Atomic Layer Plug-In

The Atomic Layer Plug-In extends the metabolic network by modeling features for the underlying atom transport layer. The atom transport layer describes the fate of individual atoms in the metabolic network. Therefore, you specify the number of atoms for each metabolite and define the atom mappings of all reactions. In combination with the Chemical Structure Plug-In you can directly model the atom mappings in combination with the actual chemical structures of the metabolites. A specific internal normalization process makes the individual atom positions in a molecule unique, reproducible and independent from the molecule's input format. By this, the atom mappings are based on well-defined atom positions in the reactant molecules.
Atom mappings can be defined for all chemical elements in a network or alternatively only for specific atom types (e.g. carbon atoms).

Using the Plug-In

After installation, the Atomic Layer Plug-In is available in the list of active plug-ins. Activate the plug-in within a network document.

Activating atomic layer
Activating atomic layer

Activation causes the features and functionality of the plug-in available in the document. This means in detail:
  • each metabolite is equipped with a property "Number of Atoms"
  • each reaction is equipped with a property "Atom Mappings"
  • an additional menu "Atomic Layer Options" is available in the Extras menu.

In order to edit atom mappings in a metabolic network an important requirement are chemical structures. Use the Chemical Structure Plug-In to equip each metabolite with a structural formula. However, chemical structures are optional. You can also create atom mappings without them. In this case, you simply specify how much atoms are available in each reactant. Nevertheless, chemical structures help to understand the meaning of the atom mappings because the actual atom positions in the molecules become evident.

The next steps are defining the number of atoms for each metabolite, specifying the atom mappings for each reaction and checking the atomic model for consistency.

1.1.1. Number of Atoms

Each metabolite has a number of atoms property which is initially zero. After clicking on the property field in the property editor the dialog window shown in the next image appeares. If no chemical structure is available for the metabolite you can only specify the number of atoms textual in the formula field. Here, you can specify the number of atoms by element (hydrogen atoms are ommitted). For instance, writing "CCC" is interpreted as three carbon atoms; C6H12O6 for six carbon and six oxygen atoms etc. A sequential representation of the atoms is shown on the drawing area in the center of the dialog editor (see left image).

Defining number of atoms without structural formula
Defining number of atoms without structural formula

If a structural formula is available, the drawing area becomes an active editor where you can select the individual atoms that shall be respected in the atom mappings. Unselected atoms are colored red, selected atoms green. You can select atoms of all elements except hydrogen. In the following picture examples atom mappings are only created for carbon atoms for the sake of ease. The formula representation in the line editor is synchronized while selecting atoms and vice versa.

Defining number of atoms with available structural formula
Defining number of atoms with available structural formula

Reactants may have no atoms. In this case they are neutral elements in the atom mappings. Extracting Number of Atoms

If structural formulas are available in the network, the number of atoms properties can be automatically loaded. Therefore, choose "Import Reactions and Metabolite Properties" in menu Extras -> Atomic Layer Options. From the provided options select "Extract Number of Atoms from Structural Formulas".

1.1.2. Atom Mappings

After specifying the number of atoms for each reactant, a reaction's atom mapping can be edited. Therefore, click the corresponding property field in the property editor. The atom mapping editor dialog shown in the next image appears where you can interactively define how the individual atoms are transported in the reaction. Similar to the number of atoms editor, the representation of the atom mapping depend on whether a chemical structure is available or not.

Defining atom mappings without structural formula
Defining atom mappings without structural formula

Without chemical structures, the included atoms are displayed sequentially. Here it comes clear that the actual position of the atoms in the molecule is an important information for defining atom mappings. Hence, it is strongly recommended to base your atom mappings on structures.

Defining atom mappings with available structural formula
Defining atom mappings with available structural formula

Initially, the educt atoms are not connected to the product atoms. Each educt atom is connected to a drag point which can be placed on a product atom. In order to define the mapping of an individual atom, take the drag point and move it onto the desired target atom. You can remove the mapping by moving a connected drag point to an arbitrary position outside the product molecule. It is also possible to exchange two mappings by moving the drag point to an already connected atom.

It is also possible to connect multiple atoms simultaneously. Therefore, drag a selection rectangle on the drawing area and by this, select a group of drag points. Now, by placing one of the drag points on a target atom all other selected drag points are moved and placed along with it. Variants

