S-groups

Superatom S-group

Building of Superatom S-group

Creating of SuperatomSgroup object

First, the whole molecule should be built using the Core API methods, or imported. In this example, we import it from SMILES format. Then the SuperatomSgroup is constructed with the molecule in the argument of the constructor.

        Molecule mol = MolImporter.importMol("C1=CC=CC=C1C");
        Cleaner.clean(mol, 2, null);

        // Create the Sgroups.
        SuperatomSgroup superSg = new SuperatomSgroup(mol);

Setting an S-group as the parent of its atoms

The atoms that are supposed to be a part of an S-group should be added to it (that is, set the S-group as the parent of the MolAtom). In our example, we add the carbon atoms of the benzene ring to the S-group, they are the first six atoms of the molecule.

        for (int i = 0; i < 6; i++) {
            mol.setSgroupParent(mol.getAtom(i), superSg, true);
        }

Set subscript of the S-group

In order to set subscript of a Superatom S-group, use the SuperatomSgroup.setSubscript(String) method:

       superSg.setSubscript("Ph"); 

Adding attachment points

Since Marvin 6.0, we support to add S-group attachment point only to atoms that are part of a Superatom S-group. Attachment points are represented by an object which stores its attach atom, crossing bond and order. The attach atom is one of the MolAtoms of the superatom S-group on which the attachment point is placed. The crossing bond is a bond where

• one of the end atoms is inside the Superatom S-group (this atom is called attach atom);
• the other end atom is outside the Superatom S-group.

When an attachment point is free, the crossing bond is null, further crossing bond addition is possible. The order is an integer greater than zero defining the priority of the attachment point. When a bond is added to a contracted superatom S-group, it occupies a free attachment point with the lowest order.

To add an attachment point, use one of the following methods:

• SuperatomSgroup.addAttachmentPoint(MolAtom);
• SuperatomSgroup.addAttachmentPoint(MolAtom, int order);

In the first case, the smallest unused number is set as order.

Crossing bond can be added to an attachment point by invoking SuperatomSgroup.addCrossingBond(MolAtom attachAtom, MolBond crossingBond) method. However, the crossing bond information is updated automatically by Molecule.add(MolBond bond) method.

Note, that the method MolAtom.setAttach(int) is deprecated, and its usage is not recommended any more.

Calculate the attachment points

By invoking SuperatomSgroup.calculateAttachmentPoints(), attachments points are put to atoms in the superatom S-group that have bond which other end atom is outside the group (crossing bond). It is useful when the superatom S-group is created using the SuperatomSgroup.setSgroupGraph() method.

Getting the attachment point information

Attachment point information of a superatom S-group can be received by calling method SuperatomSgroup.getAttachmentPoints(). The result is an java.util.ArrayList of AttachmentPoint objects from the superatom S-group. The list is sorted by increasing attachment point orders.

Note, that the method MolAtom.getAttach() is deprecated, and its usage is not recommended any more. The orders of the attachment points located on a given atom can be obtained by invoking method SuperatomSgroup.getAttachmentPointOrders(MolAtom). It returns the ArrayList<Integer> of attachment point orders located on the given MolAtom.

Leaving group

A leaving group atom can be defined to each attachment point. That atom is in the molecule when the attachment point is free and disappear when a crossing bond is bound to that attachment point ("leaves the molecule").

In the example above the leaving groups on the N-terminal of Alanine, on the C-terminal of Cystein as well as on its Sufur atom is visible. Due to the bond between the two amino acid, the leaving group on the Alanine C-terminal and on the Cystein N-terminal is outside the molecule.

Leaving group information can be set to an attachment point using the following methods:

• SuperatomSgroup.setLeavingGroup(int order, int atNo);
• SuperatomSgroup.setLeavingGroup(int order, int atNo, String alternativeName);
• SuperatomSgroup.setLeavingGroup(int order, int atNo, String alternativeName, BondType crossingBondType);

In the argument of these methods, the

