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, dist, atoms=None)

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 CT by are scanned by default)

NOTES:

  • Each atom pair is listed only once in the output.
  • This funtion 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.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, atom2)

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, atom2, atom3)

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, atom2, atom3, atom4)

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, atom2, atom3, atom4, atom5, atom6, minangle=False)

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.
exception schrodinger.structutils.measure.LinearError

Bases: ValueError

A class indicating a plane could not be computed due to all atoms being linear

__init__

Initialize self. See help(type(self)) for accurate signature.

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

schrodinger.structutils.measure.fit_plane_to_points(coords)

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 (numpy.array) – The coordinates to fit the plane to, such as come from struct.getXYZ()

Return type:

numpy.array

Returns:

An array of 3 floats that defines a normalized vector that is normal 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)

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.

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 (numpy.array) – The coordinates to fit the plane to, such as come from struct.getXYZ()

Return type:

list

Returns:

An list of 3 floats that defines a normalized vector that is normal 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)