symmetry module

Expansion of molecular & crystal symmetry.

Direct stand-alone usage has been deprecated; see symexp.py.

Changed in version Start: 09/09/11

Changed in version 0.3.7: 11/04/11

Changed in version 0.5.0: 05/04/15 ReStructuredText docs

class symmetry.Arguments(imports=[], main=False, *args, **kwargs)

Bases: argparser.ArgumentParser

Argument parser for symmetry.

Parameters:
  • imports ((list of) ArgumentParser method(s)) – method(s) adding arguments to ArgumentParser instance. (Alternative to ArgumentParser parents w/ better maintained groups.)
  • main (bool) – Parser for main program (i.e. not listed within an ArgumentParser parents argument). Adds default program information.
static export()

Adding options used in both stand-alone and imported modes.

class symmetry.Cartesian_operator(name='', rotation=[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]], translation=[0.0, 0.0, 0.0], verbose=True)

Bases: object

Rotation + translation in Cartesian space.

x’ = [R]x + t.

Parameters:
  • rotation (numpy.matrix-like.shape(3,3)) – R - row-major 3x3 rotation matrix.
  • translation (numpy.matrix-like.shape(3,1)) – t - translation vector applied after rotation.
  • name (str) – optional name, 1st character used chain ID, 1st 4 characters used for PDB segid.
  • verbose (bool) – print information about operator.
euler(verbose=False)

Euler rotation and axis from rotation matrix.

Parameters:verbose (bool) – print rotation & axis
Returns:(rotation (degrees), unit-vector-axis)
Return type:float, numpy.matrix.shape(3,1)
isunit()
Returns:True if unit operator.
Return type:bool
class symmetry.Documentation

User-level documentation (imports).

class Input
local

Generic documentation for import into other modules.

class symmetry.Symmetry(local=None, unit=True, space_group=None, cell=None, lattice_translations=1, distance=3.5, tolerance=0.5, completion=None, verbose=False)

Bases: object

Symmetry expansion of coordinates.

Changed in version 0.5.5: 10/20/15 Riding anisotropic Us supported. Tested by comparing traces of ANISOU PDB records for symmetry equivalents, and visual inspection of R3 expanded insulin.

For local symmetry, roughly O(NlogN) to find neighbors:

  • 25 ms for 50 atom target
  • 15 s for 4200 atom target

Re-expansion O(1), ~1 ms.

Variables:
  • operators – indices of the operators used to generate each neighbor from unique (local, crystallographic, translation_a, b, c), noting that only local currently implemented.
  • neighbors – selection of atoms from unique that generate neighbors with the corresponding transformation from operators.

Initialize operators for expansion / set default neighbor criteria.

Parameters:
  • local (list of N (Carterian_operator or tuple for instantiation of Cartesian_operator).) – local (molecular) operators or None.
  • unit (bool) – insert (if absent) and use the unit operator.
  • space_group (str or NoneType) – (optionally shortened) Hermann-Mauguin symbol with ‘:setting’ appended (if required; see space_group, or None.
  • cell (tuple(6) or numpy.matrix-like (size = 3x3)) – unit cell parameters, or fractional to orthogonal (Å) matrix, required if space_group.
  • lattice_translations (int) – Number to search in each direction for neighbors. If unique atoms are within -0.5 to +1.5 (fractional units, most cases) then 1 should suffice. In some cases a larger search generates more neighbors - wise to check 2. Zero disables.
  • distance (float) – within which neighboring atoms will be found, see also Symmetry.neighbors.
  • tolerance (float) – neighbors to be re-identified when an atom has moved more than this amount (Å), see also Symmetry.neighbors.
  • completion (string or NoneType) – if ‘residue’ or ‘chain’, expand the selection of neighboring atoms to the whole group.
  • verbose (bool) – print diagnostics.

Warning

This inistantiation assumes that the non-crystallographic symmetry, unit cell and magnification will remain constant. Refinement will require re-instantiation. RSRef currently assumes that magnification will only be refined for EM which where space_group=None, so that it is safe to instantiate only at start up.

Note

local could be the result of symmetry.safe_eval of an input tuple of which the following is a short example:

("p",        ((0.500000,       0.809000,      -0.309000),
             (-0.809000,       0.309000,      -0.500000),
             (-0.309000,       0.500000,       0.809000)),
              (0.000000,       0.000000,       0.000000)),
("e",        ((0.309000,      -0.500000,       0.809000),
              (0.500000,       0.809000,       0.309000),
             (-0.809000,       0.309000,       0.500000)),
              (0.000000,       0.000000,       0.000000)))
complete(atoms, neighbors, completion=None)

Expand list of neighbors to include all atoms w/in residue or chain.

Requires atoms in the same residue to share the same chain and segids (even if null) and for at least one of these to be unique for the residue number.

