Package schrodinger :: Package structutils :: Module rmsd :: Class ConformerRmsdX

Class ConformerRmsdX

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.

This is an enhanced version of ConformerRmsd where working copies of the input structures are modified instead the original. The superimpose transformation is applied to the entire test_structure. The translation and rotation matrixes are instance attributes. Debugging/verbosity is controlled by log level instead of an instance attribute.

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 = ConformerRmsdX(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 = ConformerRmsdX(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="all AND NOT atom.element H", in_place=True)

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

_encodeOriginalAtomNumbers(self, st)

_extractSuperimposeAslStructure(self, st)

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

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

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

_getRenumberedStructure(self, st)
Returns: a new structure with a normalized atom order, based upon the reference set of SMARTS patterns in self._mol_pattern_dict.

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.

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.

Instance Variables

[hide private]

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

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

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)

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.

Method Details

[hide private]

init(self, reference_structure, test_structure=None, asl_expr="all AND NOT atom.element H", in_place=True)
(Constructor)

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.

str(self)
(Informal representation operator)

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

_encodeOriginalAtomNumbers(self, st)

Parameters:

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

_extractSuperimposeAslStructure(self, st)

Parameters:

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

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:

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.

_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.

_getRenumberedStructure(self, st)

Parameters:

st (structure.Structure) - The structure to renumber.

Returns:

a new structure with a normalized atom order, based upon the reference set of SMARTS patterns in self._mol_pattern_dict.

_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)

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.

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.

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.

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.

Class ConformerRmsdX

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

__str__(self) (Informal representation operator)

_encodeOriginalAtomNumbers(self, st)

_extractSuperimposeAslStructure(self, st)

calculate(self)

_prepareStructures(self)

_getReducedStructure(self, st)

_getRenumberedStructure(self, st)

_superimpose(self, ref_st_selection, test_st_selection)

getRmsdDataname(self)

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

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

orig_index_prop

renumber_structures

use_heavy_atom_graph

use_symmetry

init(self, reference_structure, test_structure=None, asl_expr="all AND NOT atom.element H", in_place=True)
(Constructor)

str(self)
(Informal representation operator)