Data Type: Molecule ()

Description:

An object of data type Molecule contains information about the structure of the molecule. Typical information that is stored are the types and positions of the molecule's atoms and the bonds between the atoms, plus the type of each bond. Furthermore, the data object stores information about groups of atoms in a hierarchical way. For example a functional group consists of a number of atoms, several functional groups may form a residue, and a couple of residues may form a secondary structure. This allows quick traversal of the molecule's structure.

Molecules can be loaded from a file or generated by several global tcl commands. They can be edited by either using some of the data objects tcl commands which are described in the following sections or by using the Molecule Editor, Attribute Editor, or Data Editor.

Molecules can be visualized with the following viewing modules: Molecule View, Bond Angle View, Secondary Structure View, or Tube View. In addition, there are two modules for generating molecular surfaces. The Generate Molecular Surfaces module enables you to generate the solvent accessible, solvent excluded, and van der Waals surfaces of a molecule. The Generate Molecular Interface module can be used to generate intra- and intermolecular interfaces, such as between single atoms or residues, or between two molecules, respectively.

When comparing the structures of several molecules with each other, one is faced with the problem of aligning molecules to each other. This can be easily done by connecting the AlignMaster connection port to a second molecule which will serve as reference. There are several alignment modes. If the molecules have the same number of atoms you can align the two molecules to each other by using all atoms, whereby the i'th atom of the first molecule corresponds to the i'th atom of the second molecule. You can also select atoms in either the slave or the master molecule. The slave is the molecule to be aligned. If the molecules have different numbers of atoms, the only way to align molecules is to select atoms in both molecules.

Connections:

Data [optional]
The molecule may be connected to a molecular dynamics trajectory. If so, a Time port will appear in the Properties Area which enables you to load new time steps into the molecule.

Time [optional]
Sometimes it is necessary to synchronize two or more time-dependent data objects, such as a molecule from a trajectory and the corresponding electrostatic field. In this case, the Time port can be connected to a Time object.

AlignMaster [optional]

PrecomputedAlignment [optional]
You find the description of the two ports above are described in the section on alignment of molecules.

Ports:

Time

The Time port is visible only if the molecule object is time dependent, i.e., it is connected to a molecular dynamics trajectory. In the slider you can select a specific time step. If you wish to step through the trajectory, use the buttons next to the slider. For continuous animation, use the outer buttons.

Alignment



You will find the description of the above three ports in the section on alignment of molecules.

Selection Browser

Press this button if you wish to open the selection browser for this molecule.

Transform

If you want to transform all atom coordinates of the molecule by the current transformation in order to save the molecule with the transformed coordinates to a file, press the Apply button. As long as the Transform Editor is active you can also undo your actions.

Commands:

You can use the console window for entering additional commands for molecules. The easiest way to use the console for a molecule is to click on the molecule object in the Project View and then press the TAB key in the console window to display the name of the selected object. After the name you can use the following selection commands:

list
Lists all levels defined for the molecule.

list <levelName>
Lists all groups of level levelName.

list <levelName/[groupName|groupRange]>
Prints information about a single group or multiple groups specified by a group range.

define <levelName/groupName> <groups>
This command defines a new group groupName in the level levelName. If levelName does not yet exist, it will be added as a new level. groups is a list of groups of possibly different levels. Groups can be specified using ranges.
Example: The following command defines group one in level test consisting of atoms 1 and 3 and residues 4 to 6.

define test/one atoms/1 atoms/3 residues/4-6 

defregexp <levelName/groupName> <atomExpr>
Define a new group by using atom expressions. The new group will only contain atoms, i.e., no higher level groups.

applyTransform
The current transform is applied to the molecule, i.e., the original atomic positions are replaced by the transformed positions.

generateSmiles
Returns SMILES string of molecule.

alignBySmartsMatching
Aligns molecule to <mol2> by first matching the given smarts string to both molecules and then using this matching for computing the transformation yielding the lowest rmsd between the matched groups. If either of the molecules did not have a matching nothing will be done and 0 is returned. Else 1 is returned.

computeRMSD
Returns the root mean square distance between the molecule and another molecule. The molecules must have identical topologies (this means the sequence of the atoms must be identical too).

savePQR
Saves the molcule in PQR format (pdb format with added partial charges and radii). If no attribute names are supplied as parameters, the default values 'charge' and 'radius' will be used.

getMolWeight
Returns the molecular weight of the molecule. The computation will consider implicit hydrogens in the atoms/implicit_hnum attribute.

Viewer Commands:

The following commands allow connecting different kinds of viewer modules to the molecule from the command line:

showSurface
Creates Generate Molecular Surfaces and Molecule Surface View modules to show the molecular surface. No return value.

showSticks
Creates a MolecuelView module to show the molecule in sticks representation. No return value.

