Class ConformerRmsd

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,
and the input atoms may be reindexed to provide a natural mapping.

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.


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

These attributes are available after calculate()
rmsd = Root mean square deviation of atomic coordintates (float)
max_distance = greatest displacement between atom pairs (float)
max_distance_atom_1 = reference atom index (in new scheme if renumbering)
max_distance_atom_2 = test atom index (in new scheme if renumbering)
rmsd_str = string of basic rmsd info == str(self)

.. attribute:: 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.

.. attribute:: 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.  Currently, the
    renumbering routine may reorder the molecules in multi-molecule
    structures as a side effect; setting extract=True may workaround
    potential problems with molecule-specific ASL expressions and
    the molecule reodering issue.

use_heavy_atom_graph=False
    Boolean to control whether the reference and test structures
    should be treated as heavy-atom only, graph topologies.
    Tautomers, and different ionization states are not true
    conformers, but often require RMSD analysis.  If True, prior
    to renumbering, 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.

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

extract=False
    Boolean to control whether the reference and test structures
    should be reduced to just those atoms matching the ASL expression.
    This speeds up calculations involving large structures, when
    only a small portion is needed for the RMSD.  e.g. reference is
    ligand file and test file contains receptor-ligand complexes.
    This option is also useful for comparing a shared substructure
    found in non-conformers.  e.g. create substructure conformers
    from non-conformers on the fly.

verbose=False
    Boolean to enable debugging print statements.

Raises exceptions if a preparation step can't be completed, or if
the input structures can't be handled as conformers.

reference_structure (structure.Structure)
    The reference conformer structure.

test_structure (structure.Structure)
    The test conformer structure.  The reference_structure is
    used if test_structure is None.

asl_expr (string)
    The Atom Selection Language (ASL) expression used to identify
    the atom indexes to be compared.  The default is 'all AND
    NOT atom.element H'.

in_place (boolean)
    Boolean to control whether the test structure should be
    transformed onto the reference structure before calculating.
    If in_place is False, the test structure is moved.
    The default is True, do the calculation in place.

Writes the reference and test structures to file.

file_name (string)
    Path of the structure file to write.

mode (string)
    'w' => write, clobber as needed
    'a' => append

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.

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

Raises ValueError if file_name does not have '.cmd' extension.