schrodinger.comparison.atom_mapper module¶

implementation of atom mapper used to perform comparisons and get atom mappings

class schrodinger.comparison.atom_mapper.MapScore(score, atom_map, reord_st)¶

Bases: tuple

atom_map¶: Alias for field number 1

reord_st¶: Alias for field number 2

score¶: Alias for field number 0

schrodinger.comparison.atom_mapper.discard_lewis_data(st: Structure) → Structure¶

Get a copy of a structure with the Lewis data discarded.

Necessary to get correct chirality labels calculated for connectivity-based Atom Mappers.

Parameters:: st – Structure to get remove Lewis data from
Returns:: structure with Lewis data discarded

class schrodinger.comparison.atom_mapper.BaseAtomMapper(optimize_mapping: bool, debug: bool = False)¶

Bases: object

Base class for an atom mapper which reorders atoms in a Structure instance using graph isomorphism as implemented in networkx.

This class can be used to easily construct atom mapping algorithms and/or to determine if two structures are conformers. The essential features of implementing a new algorithm are to define an atom type (graph invariant) which identifies nodes and a method to score particular atom mappings. For more control one can also define new methods for creating and comparing graphs.

Once the abstract methods have been implemented in a subclass (call this MyAtomMapper for example) the mapper can be used to reorder the atoms of two structure instances such that there is an one-to-one correspondence between atom i in the first and second structure. That is, the atom map is applied to the structure:

mapper = MyAtomMapper(optimize_mapping=True)
st1, st2 = mapper.reorder_atoms(st1, range(1, st1.atom_total + 1),
    st2, range(st2.atom_total + 1))

or two determine if the two structures are conformers:

are_conformers = mapper.are_conformers(st1,
    range(1, st1.atom_total + 1), st2, range(st2.atom_total + 1))

ATOM_TYPE = 's_m_custom_atom_type'¶

MAPPER_INDEX = 'i_m_atom_mapper_index'¶

__init__(optimize_mapping: bool, debug: bool = False)¶

Parameters:

optimize_mapping – if True search all possible bijections to deliver the one with the lowest score. if False, an arbitrary bijection (the first found) is returned.
debug – print extra debugging information

abstract initialize_atom_types(st: Structure, invert_stereocenters: bool = False)¶

Initialize the atom types This method typically calls set_atom_type to store the atom types

Parameters:

st – structure containing atoms to initial type of
invert_stereocenters – whether or not R/S labels should be flipped

get_atom_type(at: StructureAtom) → str¶

This value is used as an atom property

Parameters:: at – atom we wish to obtain a type for
Returns:: string which identifies atom type

set_atom_type(at: StructureAtom, value: str)¶

Set the value of the atom type

Parameters:

at – atom we wish to set type for
value – set the type of atom to this

abstract score_mapping(st1: Structure, st2: Structure, atset: Set[int]) → MapScore¶

Scores a particular atom reordering.

Parameters:

st1 – first structure
st2 – second structure
atset – the atoms which have been mapped. This may be a subset of the atoms in the two structures as we test partial as well as full maps.

Returns:

any metric which measures the goodness of a particular relative atom ordering in st1 and st2. Can be any type that has the less than operator implemented. We will assume this is a MapScore.

score_is_equivalent(score1: float, score2: float) → bool¶

This defines if the two scores are actually equal. This helps to resolve machine dependent atom mappings in which two scores are very close to being equal but are not numerically equal. If this is an issue the this method can be implemented to return True if the two scores are within some numerical threshold and should be considered equal even if the less than operator considers them to not be equal.

for example if the two scores are 1.2e-8 and 1.4e-8 you may want to consider this method returning True.

Parameters:

score1 – the first score
score2 – the first score

early_stop(score: float) → bool¶

Check if score is such that we should abort the atom_mapper early.

Parameters:: score – score to check for early stopping condition
Returns:: If True, AtomMapper should stop early. By default, we will not have an early stopping condition