showHBonds
Creates a HBondsView module to show all hydrogens bonds. No return value.

showHBondsTo
Create a new molecule in the Project View containing all hyrdogens bonds between molecule and molecule2. A H Bond View will be connected to this molecule to show the hydrogen bonds. Returns name of new molecule.

Selection Commands:

showBroswer
Shows the selection browser. No return value.

sel <atomExpr>
Lets you add atoms specified by atomExpr to the current selection.
Example: The following command will select all carbon atoms which are located in helices.

 sel a=C AND s/type=helix 

There is also a global command 'sel' which applies the atom expressions to all molecules in the Project View.

desel <atomExpr>
Lets you remove atoms from the selection. Like for 'sel' there is also a global 'desel' command operating on all molecules.

selAtom <atomIx>
Selects atom with given index.

deselAtom <atomIx>
Deselects atom with given index.

isAtomSelected <atomIx>
Returns 1 if atom with given index is selected, 0 otherwise.

getNumSelection
Returns number of selected atoms.

invertSelection
Atoms which are selected will become unselected and vice versa.

selWithinSelection <objectname> <range>
Atom expressions only work on single molecule objects. This command allows the WITHIN operator of atom expressions to be used in relation to another molecule object in the Project View. The command will select all atoms that are within <range> Angstroem from any atom selected in the molecule <objectname>.

selWithinCoordinate <x> <y> <z> <range>
Will select all atoms which are within range Angstroem from the given coordinate.

expandSelectionToGroupsOfLevel <levelIx>
Will expand selection to all groups of given level for which at least a single atom is selected.

selFromFilter [<objectName>]
Selects all atoms which are not hidden in the filter of the given downstream object. If the name of the object is omitted it will select all atoms which are not hidden in any of the downstream object filters. No return value.

selToFilter [<objectName>]
Sets filter of the given object to the currently selected atoms. If the name of the object is omitted it will apply to all downstream objects. No return value.

printSelection
Prints a lists of all atoms which are selected.

printSelectionByAtoms
Same as printSelection.

printSelectionByResidues
Prints a lists of all residues which are entirely or partially selected.

printSelectionByLevel <levelName>
Prints a lists of all groups of the given level which are entirely or partially selected.

getSelectionCenter
Computes center of gravity of selected atoms and returns x,y, and z coordinate.

getSelectionBBox
Computes the bounding box surrounding all selected atoms and returns it as xmin,xmax, ymin,ymax, zmin,zmax.

addSet <name>
Adds current selection as a new group to the 'sets' level. The name attribute of the new group will have the value name. This set can be used to return to the current selection at a later time. Note that there is also a global command which will apply addSet to all molecules in the Project View.

removeSet <name>
Remove set of name name from 'sets' level. No return value.

useSet <name>
Resets selection to atoms contained in the group in 'sets' level which has the name attribute value name. No return value. Like for addSet, there is also a global useSet command.

Labeling commands:

The following command allow modifying labels of groups. They work on all downstream MolLabel modules.

setGroupLabel <levelIx> <groupIx> <label>
Attaches a label to a group. This is done by setting the label in a create MolLabel module. If no module exits, a new MolLabel will be created. No return value.

setGroupLabelSize [<levelIx>] <size>
This command works on all attached MolLabel modules and sets the font size of all labels for the given level. If the level index is omitted, it will be applied to all levels. No return value.

setGroupLabelColor [<levelIx>] <red|green|blue|yellow|white|black>
This command works on all attached MolLabel modules and sets the color of all labels for the given level. If the level index is omitted, it will be applied to all levels. No return value.

setGroupLabelColorRGB [<levelIx>] <r> <g> <b>
Same as setGroupLabelColor but instead of using a text string defining a color, the red green blue value of the color (each within the range [0,1]) is specified. No return value.

Editing levels: The following commands allow modifying the level hierarchy of the molecule. The commands work index based. Removing levels may invalidate locally stored level indices.

getLevelIx <levelName>
Returns index of level with name levelName, 0 if no such level.

getLevelName <levelIx>
Returns name of level with index levelIx.

getNumLevels
Returns number of levels.

addLevel <levelName> <referenceLevelIx>
Adds level of name levelName which references the level with index referenceLevelIx. Returns index of new level

removeLevel <levelIx>
Removes level with index levelIx. All dependant levels will also be removed. Level indices might change after using this command. No return value.

getReferenceLevelIx <levelIx>
Returns the index of the referenced level of level levelIx. Returns 0 if it does not reference another level.

Editing groups of a level: The following commands allow modifying the groups that are part of a level. The commands work index based. Removing groups may invalidate locally stored group indices.

getNumGroups <levelIx>
Returns number of groups of level with index levelIx.

getNumGroupElements <levelIx> <groupIx>
Returns number of elements of group groupIx of level levelIx.

