schrodinger.structutils.measure module¶
Functions for measuring distances and angles in structures.
Copyright Schrodinger, LLC. All rights reserved.
- schrodinger.structutils.measure.get_close_atoms(st: schrodinger.structure._structure.Structure, dist: float, atoms: Optional[List[int]] = None) List[Tuple[int, int]] ¶
Use this function to find all atoms within a specified distance of each other in roughly O(N) time. Returns a list of tuples in the form of: (atom1, atom2), where atom1 and atom2 are atom indices.
This function is only roughly O(N) in the number of atoms in the molecule because as dist increases it will reach the limit of O(N^2). Its true cost is O(N*m) where m is the number of atoms in a cubic box with edges of dist length.
- Parameters
st – Structure object
dist – distance threshold, in angstroms.
atoms – optionally consider only atoms with these indices (all atoms in
st
are scanned by default)
- Returns
list of paired atom indexes that fall within the distance threshold
NOTES:
Each atom pair is listed only once in the output.
This function is efficient only for small distances (<3A)
Periodic boundary conditions (PBC) are NOT honored.
- schrodinger.structutils.measure.get_close_coordinates(coords, dist)¶
Use this function to find all coordinates within a specified distance of each other in roughly O(N) time.
- Parameters
coords (list(list(float, float, float))) – List of (x, y, z) coordinates.
dist (float) – distance threshold, in angstroms.
- Returns
Returns indices to the input array for pairs of the coordinates that are within the threshold of each other.
- Return type
tuple(int, int)
- schrodinger.structutils.measure.create_distance_cell(st, distance, honor_pbc=True)¶
Create a DistanceCell for the given structure and cutoff. If struct has the Chorus box properties, the distance cell will be PBC-aware.
- Parameters
st (schrodinger.structure.Structure) – The input structure, may have the Chorus box properties.
distance (float) – The cutoff for finding nearest neighbor atoms.
honor_pbc (bool) – Whether to honor Periodic Boundary Conditions, if defined as properties in the “st” structure. Default is True.
- Returns
The distance cell.
- Return type
schrodinger.infra.structure.DistanceCell
- schrodinger.structutils.measure.any_atom_in_distance_cell(distance_cell, st)¶
Check that if any atom of
st
lies in thedistance_cell
.- Parameters
distance_cell (schrodinger.infra.structure.DistanceCell) – A DistanceCell object
st (schrodinger.structure.Structure) – A structure object
- Returns
True if any atom of
st
lies in thedcell
else False- Return type
bool
- schrodinger.structutils.measure.get_atoms_close_to_structure(st, other_st, cutoff, honor_pbc=True)¶
Returns a list of atoms from st that are within the threshold distance of st2.
- Example: Get a list of receptor atoms close to the ligand:
close_atoms = measure.get_atoms_close_to_structure(re_st, lig_st, 3.0)
- Parameters
st (
structure.Structure
) – Structure atoms from wich should be analyzed/returned.other_st (
structure.Structure
) – Query structure.cutoff (float) – Distance theshold.
honor_pbc (bool) – Honor Periodic Boundary Conditions, if defined as properties in the “st” structure. Default is True.
- schrodinger.structutils.measure.get_atoms_close_to_subset(st, other_atoms, cutoff, honor_pbc=True)¶
Returns a list of atoms from that are within the threshold distance of “other_atoms” subset, and are not themselves in that subset.
- Example: Get a list of receptor atoms close to the ligand:
close_atoms = measure.get_atoms_close_to_subset(st, lig_atoms, 3.0)
- Parameters
st (
structure.Structure
) – Structure atoms from wich should be analyzed/returned.other_atoms (list of int) – Query atoms.
cutoff (float) – Distance theshold.
honor_pbc (bool) – Honor Periodic Boundary Conditions, if defined as properties in the “st” structure. Default is True.
- schrodinger.structutils.measure.get_shortest_distance(st, atoms=None, st2=None, cutoff=inf)¶
Determines the shortest distance and indices of the nearest atoms between two structures or between a groups of atoms in a single structure. NOTE: Periodic boundary conditions (PBC) are NOT honored.
- Parameters
st (
schrodinger.structure.Structure
) – Structure containing group(s) of atoms for nearest distance search.atoms (list(int)) – If specified, the distances between this group of atoms and all other atoms in st are evaluated. Either atoms or st2, but not both, must be specified.
st2 (
schrodinger.structure.Structure
) – Structure of second group of atoms for nearest-distance search. Either st2 or atoms, but not both, must be specified.cutoff (float) – Cutoff distance in Angstroms for nearest-distance search (by default no cutoff is used). Setting this parameter can speed the calculation by considering only points between sets that are within the cutoff value. None will be returned if no neighbors are found within the specified cutoff.
- Return type
tuple of float, int, int or None
- Returns
A tuple containing the nearest distance between atoms and the indices of the closest atoms between each set.
- schrodinger.structutils.measure.get_atoms_close_to_point(st, xyz, cutoff, honor_pbc=True)¶
Returns a list of atoms from st that are within the threshold distance of a point, which is defined by its xyz coordinates..
- Example: Get a list of receptor atoms close to a point:
close_atoms = measure.get_atoms_close_to_structure(re_st, xyz, 3.0)
- Parameters
st (
structure.Structure
) – Structure atoms from wich should be analyzed/returned.xyz (list) – xyz coordinates of point
cutoff (float) – Distance theshold.
honor_pbc (bool) – Honor Periodic Boundary Conditions, if defined as properties in the “st” structure. Default is True.
- Returns
list of atoms close to a point
- Return type
list
- schrodinger.structutils.measure.dist_cell_iterator(st, dist=None, atoms=None, cell_handle=None, delete_dist_cell=True)¶
Create an iterator that uses a distance cell to iterate through neighbors of the specified atoms
- Parameters
st (
schrodinger.structure.Structure
) – The structure to examinedist (float) – The distance cutoff for calculating neighbors. Either dist or cell_handle must be given, but not both.
atoms (list) – A list of atom numbers to calculate neighbors for. If not, given, st.atom will be used.
cell_handle (int) – A handle to an existing distance cell. If not given, a new distance cell will be created with distance dist. Either dist or cell_handle must be given, but not both.
delete_dist_cell (bool) – If cell_handle is given and delete_dist_cell is True, then distance cell cell_handle will be deleted after iteration is complete. Has no effect if cell_handle is not given. Defaults to True.
- Returns
An iterator that iterates through neighbors of the specified atoms
- Return type
iter
- Raises
ValueError – If both dist and cell_handle are not None
- Deprecated
The DistanceCellIterator class provides the same functionality as this function but with increased flexibility
- class schrodinger.structutils.measure.DistanceCellIterator(struc, dist, atoms=None)¶
Bases:
object
Iterate through neighbors of specified atoms. This class replaces the dist_cell_iterator function. NOTE: Periodic boundary conditions (PBC) are NOT honored.
- __init__(struc, dist, atoms=None)¶
Construct the distance cell to use for finding neighbors
- Parameters
struc (
schrodinger.structure.Structure
) – The structure to use for building the distance celldist (float) – The distance cutoff for calculating neighbors
atoms (list) – A list of atom numbers for
struc
. If given, the distance cell will only contain the specified subset of atoms, so all other atoms will be ignored when calculating neighbors. If not given, all atoms will be used.
- iterateNeighboringAtoms(struc=None, atoms=None)¶
Iterate over neighboring atoms (atoms within
dist
Angstrom of each other). NOTE: Periodic boundary conditions (PBC) are NOT honored.- Parameters
struc (
schrodinger.structure.Structure
) – The query structure. Neighbors will be found for each atom of this structure. If not given, the structure passed to__init__
will be used as the query structure.atoms (list(int)) – A list of atom numbers for the query structure. If given, only the specified atoms will be examined. If not given, all atoms of the query structure will be used.
- Returns
A generator that iterates through neighbors. Each iteration will yield a tuple of (atom index, list of neighboring atom indicies)
- Return type
generator
Note: This method returns atom indices instead of atom object due to speed concerns. Profiling (using timeit) showed that:
returning atom indices instead of atom objects reduced runtime by ~25%
using
coord = mm.mmct_atom_get_xyz(struc.handle, atom_num)
in place ofcoord = struc.atom[atom_num].xyz
also reduced runtime by ~25%
- schrodinger.structutils.measure.measure_distance(atom1: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]], atom2: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]]) float ¶
Measure the distance between two atoms.
All atom arguments must be _StructureAtom objects (returned from the Structure.atom list, and can be from different structures), or XYZ coordinates, as lists or numpy arrays.
See also the Structure.measure method. It can use integer atom indices in addition to _StructureAtom objects, but is restricted to measurements within the structure and cannot do plane angle measurements.
NOTE: Periodic boundary conditions (PBC) are NOT honored.
- schrodinger.structutils.measure.measure_bond_angle(atom1: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]], atom2: Union[schrodinger.structure._structure.StructureAtom, List[float]], atom3: Union[schrodinger.structure._structure.StructureAtom, List[float]]) float ¶
Measure the atom between 3 specified atoms.
All atom arguments must be _StructureAtom objects (returned from the Structure.atom list, and can be from different structures), or XYZ coordinates, as lists or numpy arrays.
See also the Structure.measure method. It can use integer atom indices in addition to _StructureAtom objects, but is restricted to measurements within the structure and cannot do plane angle measurements.
NOTE: Periodic boundary conditions (PBC) are NOT honored.
- schrodinger.structutils.measure.measure_dihedral_angle(atom1: Union[schrodinger.structure._structure.StructureAtom, List[float]], atom2: Union[schrodinger.structure._structure.StructureAtom, List[float]], atom3: Union[schrodinger.structure._structure.StructureAtom, List[float]], atom4: Union[schrodinger.structure._structure.StructureAtom, List[float]]) float ¶
Measure the dihedral angle between the specified atoms.
All atom arguments must be _StructureAtom objects (returned from the Structure.atom list, and can be from different structures), or XYZ coordinates, as lists or numpy arrays.
See also the Structure.measure method. It can use integer atom indices in addition to _StructureAtom objects, but is restricted to measurements within the structure and cannot do plane angle measurements.
NOTE: Periodic boundary conditions (PBC) are NOT honored.
- schrodinger.structutils.measure.measure_plane_angle(atom1: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]], atom2: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]], atom3: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]], atom4: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]], atom5: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]], atom6: Union[schrodinger.structure._structure.StructureAtom, List[float], Tuple[float]], minangle: bool = False) float ¶
Measure the angle between planes of the provided atoms.
All atom arguments must be _StructureAtom objects (returned from the Structure.atom list, and can be from different structures), or XYZ coordinates, as lists or numpy arrays.
See also the Structure.measure method. It can use integer atom indices in addition to _StructureAtom objects, but is restricted to measurements within the structure and cannot do plane angle measurements.
NOTE: Periodic boundary conditions (PBC) are NOT honored.
Parameters
- minangle (bool)
This applies to the planar angle calculation and if True restricts the angle to the range [0, 90] degrees. That is, it treats the order of atoms defining a plane as unimportant, and the directionality of the plane normals is ignored.
- schrodinger.structutils.measure.is_colinear(coords)¶
Test if a set of coordinates are all colinear.
- Parameters
coords (
numpy.array
) – The xyz coordinates- Return type
bool
- Returns
True if the points are colinear, False if not.
- exception schrodinger.structutils.measure.LinearError¶
Bases:
ValueError
A class indicating a plane could not be computed due to all atoms being linear
- schrodinger.structutils.measure.fit_plane_to_points(coords, normal_alignment_idcs=(0, 1, 2))¶
Fit a plane to a set of xyz coordinates
This method comes from http://stackoverflow.com/questions/15959411/fit-points-to-a-plane-algorithms-how-to-iterpret-results It is the SVD method appearing there.
- Parameters
coords (list(list(float)) or numpy.array) – The coordinates to fit the plane to, such as come from struct.getXYZ()
normal_alignment_idcs (tuple(int, int, int) or NoneType) – 3 zero-based indices which indicate which points of
coords
will be used to align the returned vector. This allows for a consistent direction of the returned vector between function calls. If None, this alignment procedure will not be performed. Any choice of 3 points is equally valid if used consistently between function calls; a reason to change them from the default is if the first 3 points are colinear, in which case the alignment procedure cannot work.
- Return type
numpy.array
- Returns
The unit normal vector to the best fit plane
- Raises
LinearError – If there are only 3 coordinates and they are colinear. If there are 4 or more colinear coordinates, one of the infinite number of possible vectors will be returned.
ValueError – If there are fewer than 3 sets of coordinates
numpy.linalg.LinAlgError – If the SVD does not converge (note - I was unable to find a case where this happened)
- schrodinger.structutils.measure.fit_plane_to_points_as_list(coords, normal_alignment_idcs=(0, 1, 2))¶
Fit a plane to a set of xyz coordinates
This method is used by Maestro because it’s easier to access a list from C++ than a numpy array.
See docstring of fit_plane_to_points() for more details. Only information which differs from that function is given here.
- Return type
list
- Returns
A list of 3 floats that defines a normalized vector that is normal to the best-fit plane
- schrodinger.structutils.measure.measure_angle_between_rings(ring1: List[Union[schrodinger.structure._structure.StructureAtom, Tuple[float]]], ring2: List[Union[schrodinger.structure._structure.StructureAtom, Tuple[float]]]) float ¶
Measure the angle between the 2 rings.
All atom arguments must be _StructureAtom objects (returned from the Structure.atom list, and can be from different structures), or XYZ coordinates.
NOTE: Periodic boundary conditions (PBC) are NOT honored.