unique_job_name(base_name: str) → str¶

Add an integer to the end of the base_name to get a unique name.

Parameters:: base_name – base job name
Returns:: unique name

st_to_graph(st: Structure, atset: Set[int]) → Graph¶

Convert Structure instance to a networkx Graph using _StructureAtom instances as nodes and adding an atom type property

Parameters:

st – the structure to convert
atset – a set of atoms to use to create the graph

Returns:

networkx Graph

comparator(d1: Dict, d2: Dict) → bool¶

Comparison function to be used to determine if two nodes on graph are equivalent.

If this method is not used when constructing a GraphMatcher, node attributes will not be considered for the purpose of determining isomorphism.

Parameters:

d1 (dict) – key=value dictionary from graph returned from st_to_graph which represents node 1
d1 – key=value dictionary from graph returned from st_to_graph which represents node 2

Returns:

boolean indicating equilvalence

isomeric_atom_sets(st1: Structure, atset1: Set[int], st2: Structure, atset2: Set[int]) → bool¶

Check that the atom types in atset1 are the same as those in atset2. If not, the two structures cannot be conformers.

Parameters:

st1 – the first structure
atset1 – set of atom indexes defining the first substructure
st2 – the second structure
atset2 – set of atom indexes defining the second substructure

Returns:

a boolean indicating if these atom lists are isomeric

are_consistently_ordered_conformers(st1: Structure, st2: Structure, atlist: List[int]) → bool¶

Determine if two substructures are consistently ordered conformers. That is, they have the same atom numbering and bonding

Parameters:

st1 – the first structure
st2 – the second structure
atlist – list of atom indexes defining the substructure

Returns:

boolean indicating whether or not the two structures are ordered conformers

invert_chirality(ch_list: List[str])¶

Invert the chirality (R/S) of an input list of chiralities.

Parameters:: ch_list – list of chirality labels for a structure

are_conformers(st1: Structure, atlist1: List[int], st2: Structure, atlist2: List[int]) → bool¶

Determine if the two substructures, as defined by the atom lists, are conformers but do not explore isomorphisms.

Parameters:

st1 – the first structure
atlist1 – list of atom indexes defining the first substructure
st2 – the second structure
atlist2 – list of atom indexes defining the second substructure

Returns:

boolean indicating whether or not the two structures are conformers

are_enantiomers(st1: Structure, atlist1: List[int], st2: Structure, atlist2: List[int]) → bool¶

Determine if the two substructures, as defined by the atom lists, are enantiomers but do not explore isomorphisms.

Parameters:

st1 – the first structure
atlist1 – list of atom indexes defining the first substructure
st2 – the second structure
atlist2 – list of atom indexes defining the second substructure

Returns:

boolean indicating whether or not the two structures are conformers

reorder_structures(st1: Structure, atlist1: List[int], st2: Structure, atlist2: List[int], invert_stereocenters: bool = False) → Tuple[Structure, Structure]¶

Reorder the atoms in the two structures.

Parameters:

st1 – the first structure
atlist1 – list of atom indexes defining the first substructure
st2 – the second structure
atlist2 – list of atom indexes defining the second substructure
invert_stereocenters – If True, flip all R<->S, used for are_enantiomers

Returns:

the two structures with structure 2 having had atoms reordered

class schrodinger.comparison.atom_mapper.ConnectivityAtomMapper(use_chirality: bool)¶

Bases: BaseAtomMapper

Used by comparison.py for comparison of conformers. Uses element types and optionally chirality to equate atoms and all bonds are considered equivalent.

Usage example: mapper = ConnectivityAtomMapper(use_chirality=False) st1, st2 = mapper.are_conformers(st1, range(1, st1.atom_total + 1), st2, range(st2.atom_total + 1))

__init__(use_chirality: bool)¶

Parameters:: use_chirality – if True, in addition to element type use chirality (where defined) to equate atoms.

