schrodinger.structutils.measure module¶

Functions for measuring distances and angles in structures.

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 the distance_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 the dcell 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 examine
dist (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 cell
dist (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 of coord = 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.