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

Class ConformerRmsdX

        object --+    
                 |    
_ConformerRmsdBase --+
                     |
                    ConformerRmsdX

Known Subclasses:

application.jaguar.rmsd.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)
x.__init__(...) initializes x; see help(type(x)) for signature

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

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

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

renumberWorkingStructures(self)
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 _ConformerRmsdBase: getRmsdDataname, populatePatternDict, writeCommand, writeStructures

Inherited from _ConformerRmsdBase (private): _encodeOriginalAtomNumbers, _getRenumberedStructure

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

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.

Properties

[hide private]

Inherited from object: __class__

Method Details

[hide private]

init(self, reference_structure, test_structure=None, asl_expr=`'all AND 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__

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.

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.

renumberWorkingStructures(self)

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.

Overrides: _ConformerRmsdBase._getReducedStructure

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

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

_extractSuperimposeAslStructure(self, st)

calculate(self)

_prepareStructures(self)

renumberWorkingStructures(self)

_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=`'all AND NOT atom.element H'`, in_place=True)
(Constructor)

str(self)
(Informal representation operator)