Package schrodinger :: Package structutils :: Module rmsd :: Class ConformerRmsd

Class ConformerRmsd

object --+
         |
        ConformerRmsd

Known Subclasses:

A class to calculate the root mean square deviatation between the atomic coordinates of two conformer structure.Structure objects. The inputs are expected to be conformers in the traditional sense.

Working copies of the input structures are modified instead the original. The superimpose transformation is applied to the entire test_structure. The transformation matrix is saved as superposition_matrix property if in_place is set to False.

Renumbering is achieved by creating a list of SMARTS patterns, one for each molecule in the reference structure, evaluating the SMARTS pattern with both the reference and test structures to get a standard order of atom indexes, then passing that atom order to mm.mmct_ct_reorder. Renumbering can be slow with protein-sized molecules so you may want to disable that feature when working with large molecules.

API Example:

   # Calculate in place, heavy atom RMSD.
   st1 = structure.StructureReader('file1.mae').next()
   st2 = structure.StructureReader('file2.mae').next()
   conf_rmsd = ConformerRmsd(st1, st2) # in place, heavy atom RMSD calc.
   if conf_rmsd.calculate() < 2.00:
       print "Good pose"

   # Loop over structures in test.mae, comparing to ref.mae
   st1 = structure.StructureReader('ref.mae').next()
   conf_rmsd = ConformerRmsd(st1, st1) # in place, heavy atom RMSD calc.
   for st in structure.StructureReader('test.mae'):
       conf_rmsd.test_structure = st
       print conf_rmsd.calculate()

Instance Attributes

Note: The following attributes are available after calculate()

Instance Methods

[hide private]

__init__(self, reference_structure, test_structure=None, asl_expr='NOT atom.element H', in_place=True)
x.__init__(...) initializes x; see help(type(x)) for signature

_encodeOriginalAtomNumbers(self, st)

populatePatternDict(self, st)
Populates the self._mol_pattern_dict based on the molecules in the given structure.

string

getRmsdDataname(self)
Returns: m2io property dataname string.

writeStructures(self, file_name='rmsd.mae', mode='w')
Writes the reference and test structures to file.

writeCommand(self, file_name='rmsd.cmd')
Writes a Maestro command file and structures with the pair wise atom mapping in command file mode.

__str__(self)
Returns: a user friendly string representation of the instance.

_extractSuperimposeAslStructure(self, st)

list of ints

@raise RuntimeError if ASL matching failed.

evaluateAsl(self, st)
Return the atoms of the input structure that match <asl_expr>.

calculate(self)
@return: Root-mean-squared difference of atom coordinates.

list of ints

_prepareStructures(self)
Returns: a working copy of the reference and test structures, renumbered and/or reduced as needed.

renumberBySymmetry(self)
Renumber the atoms in _working_test_st based off the reference structure ussing mmsym.

renumberWorkingStructures(self, has_hydrogens)
Renumber the working structures to give them identical numbering.

_getReducedStructure(self, st)
Returns: a Structure that is a simplified copy of the input: a neutral, single bond connected, heavy atom only frame.

tuple

_superimpose(self, ref_st_selection, test_st_selection)
Calculate optimal rotation-translation transform of test_st_selection of atoms in working_test_st onto ref_st_selection of atoms in working_ref_st, and apply to test_structure.

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __subclasshook__

Instance Variables

[hide private]

orig_index_prop = 'i_confrmsd_original_index'
m2io dataname for atomic property that stores the original atom index of the input structures.

float max_distance
Greatest displacement between the atom pairs

integer max_distance_atom_1
Reference atom index (in original atom scheme)

integer max_distance_atom_2
Test atom index (in the original atom scheme)

max_permutations
Maximum number of permutations to search defaults to 10000000

precision
Precision of rmsd stored to find minimum if search_permutations=True defaults to 6 (meaning a precision of 10^-6)

renumber_structures
Boolean to control whether the reference and test structures should be renumbered by a SMARTS pattern before calculating the rmsd.

float rmsd
Root mean square deviation of atomic coordintates

rmsd_str
String of basic rmsd info == str(self)

superposition_matrix
Matrix that was used for superimposing the test structure on top of the reference structure, if in_place=True.

use_heavy_atom_graph
Boolean to control whether the reference and test structures should be treated as heavy-atom only, graph topologies.

use_symmetry
Boolean to control whether the test structure atom list should be determined by with the mmsym library.

Properties

[hide private]

Inherited from object: __class__

Method Details

[hide private]

init(self, reference_structure, test_structure=None, asl_expr=`'NOT atom.element H'`, in_place=True)
(Constructor)

x.__init__(...) initializes x; see help(type(x)) for signature

Parameters:

reference_structure (structure.Structure) - Template structure
test_structure (structure.Structure) - The mobile structure.
asl_expr (string) - Atom Language Expression to identify the the atoms used to calculate the RMSD and base the superimpose alignment.
in_place (Boolean) - If True, calculate the RMSD without moving the test_structure. Otherwise, perform the optimal alignment then calculate the RMSD.

Overrides: object.__init__

_encodeOriginalAtomNumbers(self, st)

Parameters:

st (structure.Structure) - Structure to store original atom indexes as atom-level properties.

getRmsdDataname(self)

Returns: string: m2io property dataname string. The property name indicates the reference structure, the title, the ASL used to identify comparison atoms and if the structure is in-place or mobile.

