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: schrodinger.structure._structure.Structure) schrodinger.structure._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: schrodinger.structure._structure.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: schrodinger.structure._structure.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: schrodinger.structure._structure.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: schrodinger.structure._structure.Structure, st2: schrodinger.structure._structure.Structure, atset: Set[int]) schrodinger.comparison.atom_mapper.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: schrodinger.structure._structure.Structure, atset: Set[int]) networkx.classes.graph.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: schrodinger.structure._structure.Structure, atset1: Set[int], st2: schrodinger.structure._structure.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: schrodinger.structure._structure.Structure, st2: schrodinger.structure._structure.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: schrodinger.structure._structure.Structure, atlist1: List[int], st2: schrodinger.structure._structure.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: schrodinger.structure._structure.Structure, atlist1: List[int], st2: schrodinger.structure._structure.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: schrodinger.structure._structure.Structure, atlist1: List[int], st2: schrodinger.structure._structure.Structure, atlist2: List[int], invert_stereocenters: bool = False) Tuple[schrodinger.structure._structure.Structure, schrodinger.structure._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: schrodinger.comparison.atom_mapper.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: schrodinger.structure._structure.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: schrodinger.structure._structure.Structure, st2: schrodinger.structure._structure.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: schrodinger.comparison.atom_mapper.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: schrodinger.structure._structure.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: schrodinger.structure._structure.Structure, st2: schrodinger.structure._structure.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_structures=True, debug=False)

Bases: schrodinger.comparison.atom_mapper.BaseAtomMapper

Atom mapper for CSP conformer comparisons. It optimizes map over rmsd including improper rotations, and uses 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_structures=True, debug=False)
Parameters
  • optimize_mapping – if True search maps for optimal score

  • use_chirality – 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_structures – if True align structures for scoring else do in place rmsd

  • debug – if True print additional debug information

initialize_atom_types(st: schrodinger.structure._structure.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: schrodinger.structure._structure.Structure, st2: schrodinger.structure._structure.Structure, atset: Set[int]) float

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

Parameters
  • st1 – first structure

  • st2 – second structure

  • atset – set of atoms that have been mapped (indexes refer to both structures)

Returns

the rmsd

score_is_equivalent(score1: float, score2: float)

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 – the rmsd of the first map

  • score2 – the rmsd of the second map

:return boolean indicating if the score is the same or different