• order is order of attachment point which the leaving group is set to;
• atNo is atomic number of the leaving group atom;
• alternativeName is an other name of the leaving group which is possible to be set. For example, the terminal leaving groups of a DNA chain may have alternative name 3' and 5'. By default, this string is null.
• The crossingBondType defined type of the bond connecting the leaving group with its Superatom S-group. This also determines the bond type of the crossing bond. By default, the crossingBondType it is a single bond. The type of this bond is allowed to be changed, using method MolBond.setType(int) only when the leaving group is the molecule, that is, when no crossing bond is attached.

We provide methods to obtain leaving group information in the AttachmentPoint class.

• AttachmentPoint.getLeavingGroupAtom();
• AttachmentPoint.getLeavingGroupAlternativeName();
• AttachmentPoint.getCrossingBondType();

The method SuperatomSgroup.removeLeavingGroup(order) removes the leaving group permanently from the molecule.

Methods Molecule.add(MolBond) and Molecule.removeBond() handles automatically the leaving group removal and addition to the molecule.

Full example of building of polystyrene can be found at the Code examples.

Expanded, contracted state

• All represented atoms are present in the parent molecule in all expandable S-group independently from their expansion state. Here we can see a special S-group state called Sgroup.XSTATE_XC where the S-group remembers its previous contracted state but the represented atoms were moved to the molecule graph and the abbreviation (SgroupAtom) was removed from the molecule graph. Set this state on all Sgroups by calling Molecule.setGUIContracted(false) or by calling Sgroup.setGUIStateRecursively(false) individually on Sgroup-s. Example for a typical usage is a non-GUI related API based calculation where we need the represented atoms in the molecule graph instead of the abbreviation.
• Either the abbreviation (SuperAtom) or the represented atom set is exclusively present depending on the state of the S-group. In the case of expanded S-groups (called Sgroup.XSTATE_X) the represented atoms are present in the parent molecule. In the case of contracted S-groups (called Sgroup.XSTATE_C) the abbreviation (SgroupAtom) is present in the parent molecule. Set this state on all Sgroups by calling Molecule.setGUIContracted(true) or by calling Sgroup.setGUIStateRecursively(true) individually on Sgroup-s.

Note:
When Molecule.isGUIContracted() returns true and afterwards you call:

Molecule.setGUIContracted(false);
Molecule.setGUIContracted(true);

the second setGUIContracted call will restore the state before the first setGUIContracted call!

Amino acid S-groups

AminoAcidSgroups are special SuperAtomSgroups to represent amino acids. The construction of these groups are exactly the same as the SuperatomSgroups. There are two additional attributes - the one letter and the three letter name of the amino acid.

Repeating unit S-groups

Repeating unit S-groups are used to represent polymers and other repeating units.

In order to construct a repeating unit S-group object, use its constructor as

	RepeatingUnitSgroup repeatingSg = new RepeatingUnitSgroup(Molecule mol,
		String connectivity, int type); 

The parameter Molecule object will be the parent of the S-group repeatingSg. The String connectivity defines way the units connects to each other: "ht", for head-to-tail; "hh", for head-to-head, and "eu" for either/undefined polymers. The type of the S-group can be defined using the following constants:

• Sgroup.ST_ANY,
• Sgroup.ST_SRU,
• Sgroup.ST_COPOLYMER,
• Sgroup.ST_CROSSLINK,
• Sgroup.ST_GRAFT,
• Sgroup.ST_MODIFICATION.

Atoms and bonds can be added to a repeating unit S-group in a same way as to a Superatom S-group.

The generateBracketCoord method of the CleanUtil class generates brackets. As parameter the S-group and the bracket type, square or round, should be added:

	CleanUtil.generateBracketCoords(repeatingSg, MBracket.T_SQUARE);

The end groups of polymers are often unknown or unspecified which are represented by star atoms (*). Star atoms are defined with the

	repeatingSg.addStarAtoms();	

method.

Full example of building of polystyrene can be found at the Code examples.