writeStructures(self, file_name=`'rmsd.mae'`, mode=`'w'`)

Writes the reference and test structures to file.

Parameters:

file_name (string) - Path of the structure file to write.
mode (string) - 'w' => write, clobber as needed 'a' => append

writeCommand(self, file_name=`'rmsd.cmd'`)

Writes a Maestro command file and structures with the pair wise atom mapping in command file mode. The Maestro file has the same basename as the command file. Clobbers existing files.

Parameters:

file_name (string) - Path to the maestro command file with the atom pairings.

str(self)
(Informal representation operator)

str(x)

Returns:: a user friendly string representation of the instance. e.g.:
In place RMSD = 1.01; atoms = "a.e C"
Overrides: object.__str__

_extractSuperimposeAslStructure(self, st)

Parameters:

st (structure.Structure) - Structure from which to extract the ASL matching atoms.

evaluateAsl(self, st)

Return the atoms of the input structure that match <asl_expr>.

Parameters:

st (structure.Structure) - Structure to evaluate

Returns: list of ints @raise RuntimeError if ASL matching failed.

Atoms matching the ASL

calculate(self)


@return:
    Root-mean-squared difference of atom coordinates.
@type:
    float

@raise:
    ValueError if working versions of the reference and test
    structures don't have the same shape (non-confs).

The order of operations:
    * prepare working copies of the reference and test structures.
        ** copy the structures.
        ** encode the original atom indexes as atom properties.
        ** extract substructure of the atoms matching the ASL.
        ** reduce to heavy atom graph (instance option, non-default).
        ** normalize numbering scheme (instance option, default).
    * determine molecular symmetry mapping (optional, default).
    * create a numpy coordinate array for the working structures.
    * numpy linear algebra SVD to superimpose (instance option).
        ** transform test_structure
    * numpy array used to calculate RMSD, and max_dist.
    * decode original indexes to identify atoms involve in max dist.

_prepareStructures(self)

Parameters:

reference (boolean) - If true, seed the renumbering pattern dictionary.

Returns: list of ints

a working copy of the reference and test structures, renumbered and/or reduced as needed. The original atom index is saved as atom level properties in the working structure. A substructure of just the atoms specified for superposition via ASL.

renumberWorkingStructures(self, has_hydrogens)

Renumber the working structures to give them identical numbering. By default, the test structure is renumbered to match the reference using renumber_conformer() functon; but this behavior can be changed by over-riding this method in a subclass.

_getReducedStructure(self, st)

Parameters:

st (structure.Structure) - Structure to reduce.

Returns:

a Structure that is a simplified copy of the input: a neutral, single bond connected, heavy atom only frame. The returned structure is handy for making RMSD comparisons between pseudo conformers that differ by ionization state or tautomerism.

_superimpose(self, ref_st_selection, test_st_selection)

Calculate optimal rotation-translation transform of test_st_selection of atoms in working_test_st onto ref_st_selection of atoms in working_ref_st, and apply to test_structure.

Parameters:

ref_st_selection (list) - A list of 1-based atom indices to consider from reference structure.
test_st_selection (list) - A list of 1-based atom indices to consider from test structure.

Returns: tuple

(coordinate arrays in reference structure, coordinate arrays in test structure)

Instance Variable Details

[hide private]

orig_index_prop

m2io dataname for atomic property that stores the original atom index of the input structures. Default is 'i_confrmsd_original_index'. This is needed to we can extract/reduce/renumber and present information about the original index which the end-user perceives.

Value:

'i_confrmsd_original_index'

renumber_structures

Boolean to control whether the reference and test structures should be renumbered by a SMARTS pattern before calculating the rmsd. For better performance, set to False when the inputs are sure to have the same atomic numbering schemes. NOTE: Make sure use_symmetry is True if using renumber_structures.

use_heavy_atom_graph

Boolean to control whether the reference and test structures should be treated as heavy-atom only, graph topologies. Default is False. Tautomers, and different ionization states are not true conformers, but often require RMSD analysis. If True, the test_structure and reference_structure are treated by deleting all hydrogens, setting all bond orders to 1, setting all formal charges to 0, then adjusting the atom types.

use_symmetry

Boolean to control whether the test structure atom list should be determined by with the mmsym library. Mmsym accounts for molecular symmetry and is recommended. This boolean just allows for more detailed testing. NOTE: Make sure use_symmetry is True if using renumber_structures.

Class ConformerRmsd

__init__(self, reference_structure, test_structure=None, asl_expr='NOT atom.element H', in_place=True) (Constructor)

_encodeOriginalAtomNumbers(self, st)

getRmsdDataname(self)

writeStructures(self, file_name='rmsd.mae', mode='w')

writeCommand(self, file_name='rmsd.cmd')

__str__(self) (Informal representation operator)

_extractSuperimposeAslStructure(self, st)

evaluateAsl(self, st)

calculate(self)

_prepareStructures(self)

renumberWorkingStructures(self, has_hydrogens)

_getReducedStructure(self, st)

_superimpose(self, ref_st_selection, test_st_selection)

orig_index_prop

renumber_structures

use_heavy_atom_graph

use_symmetry

init(self, reference_structure, test_structure=None, asl_expr=`'NOT atom.element H'`, in_place=True)
(Constructor)

writeStructures(self, file_name=`'rmsd.mae'`, mode=`'w'`)

writeCommand(self, file_name=`'rmsd.cmd'`)

str(self)
(Informal representation operator)