Elements

The API can handle different kinds of elements from Chemotion. It can read and write Samples, Reactions, Wellplates, and Research Plans as well as Generic Elements.

How to load Elements

Single elements can be fetched directly from the instance, whereas lists of elements must be fetched by a collection. The documentation for these methods can be found in the corresponding sections (chemotion_api.collection.Collection & chemotion_api.Instance).

Lets construct an example base on Samples. To load a single sample you can use chemotion_api.Instance.get_sample() However, to do so you need to know the exact Database Id of the Sample.

try:
    sample = instance.get_sample(3)
except requests.exceptions.RequestException as e:
    pass

To load all elements within a list use chemotion_api.collection.Collection.get_samples(). This method returns an Object of class ElementSet

class chemotion_api.elements.ElementSet(session: Connection, element_type: dict, collection_id: int | None = None, collection_is_sync: bool = False)

The ElementSet class allows you to access all elements of a type in a collection. You can iterate over them or filter them using an IRI filter.

try:
    for sample in instance.get_root_collection().get_collection('Main Test').get_samples():
        pass # DO something
except requests.exceptions.RequestException as e:
    pass

The elements are loaded lazily and always in bundles of size 10. You can increase the bundle size with the second argument of the Load method.

Alternative elements can be loaded using there JSON LD @id. Use the methode chemotion_api.Instance.get_json_ld_id() This id contains its origen host, type and DB id. The following nonsense code snippet introduces the workflow:

try:
    sample_A = instance.get_sample(3)
    sample_B = instance.get_json_ld_id(sample.json_ld['@id'])
    assert sample_A == sample_B
except requests.exceptions.RequestException as e:
    pass

The JSON LD alternative for loading lists of elements uses the the JSON LD property @type chemotion_api.collection.Collection.get_elements_of_iri() This type contains the version and the element type. The following nonsensical code snippet introduces the workflow:

try:
    sample_A = instance.get_sample(3)
    col = instance.get_root_collection().get_collection('Main Test')
    sample_list = col.get_elements_of_iri(sample.json_ld['@type'])
except requests.exceptions.RequestException as e:
    pass

Please note that not all information may be loaded when loading listed elements (through the collection). To reload all information, the load() method of the corresponding element can be used.

How to create Elements

To make a new entry in the ELN, you must first select the collection in which the element is to be created. Collection objects have the appropriate methods for creating objects.

The following methods can be used to create the standard objects. All of them have no parameters and create an empty object corresponding to its type.

The created object is not saved and must be saved explicitly so that the entry is transferred to the ELN.

• chemotion_api.collection.Collection.new_samples()

• chemotion_api.collection.Collection.new_reaction()

• chemotion_api.collection.Collection.new_research_plan()

• chemotion_api.collection.Collection.new_wellplate()

To create a generic element, the type must be specified as a parameter. Either by the human-readable label or by the system-internal name:

• chemotion_api.collection.Collection.new_generic()

• chemotion_api.collection.Collection.new_generic_by_label()

Since a sample cannot be created without a molecule (not by default at least), there is also the shortcut using the following methods

• chemotion_api.collection.Collection.new_sample_smiles()

• chemotion_api.collection.Collection.new_solvent()

And finally, all objects can be created using the IRI-based method:

• chemotion_api.collection.Collection.new_element_by_iri()

try:
    col = instance.get_root_collection().get_collection('Main Test')
    sample = col.new_sample_smiles('XXX')
    sample.save()
except requests.exceptions.RequestException as e:
    pass

How to work with Elements

All Objects have a set of common properties and methods.

class chemotion_api.elements.abstract_element.AbstractElement(generic_segments: GenericSegments, session: Connection, json_data: dict | None = None, id: int | None = None, element_type: str | None = None)

This abstract element is the basis for all chemotion-api elements. It provides all the necessary functions and properties to work with these elements. It contains. For more details check the Element classes out.

property analyses: AnalysesList

With the analyses object one can read and write all information from the analysis Tab in Chemotion.

Returns:

Analyses object

property attachments: Attachments | None

Attachment container of the element. This s None if the element has no Attachments

Returns:

Attachments container

clean_data() → dict

Takes the values from the segments object and attachment object and overwrites the json_data values accordingly.

Raises:

jsonschema.exceptions.ValidationError – If the properties ar not valid

Returns:

cleaned data

property element_type: str

is either ‘sample’, ‘sample’, ‘reaction’, ‘wellplate’, ‘research_plan’ or if the element is a generic one it is only ‘element’

Returns:

The element type

Type:

Element type

classmethod get_response_key(name: str) → str

Returns the element name used to construct the save and load URL

Parameters:

name – The name of the element type

Returns:

classmethod get_url(name: str) → str

Returns the load URL based on the element type

Parameters:

name – The name of the element type

Returns:

The load url

property id: int

Database ID of the element

Returns:

Database ID of the element

load()

Loads and parses the data of an element from the server. The standard Values can be found in the properties property or the segment

Raises:

• RequestException – If the element could not be loaded!

• ValueError – If no ID available!

property properties: dict

The properties property contains all data from the main tab of the elements in Chemotion.

Returns:

Element properties

properties_schema() → dict

Returns the JSON.org schema of the cleaned properties.

Returns:

JSON.org schema

save(load_after_save: bool = False)

Saves or creates an object according to the set properties. It overwrites the json_data entries by the values set in the segments object.

Raises:

• RequestException – If request was not successful

• jsonschema.exceptions.ValidationError – If the properties ar not valid

save_url() → str

Retrieves the save URL, which varies based on whether the element already has an ID.

Returns:

The save URL

property segments: Segment

Contains all segments (tabs) of elements in Chemotion. It contains generic elements as well as the proerties and the analyses segment

Returns:

Segment object

property short_label: str | None

The short label of en element if available

Returns:

short label of en element