Parameters:
  • atoms (Atoms) – object containing the chain, (segid) and residue names/ numbers corresponding to neighbors (often an untransformed set).
  • neighbors (ndarray-like, dtype=bool, size=# atoms.) – True for atoms that are neighbors.
  • completion (str or NoneType) – ‘chains’, ‘residues’, ‘atoms’ aka None.
Returns:

completed neighbors.
Return type:

ndarray-like, dtype=bool, size=# atoms.
debug = False
equivalent(xyz, ilocal=0, ilattice=0, a_trans=0, b_trans=0, c_trans=0, anisou=None)

Transform coordinates by a single set of local and lattice operators.

Parameters:
  • xyz (ndarray.shape(3,N)) – coordinates (Angstrom).
  • ilocal (int) – index of Symmetry.local operator to be applied.
  • ilattice (int) – index of Symmetry.lattice operator to be applied (not implemented).
  • a_trans (int) – unit cell translations along a axis.
  • b_trans (int) – unit cell translations along a axis.
  • c_trans (int) – unit cell translations along a axis.
  • anisou (Anisotropics/NoneType) – U tensors if available, else None.
Returns:

transformed xyz, anisou
Return type:

ndarray, Anisotropics
neighbors(unique, target_atoms=None, selection=None, distance=None, lazy=True, tolerance=None, completion=None)

Symmetry-expand unique for all neighbors of selected atoms in target.

Parameters:
  • unique (Atoms) – atomic coordinates to be symmetry expanded.
  • target_atoms (Atoms or NoneType) – atoms whose neighbors from unique (and unique’s symmetry equivalents) will be found. If None, defaults to unique.
  • selection (ndarray, dtype=bool) – subset of target atoms to use. True to select all. Defaults to target_atoms.evaluate if target_atoms defined, or True.
  • distance (float) – limit in Å; if None, use instantiated value.
  • lazy (bool) – recalculate which atoms are neighbors only if the selection unique has changed by more than tolerance
  • tolerance (float) – see lazy; if None, use instantiated value.
  • completion (str or NoneType) – if ‘residue’ or ‘chain’, expand the selection of neighboring atoms to the whole group.
Returns:

(input atoms w/ unique.close reset, symmetry-related neighbors) unique.close will be True for atoms w/in distance of selection and not unique.evaluate. unique retains all atoms and is suitable for PDB output. Arrays of the symmetry equivalents are compressed, containing only neighboring atoms, and not necessarily whole residues or molecules suitable for output etc.
Return type:

(Atoms, Atoms)
repr_op(op_indices)

Self-documenting representation of the operator set.

Parameters:op_indices (tuple(int,)*5) – indices of the local & lattice operators and unit translations along each axis.
verbose = 1
with_neighbors(unique)

Iterate over selected atoms and (symmetry-related) neighbors.

Equivalent to Symmetry.neigbors (with default arguments), then iterating over (Atoms.evaluate | Atoms.close) for asymmetric unit and equivalent atoms.

Parameters:unique (Atoms) – atomic coordinates, (NCS) asymmetric unit.
Returns:atom type, position, occupancy, b-factor, anisotropic-Us, evaluate, close, atom number (from which equivalent generated), operators=(local, lattice, trans_a, trans_b, trans_c).
Return type:string, NumPy.matrix(dtype=float, shape=(3,1)), float, float, NumPy.matrix(dtype=float, shape=(3,3))/NoneType, bool, bool, int, tuple(5 int)
class symmetry.Target(xyz, use=None, distance=3.5)

Bases: object

Atomic coordinates for which neighbors are sought.

Sphere and box that enclose target atoms and anything w/in distance.

Parameters:
  • xyz (Atoms) – atomic coordinates whose neighbors are to be found.
  • use (ndarray, dtype=bool) – subset of atoms to use, defaults to all.
  • distance (float) – limit in Angstrom for neighbors to be considered close.
debug = False
isclose(xyz, distance_increase=0.0)

Is point w/in distance of target sphere?

Parameters:
  • xyz (numpy.matrix(shape(3,1), dtype=float)) – position, Cartesian Angstrom coordinates.
  • distance_increase (float) – to be added to self.distance.
Returns:

close
Return type:

bool
isneighbor(xyz)

Which of N points in xyz is w/in self.distance of any target atom?

Note that this does not care about atomic properties at xyz, including whether an atom has been selected for evaluation. However, the target coordinates (for which neighbors are sought) will have previously been subject to selection criteria.

Parameters:xyz (numpy.matrix(shape(3,N), dtype=float)) – position, Cartesian Angstrom coordinates.
Returns:close
Return type:ndarray(shape=N, dtype=bool)
symmetry.safe_eval(filename)