In case of symmetric molecules different ways are possible how the source atoms are mapped to the target atoms (scrambing reaction). Therefore, the atom mappings editor provides the "Variants..." button top or bottom of the reactant. By clicking on the button, a list of variants appears where you can add further entries (see image (a)). After clicking the add button, the variant editor dialog appears which looks very similar to the atom mapping editor (b). Here, you can define in what manner the new variant differs from the original (c). After adding the new variant, the mappings of the available variants can be displayed and edited (d).

(a) Atomic-Variant1.png (b) Atomic-Variant2.png

(c) Atomic-Variant3.png (d) Atomic-Variant4.png View & Editor Options

The atom mapping editor provides several options in order to ease the editing process. Each reactant molecule can be moved in the scene. Furthermore, you can use the "<->" button in order to mirror the visual representation of a structural formula. The mirrored structure is displayed with inverted stereochemistry. By this, you can place and display the molecules in a way that better corresponds to their mapping (e.g. in a splitting reaction) and makes interpretation easier (cf. images below). Another option is to hide individual educts or products from the atom mapping representation which reduces the visual complexity.

If the atom mapping of different elements is modeled you have furthermore the option to hide all atoms of certain elements in order to reduce complexity. Furthermore, it is possible to display the atoms and connections in element colors.

Default view on atom mappings
Default view on atom mappings

Displaying mappings in CPK atom colors
Displaying mappings in CPK atom colors

Displaying only mappings of oxygen atoms
Displaying only mappings of oxygen atoms

1.1.3. Network Validity Check

The Atomix Layer Plug-In can check the entire atomix network for inconsistencies. An inconsistency is
  • an empty atom mapping when at least one reactant has one or more atoms
  • missing atom connections in an atom mapping (incl. all different variants)
  • mismatching number of educt and product atoms
  • an atom mapping that maps more or less atoms than the number of educt and product atoms
  • mismatching elements of mapped atoms
Validity check button
Validity check button

All occurring inconsistencies are displayed in a list. By clicking on an individual error message, the corresponding reaction is highlighted in the network.

1.2. Displaying Atom Mappings in the Diagram

There are multiple ways to visualize atom mappings in the network diagram:

  • visualization on demand
  • using a self painting property to fill the item's background
  • using an accessory to visualize the structure
  • visualizing the entire atom mapping network in 3D

1.2.1. Visualization on Demand

The view mode of the diagram editor provides the option to interactively visualize properties of individual network components on mouse hover. Refer to the Omix User Manual in order to read about "Visualization on Demand".

1.2.2. Self Painting Property

Instead of filling the shape of an item with color, texture or gradient brush you can choose a property to be painted in the items background. Edit a reaction's fill paint property, choose the "Property Reference" tab and select the property "Atom Mapping". This causes the atom mapping, to be painted as shape content if available. In order to use this mechanism for all reactions in the diagram configure the reactions' default fill paint property for the entire network.

Another way to use this feature is to insert a GraphicsItem in the diagram, assign an atom mapping as custom property and referencing this property as fill parameter:

omix.atomic.AtomMapping atomMapping = ... 
GraphicsItem item = getGraphicsItem("itemID");
item.setCustomProperty("atomMapping", atomMapping);
item.paint = new PaintedProperty("atomMapping", null, null);

1.2.3. Visualizing Accessory

Edit the document's OVL code and add following lines:

extend Reaction{
	ObjectField<omix.atomic.AtomMapping> atomMappingField : void;
		atomMappingField.value = (omix.atomic.AtomMapping)OmixApplication.readField("omix.atomic", this, "atomMapping");

The code extends each reaction symbol and adds an ObjectField. An ObjectField displays its content beside the network item if possible. The content in this case is "omix.atomic.AtomMapping" which is the internal type name for atom mappings. The atom mapping property provided by the plug-in is called "atomMapping" stored in namespace "omix.atomic". In line 3, the command OmixApplication.readField(...) reads the atom mapping property and stores its content in the ObjectField where it is then visualized. The block between line 2 and 4 represents an initializer that is invoked when the code is first applied in the network. You can also use the code in line 3 in other code segments.

1.2.4. 3D Visualization

CumoVis is a plug-in for Omix as an extension of the Atomic Layer Plug-In. In CumoVis, the entire network of atom mappings can be visualized in 3D.

1.3. Model Output

The Atomic Layer Plug-In plays an important role in the plug-in collection of the Fluxomix Suite for Metabolic Flux Analysis.
Here, the atom mappings can be exported to FluxML, the model specification of 13CFLUX2, and serve as basis for the simulation of carbon labeling experiments.

If you require a way to import or export atom mappings that is currently not yet supported (file formats, databases etc.) please contact us.