getGroupElement <levelIx> <groupIx> <elementIx>
Returns index of elementIx'th group which is referenced by group groupIx of level levelIx.

getGroupElements <levelIx> <groupIx>
Returns list which contains indices of groups which are referenced by group groupIx of level levelIx.

removeGroupElement <levelIx> <groupIx> <elementIx>
Removes elementIx'th reference of group groupIx of level levelIx. Element indices of the group will change after using this command. No return value.

setGroupElement <levelIx> <groupIx> <elementIx> <refGroupIx>
Sets the reference of the elementIx'th element of the group groupIx of level levelIx to the group refGroupIx. No return value.

addGroupElement <levelIx> <groupIx> <refGroupIx>
Add the reference refGroupIx at the end of the of the elements of the group groupIx of level levelIx. No return value.

removeGroup <levelIx> <groupIx>
Remove the group groupIx from index levelIx. Will also remove all dependant groups and attribute entries. No return value.

removeGroups <levelIx> <groupIx1> <groupIx2> ...
Remove the given groups from level levelIx. Will also remove all dependant groups and attribute entries. No return value.

restrictToGroups <levelIx> <groupIx1> <groupIx2> ...
Remove all groups of level levelIx except for the given groups. Will also remove all dependant groups and attribute entries. No return value.

removeSelection
Remove all atoms which are selected and all dependant groups. No return value.

restrictToSelection
Remove all atoms which are not selected and all dependant groups. No return value.

copySelection
Copies the selected atoms into a new Molecule object. The label of the new object in the Project View will be returned.

splitSelection
Copies the selected atoms into a new Molecule object and removed them from the current. The label of the new object in the Project View will be returned.

addMolecule <objectname>
Adds the molecule object in the Project View with the given name.

addMoleculeSelection <objectname>
Adds all selected groups of the molecule object in the Project View with the given name.

addGroup <levelIx>
Adds group to level levelIx. Returns index of new group.

addGroupSelection <levelIx>
Adds group to level levelIx and sets its group elements to the currently selected atoms. Returns index of new group.

Editing attributes: The following commands allow modifying attributes of groups. The commands work index based. Removing attributes may invalidate locally stored attribute indices.

getNumAttributes <levelIx>
Return number of attributes of level levelIx.

getAttributeIx <levelIx> <attrName>
Return index of attribute attrName of level levelIx.

getAttributeName <levelIx> <attrIx>
Return name of attribute attrIx of level levelIx.

addStringAttribute <levelIx> <attrName>
Adds a string attribute of name <attrName> to level <levelIx>. Returns the index of new attribute. Returns 0 if not successful.

addIntegerAttribute <levelIx> <attrName>
Adds an integer attribute of name attrName to level levelIx. Returns the index of new attribute. Returns 0 if not successful.

addFloatAttribute <levelIx> <attrName>
Adds a float attribute of name attrName to level levelIx. Returns the index of new attribute. Returns 0 if not successful.

removeAttribute <levelIx> <attrIx>
Remove attribute attrIx from level levelIx. No return value.

setAttributeName <levelIx> <attrIx> <attrName>
Sets name of attribute attrIx of level levelIx to attrName. No return value.

getAttributeValue <levelIx> <attrIx> <groupIx>
Returns value of attribute attrIx of level levelIx for the group groupIx.

setAttributeValue <levelIx> <attrIx> <groupIx> <value>
Sets value of attribute attrIx of level levelIx for the group groupIx to value.

Editing coordinates: getCoordinate <atomIx>
Returns the coordinate of atom atomIx. No return value.

setCoordinate <atomIx> <x> <y> <z>
Sets the coordinate of atom atomIx. No return value.

perturbCoordinates [<max>]
Applies a random perturbation to each coordinate. The perturbation will be uniformly distributed in the range [-max,max]. If the parameter is omitted 0.001 will be used. No return value.

Editing data entries: The following commands allow modifying data entries of the molecule. The commands work either by using the data entry's index or its name. Removing entries may invalidate locally stored data indices.

setData <dataID> <value>
Adds a data entry with the given name and value. The name must contain at least one letter. If the entry already exists <dataID> can be either its name or its index and the value will be reset to the new value. No return value.

removeData <dataID>
Removes a data entry. The <dataId> may either be the entry's name or its index. No return value.

getDataValue <dataID>
Returns the value of a data entry. The <dataId> may either be the entry's name or its index.

getDataName <dataIx>
Returns the name of a data entry with the given index.

getDataIx <dataName>
Returns the index of a data entry with the given name.

getNumData
Returns the number of data entries.

Miscellaneous editing commands: addHydrogens
Add hydrogens until the valences of all atoms are saturated. No return value.

removeHydrogens
Removes hydrogens. No return value.

