Analysis and manipulation

This chapter describes operations that are used to analyze molecular systems and to apply specific manipulations.

• Properties of chemical objects and collections
• Operations on peptide chains and proteins
• Operations on nucleotide chains
• Surfaces and volumes
• Energy evaluation
• Operations on universes

Many operations access and modify various properties of an object. They are defined for the most general type of object: anything that can be broken down to atoms, i.e. atoms, molecules, collections, universes, etc. All operations are methods to be called on an object. Only operations not already treated in the section "Analyzing and modifying coordinates" are described here.

• numberOfAtoms() returns the number of atoms in the object.
• atomList() returns a list of the atoms in the object.
• atomCollection() returns a collection of the atoms in the object.
• mass() returns the total mass of all atoms in the object.
• temperature() returns the temperature of the object. An optional argument indicates a universe velocity variable (default is the current velocity set).
• momentum() returns the momentum of the object. An optional argument indicates a universe velocity variable (default is the current velocity set).
• angularMomentum() returns the angular momentum of the object. Two optional arguments indicate a universe velocity variable (default is the current velocity set) and a universe configuration variable (default is the current configuration).
• charge() returns the total charge of the object. This function is available only if the object is in a universe with a force field that supports atomic charge calculation.
• dipole() returns the total dipole moment of the object. An optional argument specifies the reference point; the default is the center of mass. This function is available only if the object is in a universe with a force field that supports atomic charge calculation.
• writeToFile(filename) writes the object to a file. Optional arguments are a universe configuration variable (default is the current configuration) and a string indicating the file format as either 'pdb' (default) or 'vrml'.
• view() displays the object by running an external visualization program. This method is equivalent to the function view(object) described elsewhere.
• universe() returns the universe to which an object belongs. It returns None if the object belongs to no universe.

Some additional operations are available only for all chemical objects (atoms, molecules, etc.):

• fullName() returns the full name of the object, i.e. including the names of all parent objects.
• topLevelChemicalObject() returns the top-level chemical object of which the object is a part.

Other operations are defined only for collections and universes:

• map(function) applies the function to all chemical objects in the collection. The result is a collection if the return values are chemical objects, otherwise it is a list.
• objectList() returns a list of all chemical objects in the collection.

Collections and universes can also be used as sequence objects, i.e. len() returns the number of chemical objects they contain, indexing extracts individual chemical objects, and for-loops can be used to iterate over the objects.

A number of operations defined on proteins or peptide chains make use of the special structure of these objects. Of course, peptide chains are special molecules, and proteins are special complexes; therefore, all the operations on the basic types are also available for peptide chains and proteins.

The following methods are defined on peptide chains and proteins:

• residues() returns a collection of all residues.
• residuesOfType(types) returns a collection of all residues whose type (the three-letter amino acid name) is in the list of types supplied as argument.
• backbone() returns a collection of all peptide groups.
• sidechain() returns a collection of all sidechain groups.
• phiPsi() returns a tuple (phi, psi) of backbone dihedral angles for each residue.

Peptide chains have three additional methods:

• sequence() returns the amino acid sequence as a list of three-letter residue names.
• replaceResidue(old, new) replaces residue old (a residue object, which must be in this peptide chain) by residue new (also a residue object, which however may not be in any peptide chain).
• findHydrogenPositions() determines the positions of hydrogen atoms which are undefined in the current configuration. It uses a heuristic method based on typical configurations for amino acids; it does not make use of any force field.

Proteins offer the method setConfiguration(configuration), which sets the current configuration of the protein. The parameter must be either a PDB configuration read from a PDB file, or a filename indicating a PDB file from which the configuration is to be read.

Both proteins and peptide chains are sequence objects, i.e. they can be asked for their length, asked for a specific element, and iterated over with a for-loop. The items of a protein are its chains; the items of a peptide chain are the residues, starting at the C terminus.

Like peptide chains, nucleotide chains provide certain operations related to their special structure, in addition to the general operations on molecules.

The following methods are defined on nucleotide chains:

• sequence() returns the nucleic acid sequence as a list of two-letter residue names.
• residues() returns a collection of all residues.
• residuesOfType(types) returns a collection of all residues whose type (the two-letter nucleic acid name) is in the list of types supplied as argument.
• bases() returns a collection of all bases.
• findHydrogenPositions() determines the positions of hydrogen atoms which are undefined in the current configuration. It uses a heuristic method based on typical configurations for nucleic acids; it does not make use of any force field.
• setConfiguration(configuration) sets the current configuration of the protein. The parameter must be either a PDB configuration read from a PDB file, or a filename indicating a PDB file from which the configuration is to be read.

Nucleotide chains are sequence objects, i.e. they can be asked for their length, asked for a specific element, and iterated over with a for-loop. The items of a nucleotide chain are the residues, starting at the 5' terminus.

Surfaces and volumes can be analyzed for any collection of atoms. Both quantities are defined by assigning a radius to each atom; the surface of the resulting conglomerate of overlapping spheres is taken to be the surface of the atom group. Atom radii for surface determination are usually called "van der Waals radii", but there is no unique method for determining them. MMTK uses the values from A. Bondi, van der Waals Volumes and Radii, J. Phys. Chem. 68 (1964), p. 441-451. However, users can change these values for each individual atom by assigning a new value to the attribute "vdW_radius".

The method surfaceAndVolume() returns the surface and its enclosed volume as a tuple. An optional argument specifies a probe radius, i.e. a radius added to each atom radius before the calculation. Its default value is zero. The method surfaceAtoms() (also with an optional probe radius argument) returns a dictionary whose keys are the surface atoms and whose values are the exposed surface areas of the individual atoms.

A related operation is the determination of contacts between two groups of atoms. The method findContacts(other_group) returns a list of contacts. Two optional arguments determine which distances are counted as contacts: a factor f (default 1) and an offset o (default 0). Two atoms are considered to form a contact if their distance is less than f*(r₁+r₂+o), with r₁ and r₂ being the van der Waals radii of the two atoms. Each contact is described by a special two-element sequence object (containing the two atoms) that defines an order relation between contacts based on the interatomic distance.

Energy evaluation requires a force field, and therefore all the methods in this section are defined only for universe objects. However, they all take optional arguments (anything that can be broken down into atoms) that indicate which subset of the energy terms is to be evaluated. No arguments means all terms, one argument means all terms within the group specified by it, and two arguments mean all terms between the two groups specified.

• energy() returns the energy for the current configuration.
• energyAndGradients() returns the energy and energy gradients for the current configuration. The gradients are returned as a variable object.
• energyAndForceConstants() returns the energy and force constants (second derivatives) for the current configuration. The force constants are returned as a variable object.
• energyGradientsAndForceConstants() returns the energy, the energy gradients, and the force constants (second derivatives) for the current configuration. The gradients and force constants are returned as a variable object.
• energyTerms() returns the energy for the current configuration as a dictionary of the individual force field terms.

• distanceVector(o1, o2) returns the vector from the center of mass of object o1 to the center of mass of object o2. An optional third argument specifies a configuration variable; default is the current configuration.
• distance(o1, o2) returns the distance from the center of mass of object o1 to the center of mass of object o2. An optional third argument specifies a configuration variable; default is the current configuration.
• angle(o1, o2, o3) returns the angle at the center of mass of o2between the directions pointing toward the centers of mass of o1 and o3. An optional fourth argument specifies a configuration variable; default is the current configuration.
• dihedral(o1, o2, o3, o4) returns the dihedral angle between the planes (o1, o2, o3) and o2, o3, o4 along the axis o2-o3. An optional fifth argument specifies a configuration variable; default is the current configuration.

• configuration() returns the universe variable containing the current configuration. To store the current configuration before it is changed by some operation, it is necessary to make a copy of the current configuration.
• velocities() returns the universe variable containing the current velocities. To store the current velocities before they are changed by some operation, it is necessary to make a copy of the current velocity variable.
• velocities() returns the universe variable containing the atomic masses.
• atomNames() returns a list of the full names of all atoms, sorted like universe variables (configuration, velocities, etc.).
• setConfiguration(configuration) copies the configuration specified into the current configuration.
• setFromTrajectory(trajectory, step_number) sets the current configuration and velocities (if availble) to the values taken from a certain step in a trajectory file.
• renumberAtoms(number_list) changes the atom indices used in universe variables according to the supplied list of integers.