initialize_atom_types(st: Structure, invert_stereocenters: bool = False)¶

Initialize the atom types

Parameters:

st – structure containing atoms
invert_stereocenters – whether or not R/S labels should be flipped

score_mapping(st1: Structure, st2: Structure, atset: Set[int])¶

Score a mapping over the atoms in atset. This class is not intended for atom mapping problems and so will raise a NotImplementedError

Parameters:

st1 – first structure
st2 – second structure
atset – set of atoms that have been mapped (indexes refer to both structures)

Raise:

a NotImplementedError since this function is not intended for the use case of this class

score_is_equivalent(score1: float, score2: float) → bool¶

determines if score should be considered equivalent

Parameters:

score1 – the first score
score2 – the second score

class schrodinger.comparison.atom_mapper.LewisAtomMapper(use_chirality: bool)¶

Bases: BaseAtomMapper

Used by comparison.py for comparison of conformers. Uses element types, formal charge, number of neighbors and total number of bonds to distinguish atoms. Optionally uses chirality to equate atoms

Usage example: mapper = LewisAtomMapper(use_chirality=False) st1, st2 = mapper.are_conformers(st1, range(1, st1.atom_total + 1), st2, range(st2.atom_total + 1))

__init__(use_chirality: bool)¶

Parameters:: use_chirality – if True, in addition to element type use chirality (where defined) to equate atoms.

initialize_atom_types(st: Structure, invert_stereocenters: bool = False)¶

Initialize the atom types

Parameters:

st – structure containing atoms
invert_stereocenters – whether or not R/S labels should be flipped

score_mapping(st1: Structure, st2: Structure, atset: Set[int])¶

Score a mapping over the atoms in atset. This class is not intended for atom mapping problems and so will raise a NotImplementedError

Parameters:

st1 – first structure
st2 – second structure
atset – set of atoms that have been mapped (indexes refer to both structures)

Raise:

a NotImplementedError since this function is not intended for the use case of this class

score_is_equivalent(score1: float, score2: float) → bool¶

determines if score should be considered equivalent

Parameters:

score1 – the first score
score2 – the second score

class schrodinger.comparison.atom_mapper.CSPAtomMapper(optimize_mapping: bool, use_chirality: bool, allow_reflection: bool, align=True, debug=False)¶

Bases: BaseAtomMapper

Atom mapper for CSP comparisons optimizes map over rmsd including improper rotations inherits from LewisAtomMapper to use element, formal charge, number of neighbors and total number of bonds as graph invariants.

RMSD_THRESH = 1e-08¶

__init__(optimize_mapping: bool, use_chirality: bool, allow_reflection: bool, align=True, debug=False)¶

Parameters:

optimize_mapping – if True search maps for optimal score
use_chirality (boolean) – if True, in addition to element type use chirality (where defined) to equate atoms.
allow_reflection – whether or not to allow reflection when optimizing rmsd in scoring method
align – if True align structures for scoring else do in place rmsd
debug – if True print additional debug information

initialize_atom_types(st: Structure, invert_stereocenters=False)¶

Initialize the atom types

Parameters:

st – structure containing atoms
invert_stereocenters – whether or not R/S labels should be flipped

score_mapping(st1, st2, atset)¶

Score a mapping over the atoms listed in atlist. the score is just the rmsd

Parameters:

st1 (Structure) – first structure
st2 (Structure) – second structure
atset (set of ints) – set of atoms that have been mapped (indexes refer to both structures)

Return type:

float

Returns:

the rmsd

score_is_equivalent(score1, score2)¶

Here we declare 2 scores equivalent if the rmsd difference is within RMSD_THRESH. This resolves machine dependent descrepancies in the chosen map.

Parameters:

score1 (float) – the rmsd of the first map
score2 (float) – the rmsd of the second map

Returns:

boolean indicating if the score is the same or different