removeNonPolarHydrogens
Removes hydrogens on non polar heavy atoms. No return value.

splitByLevel <levelIx>
Splits molecule by putting each group of the given level into a seperate MolTrajectory. Returns the name of the Molecule Trajectory Bundle object which is created.

splitByAttribute <levelIx> <attributeIx>
Splits molecule by putting all groups of the given level that have the same attribute value into a seperate MolTrajectory. If the attribute is the index attribute of the level this command does the same as the splitByLevel command. Returns the name of the Molecule Trajectory Bundle object which is created.

cleanBonds
Some imported molecule structures have duplicate entries for the same bond. This leads to problems in some algorithms. This commands removes such duplicates. No return value.

addMMFFParameterization
Adds parameters of MMFF94 force field. No return value.

addMassAttribute [<name>]
Adds an atom attribute containing the atomic mass. Specifying the name of the new attribute is optional. If no name is given 'mass' will be used. No return value.

addRadiusAttribute [<name>]
Adds an atom attribute containing the standard van der Waals radius. Specifying the name of the new attribute is optional. If no name is given 'radius' will be used. No return value.

removeWater
Removes all water molecules and unbonded oxygens and hydrogens. No return value.

assignKekuleBondOrders
Converts all aromatic bond orders to single and double to create a kekule structure. No return value.

assignNonKekuleBondOrders
Reverses the kekule structure assignment. No return value.

computeHBonds [<maxDistDA> <minAngleDAX>]
Will create a level 'hBonds' containing potential hydrogen bonds. The optional parameters maxDistDA determines the maximum distance between donor and acceptor atom and minAngleDAX the minimum angle between donor, acceptor, and a heavy atom bonded to the acceptor. The default values are 3.9 and 120. For more fine grained control and more details look at the documentation of the Compute H Bonds module. No return value.

Protein specific editing commands:

alignToProtein <mol2>
Aligns this molecule to another molecule in the Project View with the given label. The alignment will be accomplished by residue sequence alignment with the CompSeqAlign module. Both molecules need to contain the residues/type attribute with 3 letter code amino acid types. No return value.

alignProtein <mol2>
Aligns a molecule in the Project View with the given label to this molecule. Both molecules need to contain the residues/type attribute with 3 letter code amino acid types. No return value.

applyBiomt
PDB files may contain information how to generate multimers from a single unit in BIOMT REMARK records. These records are read in as a PDB_REMARK data field. The applyBiomt command will parse all BIOMT matrices in this field, duplicate the structure, and apply the specified matrix transformations. S

appendAminoAcid <index> <terminus> <code>
Append a new amino acid to the amino acid that is the index'th group in the residues level. The type of the new amino acid must be given in the 3 letter code. Terminus must be 'C' or 'N' depending on which terminus the old index'th residue the new residue is appended. For this command to work, the atoms/type attribute must contain the pdb atom types and the residues/type and bonds/type attribute must exist. No return value.

substituteAminoAcid <index> <code>
Substitutes the amino acid that is the index'th group in the residues level with the amino acid of the given 3-letter code. For this command to work, the atoms/type attribute must contain the pdb atom types and the residues/type and bonds/type attribute must exist. No return value.

mutatePDB <mutationString>
This command acts similar as the substituteAminoAcid command except that the syntax of the substitution definition differs to make this command more easily usable with pdb proteins. The mutation string is a concatenation of the original type, the pdb index and the new type (example LYS34ASP). Both 3 or 1-letter code may be used (L34H). The index refers to the pdb_index attribute. If the original type is left out, the amino acid with the given index will be substituted regardless of type (example 34H). If the index is left out, all amino acids of the given original type will be substituted with the new type. In this latter case, 3-letter codes need to be used (example LYSASP). A set of substitutions can be applied at once by seperating them by whitespaces and enclosing the set in curly brackets (example {L23H G24S}). No return value.

getAminoAcidChirality [<index>]
Returns whether amino acid index is an 'L' or 'D' isomer. Returns 'N' if residue is not an amino acid or if required attributes are missing. If index is omitted a string containing 'L', 'D' or 'N' for each residue will be returned. For this command to work, the atoms/type attribute must contain the pdb atom types and the residues level must exist containing the amino acids.

setAminoAcidChirality <index> <chiralCode>
Sets amino acid to 'L' or 'D' isomer. For this command to work, the atoms/type attribute must contain the pdb atom types and the residues level must exist containing the amino acids. No return value.

getProteinFASTASequence
Returns the protein sequence in FASTA format for all convertible chains. The topology must have chains and residues levels and contain the attributes chains/name, residues/type, and residues/name. All residues whose name starts with 'HET' will be cut out. If a chain contains any other residues whose type cannot be converted from 3 letter code to 1 letter code, it will be skipped.