atoms module

Atomic coordinates and properties.

Module author: Michael S. Chapman <chapmami@ohsu.edu>

Authors:

Michael S. Chapman <chapmami@ohsu.edu>, Brynmor K. Chapman,

Oregon Health & Science University
Version:

0.5, March 23, 2016

Changed in version 02/14/2010.

Changed in version 11/4/12: - split from atomic_density.py

Changed in version 0.4.2: (10/24/13)

Changed in version 0.5.0: (3/12/15) ReStructured Text documentation

Changed in version 0.5.2: (8/26/15) is_cterm() support for bonded_main in torsion

Changed in version 0.5.4: 9/29/15 Optional echoing of input ANISOU to output & CA only.

Changed in version 0.5.5: 10/13/15 Anisotropic Us ride with atom rotations.

Changed in version 0.5.6: 01/11/16 Comparison of anisotropic Bs.

class atoms.Anisotropics(elements)

Bases: object

Anisotropic atomic displacement factors for an array of atoms.

Variables:U (numpy.ma.ndarray.shape(n,3,3)) – Symmetric U tensors, Å:sup:‘2’ units, for n atoms.

For atoms without anisotropic U, self.U.mask is True. The class provides methods rotate() to rotate the tensors of a selection of atoms (as one would also rotate atom positions), and iso_like() to rescale U elements to be compatible with (changed) isotropic B-values.

Unit testing is partial, but supplemented by one-off regression testing. In the latter, Ethan Merritt’s coruij.f (Acta D55: 1997-2004 (1999)) was used to compare the anisotropic Us for arginine kinase determined at ambient temperature in two unit cells. On a first run, the two structures were provided unchanged, along with a superimposition matrix. On a second run, the structures were superposed by PaStO and compared using coruij.f with a unit matrix. ADP comparison statistics, including SUV, were nearly identical (there might have been small differences in the superimposition.) This validates __init__(), isotropic(), rotate() and triangular(). Unit tests for ccuij(), cciso(), isotropize(), suij() are available based also on regression from coruij.f.

Initialize anisotropic U tensors from unique elements in PDB

Parameters:elements (ndarray) – U-tensor [1,1], [2,2], [3,3], [1,2], [1,3], [2,3] units: Å2, noting that above indices start at 1, but array elements from 0.
alignment(other, paired=True, scale=False, individual=False, intermediate=(0.0, 1.0), three_axes=False, self_atoms=None, other_atoms=None, diagnostics=[0, 50.0])

Attempts to measure alignment of U principle axes.

Parameters:
  • other (Anisotropics) – unlike self, other must contain only the Us for paired atoms, reordered according to the atom order in self. This will usually be the Anisotropics instance of a Pairing.reordered set of atoms.
  • scale (Group or Selection or bool) – normalize for average b_iso atom size within group(s) of atoms in self (if specified), treating all non-selected atoms as an additional group.
  • individual (bool) – scaling by individual atom, else by average isotropic B
  • intermediate ((float, float)) – beyond these prolateness limits, the ellipsoid will be considered pure oblate and prolate respectively, transitioning between the two with a linear ramp between the limits.
  • three_axes (bool) – calculate alignment in an additional way using all three axes, permuting to find the best alignment.
  • self_atoms (Atoms) – from which self’s Us taken (for debugging only).
  • other_atoms (Atoms) – from which other’s Us taken (for debugging only).
  • diagnostics ([int, float]) – print diagnostics for 1st n cases where alignment stats differ by more than threshold.
Returns:

misalignment [x 3 if three_axes]
Return type:

MaskedArray [x 3 if three_axes]

Misalignment is calculated by VecList.align_unique() which, in over-simplified explanation, could be considered to be the rotation from best alignment of the unique axes from paired ellipsoid atoms.

Misalignment can optionally also be calculated (if three_axes) as the average (cosine) deviation between vectors in self and other, after permuting self for the maximum sum of dot products between paired vectors. This has been deprecated from Pairing, because inspection of discrepancies between the two misalignment calculations showed that this calculation was not sensitive to ~90 deg rotations of ellipsoids.

analyze()

Anisotropy and prolateness (cigar-like shape).

Returns:anisotropy, prolateness
Return type:(numpy.ma.ndarray, numpy.ma.ndarray)

Anisotropy is defined conventionally: The eigenvalues of the U tensor are the squared displacements along the principal axes, and it is their ratios that are used. Anisotropy = minimal axial displacement2 / maximal, so its range is from 0.0 (highly anisotropic) to 1.0 (spherical);

Prolateness is arbitrarily defined here by the ratios of displacement: (axismax - axismid)/(axismax - axismin), so its range is from 0.0 (oblate, pancake) to 1.0 (prolate, cigar). Note that prolateness is calculated with the displacements (not squared) on which the density ellipsoids depend, whereas anisotropy is calculated conventionally using displacement2.

axes()

Magnitudes and principal axes of displacement.

Returns:(square displacements along principal axes, unit vectors along each row (fastest dimension), so the mth vector of tensor n is in axes[n, m, :])
Return type:(numpy.ma.ndarray.shape=(n,3), numpy.ma.ndarray.shape(n,3,3))
cciso()

Anisotropic atom density correlation w/ its isotropic equivalent.

Used in Merritt, E.A. Acta D55: 1997-2004 (1999).

ccuij(other, scale=False)

Density correlations between this and another set of anisotropic atoms

Equation 6 of Merritt, E.A. Acta D55: 1997-2004 (1999)

Parameters:
  • other (Anisotropics) –
  • scale (bool) – normalize for atom size, as in numerator of eqn 8 of Merritt
Return ccuij:

Correlation coefficient for densities of each atom where anisotropic.
Rtype MaskedArray:
 

See also

method suij for normalized shape correlation

check(atoms=None, verbose=True)

Raises diagnostic exceptions if fails integrity checks.

  1. Atoms without anisotropic U are masked.
Parameters:atoms (Atoms) – from which Us were derived, used for optional diagnostics
Return self:(just so that check can be chained w/ other methods.)
Rtype Anisotropics:
 
divergence(other, paired=True, scale=False, individual=False)

Kullback-Liebler divergence between this and another set of anisotropic atoms

Equation 23 of Murshudov et al. Acta Cryst. D67: 255-67 (2011); Equation 8 of Merritt, E.A. Acta Cryst. A67: 512-16 (2011)

Parameters:
  • other (Anisotropics) – unlike self, other must contain only the Us for paired atoms, reordered according to the atom order in self. This will usually be the Anisotropics instance of a Pairing.reordered set of atoms.
  • scale (Group or Selection or bool) – normalize for average b_iso atom size within group(s) of atoms in self (if specified), treating all non-selected atoms as an additional group.
  • individual (bool) – scaling by individual atom, else by average isotropic B
Returns:

KL divergence in density for each atom pair where anisotropic.
Rtype MaskedArray:
 

See also

method suij for normalized shape correlation

The scaling represents extensions over Murshdov and Merritt who were considering situations where B-factors would be similar and not for (say) different temperatures. Don’t know how will behave.

Empirically find that scaling does not affect the commutivity of the symmetrized K.-L. divergence, i.e. divergence(a, b) = divergence(b, a)

iso_like(isotropic, selection=None, copy=False)

Scale the anisotropic U(s) to match the isotropic B(s).

Parameters:
  • isotropic (numpy.ma.array) – B-factors for each atom in self.U
  • selection (ndarray or Selection or NoneType) – True for scaled atoms or None for all.
  • copy (bool) – returns modified copy of self.U; else in-place, modifying self
Returns:

modified U if copy, else self, U changed (only) at n selected atoms
Return type:

ndarray or Anisotropics

See also

atoms.iso_like() for single atom.

isotropic()

Convert anisotropic U(s) to isotropic B(s).

Parameters:
  • start (int) – index of 1st atom.
  • end (int) – index of atom after last.
Returns:

isotropic B-factor(s) as a masked array where can be calculated
Return type:

numpy.ma.ndarray

See also

atoms.isotropic() for single atom.

isotropize(selection=None, copy=False)

Spherically symmetric equivalent anisotropic U tensors.

Parameters:
  • isotropic (numpy.ma.array) – B-factors for each atom in self.U
  • selection (ndarray or Selection or NoneType) – True for scaled atoms or None for all.
  • copy (bool) – returns modified copy of self.U; else modified self
Returns:

modified U if copy, else self, U changed (only) at n selected atoms
Return type:

ndarray or Anisotropics
join(added)

Join two instances.

Warning

Untested as of 10/17/15

Warning

use with care as result will cease to be aligned with Atoms object.

rotate(operator, selection=None, check=False)

Transform Us of selected atoms by rotational component of operator.

Parameters:
  • operator (numpy.matrix) –
  • selection (ndarray or Selection or NoneType) – True for transformed atoms or None for all.
  • check (bool) – cross-check rotational invariants (for debugging).
Returns:

self, U changed (only) at n selected atoms
Return type:

Anisotropics

Internal checking was coded, because a fraction of atoms displayed by Coot seemed to have ellipsoids with axes rotated by up to 20 degrees or altered ellipticities. Subsequently, viewing in PyMol is much more satisfying, so we think that it is a bug in Coot. Internal testing includes: (1) that magnitidues of the principal axes are ~invariant with rotation. (2) if reference frame axes are introduced, then the direction cosines of all principal axes remain ~invariant with rotation of both the anisotropic Us and the reference axial basis. These were all checked with hexagonal insulin (non-orthogonal). Precision of ~1.e-05 and ~0.3 deg. seems commensurate with the 5-digit roundoff of ANISOU records in a PDB file.

scale(other, paired=True, uniform=None, individual=False)

Scale U in a copy of self so that B_iso is the same as in other.

Scaling U tensor is equivalent to a resizing of the real-space atom ellipsoid.

Parameters:
  • other (Anisotropics) – reference whose Us against which self.U is scaled.
  • paired (Selection|bool) – atoms of self that are paired with atoms in other.
  • uniform (Group or Selection or NoneType) – group(s) of atoms in self, within which scaling by average <B_iso> is applied. All atoms not selected are combined into another group for scaling. Thus, the default (None) is all atoms scaled uniformly as one group.
  • individual (Group or Selection or bool) – group(s) of atoms in self for which scaling is by each B_iso. True for all atoms, False for none.
Returns:

new
Return type:

Anisotropics
scale_individual(other, paired=True, selection=None)

Scale so that each selected atom in copy of self.U has same B_iso as in other.

Scaling U tensor is equivalent to a resizing of the real-space atom ellipsoid.

Parameters:
  • other (Anisotropics) –
  • paired (Selection or bool) – atoms of self that are paired with atoms in other.
  • selection (Selection or NoneType) – True for selected atoms; None for all atoms
Return new:
Rtype Anisotropics:
 
scale_uniform(other, paired=True, selection=None)

Scale all atoms in selection so that <B_iso> of paired atoms is same as in other.

Scaling U tensor is equivalent to a resizing of the real-space atom ellipsoid.

Parameters:
  • other (Anisotropics) –
  • paired (Selection|bool) – atoms of self that are paired with atoms in other.
  • selection (Selection|Group|NoneType) – True for selected atoms; None for all atoms
Return new:
Rtype Anisotropics:
 
selection(selection)

Subset of Anisotropics instance, where selection is True.

Parameters:selection (Selection) – True where to be copied
Returns:New set of anisotropic Us
Return type:Anisotropics

Warning

Untested as of 10/17/15.

Warning

incompatible with update_pdb()

Warning

try to avoid use as result will cease to be aligned with Atoms object. Better to apply selection (or selection.u to self.u) to all-atom arrays.

shuffle()

Copy with the anisotropic tensors shuffled randomly between atoms.

Can be used to calculated “randomized” statistics.

subset(start, end=None)

Subset of Anisotropics instance, starting at start, and ending at end-1.

Parameters:
  • start (int) – 1st atom (starting at 0)
  • end (int) – last atom (default is start+1 for single atom)

Warning

Untested as of 10/17/15.

Warning

incompatible with update_pdb()

Warning

use with care as result will cease to be aligned with Atoms object.

suij(other)

Shape correlations between this and another set of anisotropic atoms

After normalization for size. Equation 8 of Merritt, E.A. Acta D55: 1997-2004 (1999); except that the numerator is squared as in the 18-Apr-1999 correction of Merritt’s coruij.f that should use square. (Ethan confirmed ~1/10/16 that square should be used and that the square was used to calculate the statistics in the paper.)

Parameters:other (Anisotropics) –
Return suij:Correlation coefficient for densities of each atom where anisotropic.
Rtype MaskedArray:
 

See also

method ccuij for un-normalized correlation

triangular()

Top right triangle of U for PDB output.

Returns:U-tensors [1,1], [2,2], [3,3], [1,2], [1,3], [2,3] for n atoms; units: Å2, noting that above indices start at 1, but array elements from 0.
Return type:numpy.ma.ndarray.shape(6, n)

See also

atoms.triangular() for single atom.

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

Bases: argparser.ArgumentParser

Argument parser for optimization target function.

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 atoms.Atoms(filename=None)

Bases: object

Arrays for the atomic coordinates.

Coordinates (xyz), type, occupancy (o) and B-factor (b) are attributes required by core RSRef methods. Optional attributes should be assigned if available from the PDB file, but will tolerate omissions in non-standard PDB files. Arrays will be of length, N = number of (ATOM + HETATM) records, in the last dimension. Unavailable attributes are set to None. Atom_type is used to select the form factor and is derived from element and charge (if available) or atnam in the many PDB files lacking element.

Variables:
  • xyz – atom positions in orthogonal Angstrom coordinates, required.
  • o – atomic occupancies, required.
  • b – atomic temperature factors, required.
  • atype – atom atype, required.
  • element – element symbol, recommended.
  • charge – eg “++”, recommended.
  • atnam – atom name, required if element absent.
  • altloc – alternative location indicator, optional.
  • resnam – residue name, optional.
  • chain – chain identifier, optional.
  • resnum – residue number, 1-999, optional.
  • insert – residue insertion indicator, optional.
  • segid – segment identifier, optional.
  • bonded – hash list of intra-chain bond connectivities (after connectivity() called).
  • evaluate – atom included in comparison of model & experimental density; a superset of refining atoms.
  • close – neighboring atom whose density might contribute to atoms being evaluated.
  • linenum – atom’s line number from input file.
  • limits – lower and upper limits (x,y,z) for coordinate bounding box.
  • margin – margin surrounding atoms used in bounds (limits) calculation.

Changed in version 05/20/14: - evaluate and close changed from Selection to ndarray to avoid recursive inclusion of Atoms within Selection.

Todo

Torsion angle parameterization is no longer dependent on MMTK, so simplifications to Atoms are possible: (1) link_torsion (re-binding xyz to external array) not needed, although remote possibility that useful with another external optimizer. (2) polymer_chain is not needed. (3) setattr() is not as crucial, but may still be useful with other (CNS) optimizers. Might want profile to see if worth the overhead. (4) property for xyz can be removed with link_torsion, but could be retained for remotely possible future use if profiling indicates little overhead.

Parameters:filename (str) – PDB file with which to initiate, else instantiates empty Atoms object.
class ChainName

Bases: object

Unique chain_ids for symmetry equivalents, if possible.

warning = '* Using %s to get unique chain identifiers.*'
Atoms.are_close(attr, value, atol=0.01, rtol=0.0, nan_exception=True)

Indices for atoms whose attribute close to value.

Parameters:
  • attr (str) – one of the one-dimensional float arrays, eg. b, occ
  • value (float) – target
  • atol (float) – finds absolute(array[:]-value) <= (atol + rtol*value)
  • rtol (float) – see above
  • nan_exception (bool) – raise exception if isnan(value), else return empty list
Returns:

list of indices where close
Return type:

bool ndarray

Note

think about input precision of PDB file when setting atol.

See also

is_close

Atoms.are_neighbors(distance=3.0, verbose=True)

Find atoms that might be close to those being evaluated.

Parameters:distance (float) – within which considered close.
Returns:True if atoms i & j within distance
Return type:ndarray(shape=(n,n), dtype=bool)

The boolean array is very sparse, so its full storage might be a concern. For 20,000 atoms, 50 MB is needed (as boolean), and the calculation takes 2s. A dictionary of 1D booleans for only refining atoms would usually take about half the space. A dictionary of the sparse indices for neighbors would cut the storage to 0.2MB, but at the cost of higher computation each time it is used. Neither of these alternatives are coded up, but below the return are blocks that are simpler implementations of the boolean array that might be more easily adapted to dictionaries / indices.

Atoms.bounds(margin=0.0)

Limits on orthogonal box containing evaluate coordinates w/ margin.

Parameters:margin (float) – distance (Angstrom) added around the coordinates.
Returns:If M{m=}margin, M{ [[x_min-m, x_max+m] [y_min-m, y_max+m] [z_min-m, z_max+m]]}, empty if not any(self.evaluate).
Return type:ndarray(type=float, shape=(2,3))
Atoms.checks_off()

Disable bounds checking on Atoms arrays.

Returns:self
Return type:class Atoms

Warning

could lead to fragile interfaces with external packages if arrays are shared.

Atoms.checks_on()

Enable bounds checking on Atoms arrays.

Returns:self
Return type:class Atoms
Atoms.conformer

Conformers sorted 1, 2, 3... by occupancy then alphabetically.

Occupancy is rounded to 3 decimal places (PDB is 2 places).

Atoms.connectivity(shortest=0.5, longest=2.0, within=100)

Hash list of intra-chain atom connectivities.

Parameters:
  • shortest (float) – minimum distance (A) considered covalent connection.
  • longest (float) – maximum distance (A) considered covalent connection.
  • within (int) – +/- search window (atoms), 999999 for slower full search.
Returns:

Hash list of intra-chain atom connectivities.
Return type:

list (each atom) of lists of connected atom numbers
Atoms.difference(reference, selection=None, reference_selection=None, verbose=False)

Difference between coordinate sets: rmsd(xyz), <abs(O1-O2)>, <abs(B1-B2)>

Requires atoms to be in the same order

Parameters:
  • reference (class Atoms) – atoms
  • selection (Selection or Group) – atoms in self to use.
  • reference_selection (Selection or Group) – atoms in reference to use (must correspond to seletion).
Returns:

RMS deviation in coordinates, mean absolute difference in coordinates, occupancy & B-factor
Return type:

4 floats
Atoms.differences(reference, selection=None, reference_selection=None, check=True)

Positional differences between coordinates by residue: each atom, rms.

Requires same atoms, same order.

Parameters:
  • reference (class Atoms) – atoms
  • selection (Selection or Group) – atoms in self to use.
  • reference_selection (Selection or Group) – atoms in reference to use (must correspond to seletion).
  • check (bool) – atoms must fully match between self and reference selections, else just checks atom name.
Raises AssertionError:
 

if {check and chains, segid, resnum} or atnam do not match between self and target selections.
Atoms.from_file(filename, fileobj=None, method='default')

Reads scatterers from PDB file.

Parameters:
  • filename (str|NoneType) – PDB file or None.
  • fileobj (fileobject) – required if filename is None.
  • method (str) – to call more sophisticated library for PDB input.

Enables Atoms.checkbounds.

Atoms.from_list(attribute, mylist)

Safe copy by value, the elements of mylist into atoms.attr.

Parameters:
  • attribute (str) – Atoms attribute name to be set, or “x”, “y”, “z” to set one of the coordinates of the 2D matrix.
  • mylist (sequence) – array-like values

Note

If called from C, requires list and all elements to be PyObjects.

Note

As copy-by-value, this is perhaps the safest in-memory way of getting data into RSRef from external programs.

Safety checks: noting that valid Atoms attributes are instantiated as None, will raise exceptions if the attribute does not exist or has been assigned previously to an array of different dimensions.

Atoms.from_reader(filename)

Coordinate information from MMTK PDB reader.

Parameters:filename (string) –

Links self.xyz to torsion angle array. .. todo:: Set link to torsion elsewhere if MMTK used more generally. .. todo:: (with Brynmor) - set self.polymer[serial_number]=True for ATOM, else False.

Atoms.init_non_pdb()

Completes an instance when attributes cannot be read from PDB file.

Note

Requires: coordinates self.xyz to be set with correct number of atoms.

See also

from_list - might have been used to set coordinates from an external program, and the PDB file may not be available to initialize all attributes required by RSRef.

Warning

Attributes are filled with guesses, with possible odd consequences... particularly on writing coordinates, but it is anticipated that this method will only be called by external programs that will handle such functions independently.

Warning

No support (yet) for anisotopic Us. Not sure where would come from or how to initialize.

Atoms.is_alt(i, j)

True if atom i is an alternate location of atom j

Atoms.is_close(attr, value, atol=0.01, rtol=0.0, nan_exception=True)

Boolean for atoms whose attribute close to value.

Parameters:
  • attr (str) – one of the one-dimensional float arrays, eg. b, occ
  • value (float) – target
  • atol (float) – finds absolute(array[:]-value) <= (atol + rtol*value)
  • rtol (float) – see above
  • nan_exception (bool) – raise exception if isnan(value), else return [False]*shape_array
Returns:

True where close
Return type:

bool ndarray

Note

think about input precision of PDB file when setting atol.

See also

are_close

Atoms.is_corresponding(other, attr, value, other_value, atol=0.01, rtol=0.0, alts_ok=False, exception=True)

Check that self and other attribute have value & other value for a common atom.

Parameters:
  • other (Atoms) –
  • attr (str) – one of the one-dimensional float arrays, eg. b, occ
  • value (float) – expected in self.attr
  • other_value (float) – expected in other.attr
  • atol (float) – finds absolute(array[:]-value) <= (atol + rtol*value)
  • rtol (float) – see above
  • alts_ok (bool) – allows matches between different alternative conformers.
  • exception (bool) – on failure, throw exception rather than warning.
Returns:

corresponds
Return type:

bool
Raises KeyError:
 

on failure if exception=True
Atoms.is_cterm(i, j)

True if atom i is C-terminal of atom j, same chain & backbone

Atoms.join(added)

Join two Atoms instances.

Warning

limits are recalculated with self.margin.

Warning

incompatible with update_pdb()

Todo

Incompatible with xyz as property

Atoms.label(i)

Hashable id for atom i:

[segid/]chain/residue number/atom name/alternative locator.

Parameters:i (int) –
Returns:label
Return type:str

See also

labels

Atoms.labels(indices)

Hashable ids for atoms with specified indices:

[segid/]chain/residue number/atom name/alternative locator.

Parameters:indices (array-like) –
Returns:labels
Return type:list(str)

See also

label

Atoms.labels_close(attr, value, atol=0.01, rtol=0.0, nan_exception=False)

Labels for atoms whose attribute close to value.

Parameters:
  • attr (str) – one of the one-dimensional float arrays, eg. b, occ
  • value (float) – target
  • atol (float) – finds absolute(array[:]-value) <= (atol + rtol*value)
  • rtol (float) – see above
  • nan_exception (bool) – raise exception if isnan(value), else return empty list
Returns:

list of indices where close
Return type:

bool ndarray

Note

think about input precision of PDB file when setting atol.

See also

are_close, labels

Point self.xyz to the array used in torsion angle optimization.

Returns:self
Return type:class Atoms
Atoms.max_diff(reference, selection=None, reference_selection=None, verbose=False)

Max absolute difference between coordinate sets: xyz, occupancy, B

Requires atoms to be in the same order

Parameters:
  • reference (class Atoms) – atoms
  • selection (Selection or Group) – atoms in self to use.
  • reference_selection (Selection or Group) – atoms in reference to use (must correspond to seletion).
Returns:

RMS deviation in coordinates, mean absolute difference in coordinates, occupancy & B-factor
Return type:

4 floats
Atoms.neighbors(distance=3.0, verbose=True)

Find atoms that might be close to those being evaluated.

Parameters:distance (float) – within which considered close.

Todo

if fast, make into a property, so don’t have to call. Could monitor whether coordinates have been changed significantly.

See also

symmetry.Symmetry.neighbors for neighbors in presence of symmetry.

Atoms.pdb_coord_records = ('ATOM', 'HETATM')
Atoms.randomize(rms_xyz=0.0, std_o=0.0, std_b=0.0, seed=None, fix_an_o=False)

Add normally distributed error to atomic parameters.

Parameters:
  • rms_xyz (float) – target total rms error to be split into x,y,z components
  • std_o (float) – target standard deviation of occupancy error to be applied
  • std_b (float) – target standard deviation of b-factor error to be applied.
  • seed (int or NoneType) – for random number generator - for reproducible results.
  • fix_an_o (bool) – leave o[0] unchanged so that occupancies not co-linear with scaling in refinement.
Returns:

actual errors applied to xyz (rms), occupancy (std) & B (std).
Return type:

3 floats
Atoms.residue(i, contiguous=False)

Atoms in the same residue as atom i.

Parameters:
  • i (int) – atom index
  • contiguous (bool) – assert that the atoms must be contiguous in array
Returns:

atoms in same residue
Return type:

Selection
Atoms.residueID(i)

Hashable id for residue of atom i:

Returns:([segid|chain], residue number, insert), where a non-blank chain takes precedence over segid.
Return type:tuple(str, int, str)
Atoms.same(other)

Same names. Coordinates, B, occupancy can differ.

Warning

does not test derived attributes such as evaluate.

Atoms.same_conformer(verbose=False)

Identify pairs of atoms in the same conformer.

Defined in practice as sharing the same conformer name, or if either of the pair of atoms is single conformer.

Returns:A[i,j] is True when i & j are in the same conformer
Return type:ndarray(shape=(natom, natom), dtype=bool)
Atoms.select(selection)

Subset of Atoms instance, defined by a boolean array.

Parameters:selection (ndarray(type=bool)) – True for atoms to be copied.

Warning

limits are recalculated with self.margin.

Warning

incompatible with update_pdb()

Todo

incompatible with xyz as a property

Atoms.sort(selection=None, template=None, use_segid=False, return_matched_template=False, verbose=False, quiet=False)

Reorder atoms into the same order as corresponding atoms in template.

Parameters:
  • selection (Selection) – Return only selected atoms of self.
  • template (class Atoms.) – Self to be sorted into same order as template which should contain same or super-set of atoms in self.
  • use_segid (bool) – May want to skip as chain always required, but segid optional.
  • return_matched_template – in addition to the newly ordered Atoms, return the Selection of template atoms that were matched.
  • verbose (bool) – list un-matched atoms
  • quiet (bool) – silent (else print summary)
Atoms.subset(start, end=None)

Subset of Atoms instance, starting at start, and ending at end-1.

Parameters:
  • start (int) – 1st atom (starting at 0)
  • end (int) – last atom (default is start+1 for single atom)

Warning

limits are recalculated with self.margin.

Warning

incompatible with update_pdb()

Disconnect self.xyz from torsion angle optimization.

Returns:self
Return type:class Atoms
Atoms.update_pdb(infile, outfile='rsref.pdb', header=None, interlace=False)

Copy infile to outfile, updating coordinates, occupancies and B-factors

Parameters:
  • infile (str) – PDB file name.
  • outfile (string or file object) – PDB file name or open file.
  • header (str) – inserted at top of output PDB
  • interlace (bool) – alternate input and output atom pairs (for debugging)
Returns:

number of atoms written
Return type:

int

..note:: infile & outfile must contain the same atoms in the same order. .. deprecated:: (mostly) - replaced by self.write

Atoms.write(atoms=None, outfile='rsref.pdb', header=None, anisou=False, ca=False, rsref=None, options=None, stats=True, symmetry=None, symout=None, neighbors_only=False)

Write PDB file.

If symmetry is provided, a non-standard PDB extension is invoked to add neighboring (equivalent) atoms after the standard PDB output. The neighbors may deviate from the PDB standard in several ways, depending on options selected during the prior symmetry expansion:

  • The atoms may not correspond to comprise exactly one asymmetric unit.

  • Residues or chains may not be complete if only neighboring atoms were selected.

  • Columns 68-72 of ATOM/HETATM records (usually not used) document the crystallographic symmetry operator that generated the atom (if not the unit matrix):

    • Columns 68-69 contain the zero-filled space group operator number used to generate the atom.
    • Columns 70-72 contain the unit cell translations down a, b, c expressed as modulo-10 single digits, eg. 109 means +1 unit cell along a, 0 along b and -1 unit cell along c.

  • Columns 73-76, containing the segid, in the Xplor/CNS variant PDB, contain the non-crystallographic symmetry (NCS) operator name (if not named ‘unit’).

A large number of chain identifiers may be required, and are provided on first-come/first-served basis:

  • The original chain IDs are used if not in conflict.
  • A new ID is generated from the 1st letter of the segid or NCS operator name.
  • If these have already been used, generate a new ID starting from the end of the alphabet, then going through numbers, then lower case letters.
Parameters:
  • atoms (class Atoms) – Coordinates to write out or None for self.
  • outfile (string or file object) – PDB file name or open file.
  • header (str) – inserted at top of output PDB
  • anisou (bool) – write anisotropic displacement parameters (currently copied verbatim from intput, and therefore not supporting change in cell, structure or symmetry-equivalent. Use with care!)
  • ca (bool) – write out only CA atoms.
  • rsref (class RSRef or NoneType) – Real-space refinement instance from which statistics and unit cell are taken.
  • options (class Options) – Calling program options used in documenting PDB file, defaults to Q.option.
  • stats (bool) – Add refinement statistics to the remarks.
  • symmetry (class Symmetry or NoneType) – Expand symmetry (local, space group, lattice) according to a previously instantiated symmetry into a non-standard PDB file.
  • symout (string or NoneType) – which of the above equivalents to output, ‘local’ or ‘full’.
  • neighbors_only (bool) – write only if close=True (excluding evaluate=True), to output only the neighbors of a selection.
Returns:

number of atoms written
Return type:

int

Note

If chain or residues completion has been selected during symmetry expansion, evaluate and close may no longer be mutually exclusive.

Note

Requires the input PDB to have unique serial numbers (atom numbers) for each atom, so take care with manually edited PDB files.

Atoms.xyz
class atoms.Collection(*seq, **named)

Bases: atoms.Group

Group with a Selection for each value of an Atoms attribute.

Examples would include Selections for each chain, or each residue.

Parameters:
  • seq (dict or iterable) – (if present) either a pre-existing Group dictionary, or an iterable of paired (name, Selection).
  • named – a sequence of name=Selection arguments.
class atoms.Commands

Bases: object

Atoms-related cmd2 commands for importing/subclassing to other modules.

do_pdbout(instance, arg)

Write coordinates (symmetry expansion as per command-line arguments). Usage: pdbout [options] [Header inserted into top of PDB file]

Options:
-h, --help show this help message and exit
-o FILE, --file=FILE
 Output file name (required argument).
-a, --anisotropic
 Output anisotropic U, riding w/ coordinates from input PDB.
-c, --c_alpha Output only C_alphas.
do_select(instance, arg)

Name selection(s) of atoms. Usage: select [options] [SELECTION_EXPR]

SELECTION_EXPR: logical expression of <Selection(s)> (string) using array logical operators: &, |, ==, !=, ~, >, >=, (, ), ... evaluated in the task namespace. <Selection> is an existing instance of class Selection or a new one instantiated with S(<criterion>), where string <criterion> is a logical array expression using keywords such as residue number, chain, atom number, synonyms or unique abbreviations, see documentation for Selection. SELECTION_EXPR should be quoted to avoid shell commands / redirects etc, and if provided as a named argument, must be devoid of white-space.

Examples:

select -C rigid -n N_domain S('chain == A') & S('residue num <= 105')
select -C protein -n C S('(chai == C) & (residue_ty != HOH)')
select -C all -n catalytic "rigid['N_domain'] | S('resnam == ATP')"
select -C mycollection -a resnum -F protein -S C
select --collection=chains --attr=chain
Options:
-h, --help show this help message and exit
-C NAME, --collection=NAME
 Collection (dictionary) into which selection is placed (default: None –> “collection” or name of attribute if -a specified).
-n NAME, --name=NAME
 Unique name to be given to selection (default: None –> “default”). (-a (–attr) & -n (–name) are mutually exclusive.)
-a ATOM_ATTR, --attr=ATOM_ATTR
 Selections are made (and named) for each unique value of ATOM_ATTR in the coordinates (see -d, -f). ATOM_ATTR must be specified as a single-word abbreviation/synonym recognized in Selection expressions, eg. –attr=chain might give selections A, B..., while –attr=resnum might give 23, 24,... (-a (–attr) & -n (–name) are mutually exclusive.)
-S NAME, --selection=NAME
 Selection or dictionary (group) from which –attr subset is to be drawn (default: None –> all atoms).
help_SELECTION_EXPR()
class atoms.Documentation

User-level documentation for imports.

class Selection_Group
introduction

Generic documentation for import into other modules.

class atoms.Group(*seq, **named)

Bases: dict

Manage a dictionary of atom group selections.

Performs consistency checks:

  • Items are class Selection.

  • Selections are from the same Atoms object.

  • Selections can overlap only if they are subsets of one another:

    • Eliminating most conflicts, but...
    • Allowing a group w/in a group to be refined, but...
    • May be commutivity issues, but hopefully small for incremental changes during a refinement that will not stop convergence.
Parameters:
  • seq (dict or iterable) – (if present) either a pre-existing Group dictionary, or an iterable of paired (name, Selection).
  • named – a sequence of name=Selection arguments.
check()
Raises AssertionError:
 for items that are not Selections, or if selections have different Atoms objects, or if Selections overlap w/o being subsets.
empty()
Returns:True if selection has zero atoms.
Return type:bool
expand()

Iterates recursively through (nested) groups yielding each Selection.

Returns:Atomic selection.
Return type:class Selection
Raises TypeError:
 if encounters any value that is not Group or Selection

Todo

What if None? - is there a need to return None immediately?

expand_items()

Iterates recursively through (nested) groups yielding each (key, Selection).

Returns:key, Atomic selection.
Return type:Selection
Raises TypeError:
 if encounters any value that is not Group or Selection

Todo

What if None? - is there a need to return None immediately?

from_criteria(criteria=None, atoms=None)
Parameters:
  • criteria (string, list, tuple or dict(string(s))) – boolean expression string(s) for selection of atoms as in Selection.
  • atoms (class Atoms) – Coordinates that are to be selected from.
from_selections(selections=None)
Parameters:selections (sequence of Selections (list, tuple, dict)) – Atom selection(s)
inAny()

Selection array, True for atoms in any group.

Returns:atoms in any of the groups.
Return type:class Selection
static names(seq)

List of names for selection(s) w/in Group.

Returns:names if Group or None if Selection.
Return type:list of strings or NoneType
static selections(seq)

List of selection(s) w/in Group or Selection.

class atoms.Selection

Bases: numpy.ndarray

Boolean array with methods for atom selection.

Supports selection based on any of the attributes of PDB ATOM & HETATM records. Criteria are provided as strings to Selection methods (S) which are evaluated as Python expressions, and can be combined using Python bit-wise logical operators, for example: S(chain == A) | (S(chai==B) & (S(residue number >= 30) & S(resnu <= 50))), or ... S((chain == A) | (chain == C))

These selections can then be used as slices to perform calculations on subsets of Atoms attributes, e.g. atoms.b[selection] = 10.0, or within iterators over all atoms in an Atoms object.

One of two command parsers is used, chosen (by default) according to whether the command contains a unary operator (&, |, ~, ^, <<, >>) and is therefore a compound boolean expression, or is simple.

In criteria, Python syntax is relaxed in the following ways:

  • A selection of common synonyms can be substituted for the actual Atoms attributes, eg. atom_name for atnam, residue_type for resnam. (In simple expressions, ‘_’ above can be replaced by ‘ ‘ or ‘-‘.)
  • Strings should not be quoted. They will be recognized and quoted internally. Additionally, simple expressions should not be contained within parentheses (it is fine with compound expressions).
  • Names can be reduced to their shortest unique start, eg. ‘resna’ for ‘resnam’ allows ‘resnam’ to be distinguished from ‘resnum’.
  • Simple expressions only - case insensitive.

The abbreviated form of Selection, S(<criterion>) can be accessed with the following Python commands: import functools; S = functools.partial(Selection, atoms), where atoms is an instantiation of class Atoms.

Warning

A select command used in a shell script may need its expression enclosed in double quotes to avoid shell interpretation of logical operators.

asSelection(input_array)

Convert input to a selection.

static attribute(synonym)

Unique Atoms attribute name from any of its synonyms.

center()

Average coordinate (center of mass of equal mass atoms).

empty()
Returns:True if selection has zero atoms.
Return type:bool
expand()

Dummy to make the recursive Group.expand polymorphic for Selection.

Returns:self
Return type:class Selection
Raises TypeError:
 if encounters any value that is not Group or Selection
expand_items()

Dummy to make the recursive Group.expand_items polymorphic for Selection.

Returns:self
Return type:class Selection
Raises TypeError:
 if encounters any value that is not Group or Selection
following(current)

Index of next atom in Selection.

Parameters:current (int) – index
Returns:next selected index or None
Return type:int or NoneType
get()
inAny()

This method is solely for polymorphic compatibility with Group, enabling either to be treated as a Selection via inAny() :return self: :rtype Selection:

is_amino_acid()

True if selection contains 1 and only 1 N, CA, C, O in same residue.

is_of_atoms(atoms, verbose=True)

True if Selection’s atoms attribute is atoms.

key = 'conformer'
name = 'conformer'
operators = ['<>', '!=', '==', '>=', '<=', '>', '<', '~', '^', '|', '&', '>>', '<<', '%', '//', '/', '**', '*', '-', '+']
prefix_set = set(['conform', 'c', 'conforme', 'co', 'conf', 'con', 'confo', 'conformer', 'confor'])
previous(current)

Index of prior atom in Selection.

Parameters:current (int) – index
Returns:prior selected index or None
Return type:int or NoneType
select(criterion, compound=True)

Set self to True for all atoms meeting the criterion.

Parameters:
  • criterion (str) – logical expression operating on an Atoms attribute, eg. 'resnum >= 3' or :code`’chain == A’, or :code:‘(resnum >= 3) & (chain == A)’`
  • compound (bool or NoneType) – Force criterion to be considered compound if True, simple if False, or determine if None.
Returns:

self
Return type:

ndarray subclass Selection

Warning

A select command used in a shell script may need its expression enclosed in double quotes to avoid shell interpretation of logical operators.

Changed in version 0.5.5: 10/18/15 default compound changed from None so that boolean selections can be provided uniformly eg. macromolecule instead of macromolecule==True for simple.

synonyms = []
test()
u

Boolean repeated 9-fold for all elements of selected U tensors.

unique_set = set(['conform', 'co', 'confor', 'conf', 'con', 'confo', 'conformer', 'conforme'])
v2 = set(['conform', 'c', 'conforme', 'co', 'conf', 'con', 'confo', 'conformer', 'confor'])
value = set(['conform', 'c', 'conforme', 'co', 'conf', 'con', 'confo', 'conformer', 'confor'])
whichAttr(strattr)

Returns the Atoms attribute indicated by a (minimally unique) string.

Parameters:strattr (str) – Atoms coordinate attribute, case ignored.
Returns:attribute, attribute name
Return type:class Atoms object, string
Raises ValueError:
 if no attribute, or ambiguous
x = 8
class atoms.Tasks

Bases: object

Holder of atoms-centric task methods to be subclassed by other programs.

Superclass for atoms-related common tasks.

Warning

If this class defines pre-requisites on which other tasks depend, then this superclass must be instantiated before the other tasks are defined. If this class depends on pre-requisites defined elsewhere, then it must be instantiated afterwards. It may not be possible to satisfy both requirements!

getselect(name, flatten=False, **kwargs)

Retrieve a previously saved Selection or Group.

Polymorphic, returning searching the default collection / item names that might have been used in the preceeding select command.

Parameters:
  • name (str) – name of Selection, Group or Group item, eg. “mySelection”, “myGroup”, “myGroup[‘item’]” or “[‘item’]”.
  • flatten (bool) – Reduce Group to single Selection with inAny().
  • default – returned if no match instead of AttributeError
read_coords(new_file=None)
Parameters:new_file (str) – PDB file to be read.

Warning

Does not automatically recalculate statistics etc..

read_coords_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

select(collection=None, name=None, selection="S('all')")

Select atoms for evaluation / refinement.

Parameters:
  • selection (string or NoneType) – a bit-wise logical expression of class Selection variables and Selection.select or S operators. None: instantiate with an empty Selection for later definition. Default: all atoms.
  • name (dictionary key or NoneType) – name of the selection. None: defines the selection to be used when groups are not selected.
  • collection (string or dict or NoneType) – (name of) dictionary into which selection is to be placed. None: defines default refinement / evaluation selection.
select_attr(attribute, collection=None, selection=None)

Make a collection with subset groups sharing same Atoms attribute.

Parameters:
  • attribute (str) – name of the Atoms attribute to be grouped. Selection.synonyms / shortened forms are acceptable. Examples: ‘chain’, ‘residue number’, ‘resnam’.
  • selection (string or NoneType) – group/select only atoms that are also within selection, or in any of a Group of selections. This should be a string that evaluates to a previously defined Selection or Group. Default: all atoms.
  • collection (str) – name of dictionary into which selection is to be placed. None: defaults to the name of the attribute.
Returns:

dictionary containing selections for each unique value of attribute in selection(s).
Return type:

class Group

Warning

the Group returned could be clobbered if the default collection name is used a second time (if selecting the same attribute from different selections).

select_attr_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

select_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

update_coords(new_file=None, header=None)
Parameters:new_file (str) – PDB file to be written.

Deprecated since version for: write_coords, but this remains a no-frills alternative.

write_coords(new_file=None, header=None, anisotropic=False, ca=False, neighbors_only=False)
Parameters:
  • new_file (str) – PDB file to be written.
  • anisotropic (bool) – Write riding anisotropic Us.
  • ca (bool) – Write only C_alphas.
  • header (str) – to be inserted at top of PDB file.
  • neighbors_only (bool) – output atoms that are close, but not selected evaluation (non-standard), noting “close” can contain “evaluation” atoms after residue or chain completion.
write_coords_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

class atoms.Vec(vector=None, unit=None, length=None)

Bases: object

Immutable general vector w/ efficiencies from storing unit vector & length

comp(other)

Scalar projection of self (component) onto other.

Parameters:other (Vec) –
Returns:component
Return type:Vec
dot(other)

Dot product of self and other.

Parameters:other (Vec) –
Returns:dot product
Return type:Vec
length()
norm
proj(other)

Vector projection of self onto other.

Parameters:other (Vec) –
Returns:projection
Return type:Vec
udot(other)

Dot product of unit vectors along directions of self, other.

Parameters:other (Vec) –
Returns:unit dot product
Return type:Vec
unit
vec
class atoms.VecList(iterable=None)

Bases: list

List of Vec(tors).

align(other, lengths=True, normalize=False, verbose=False)

Find the permuted order of self vectors that aligns best with other.

Parameters:
  • other (VecList) – vectors to which self is to be aligned, same dimensions as self
  • lengths (bool) – use magnitudes, not just directions (unit vectors)
  • normalize (bool) – scale each VecList by dividing by the sum of magnitudes - see note below.
Returns:

(max-score, permutation, ave-score)
Return type:

(float, int-tuple, float)

Score is defined as the average for all paired vectors of the absolute values of their dot products. (Absolute so that +/- direction is arbitrary.) Permutation is the order of elements in self for the best (maximal) score. Ave-score is this score averaged over all possible permutations. If not lengths and not normalize, score will be the average cosine misalignment between vectors.

When the VecList are eigenvectors of a symmetric tensor, the sum of lengths is the trace. For an anisotropic U tensor, Ueq = trace/3 & B = 8 pi2 Ueq, so normalization makes equivalent the isotropic or mean square displacements.

align_to_vec(vector, intermediate=(0.0, 1.0), cosine=True, degrees=True, verbose=True)

Misalignment of the “unique” axis in self with a single vector.

For VecList lengths of 3 (eg. principal axes of anisotropic U), find the most unique axes in self (depends on prolateness) and calculate the deviation from the direction of vector.

For a prolate ellipsoid, the longest axis is unique, and for oblate it is the shortest. For prolate, the misalignment is between the principal axis and the vector; for prolate, it is the deviation from orthogonality with the shortest vector.

Note the potential advantage of aligning only the unique axis, as we avoid the indeterminate alignment when the two other axes are the same (perfect prolate or oblate).

Does not care about the +/- direction of vectors, so the maximum misalignment is 90 deg..

Parameters:
  • vector (Vec) – same dimensions as self
  • intermediate ((float, float)) – beyond these prolateness limits, the ellipsoid will be considered pure oblate and prolate respectively, transitioning between the two with a linear ramp between the limits.
  • cosine (bool) – output cosines of angles, else angles
  • degrees (bool) – angles in degrees, else radians
  • invert (bool) – allow sign of vectors to be switched, so that the maximum deviation is 90 degrees.
Returns:

(misalignment, anisotropy-weighed misalignment, weight)
Return type:

(float,) x 3

See also

align_unique to calculate misalignment of unique vectors each from a list.

See also

align_vecs to calculate misalignment of all vectors.

See also

align to permute the order of vectors to fine the best match.

Weighting is by the geometric mean of (1-anisotropy) so that a spherical atom would have zero weight.

align_unique(other, intermediate=(0.0, 1.0), cosine=True, degrees=True, verbose=True)

Misalignment of the “unique” axis in self and other.

For VecList lengths of 3 (eg. principal axes of anisotropic U), find the most unique axes in self & other (depends on prolateness) and calculate the deviation from expected perfect alignment.

For a prolate ellipsoid, the longest axis is unique, and for oblate it is the shortest. if aligning two of the same, perfect alignment would put these parallel. If one each of prolate and oblate, perfect alignment would put these orthogonal.

Note the potential advantage of aligning only the unique axis, as we avoid the indeterminate alignment when the two other axes are the same (perfect prolate or oblate).

Does not care about the +/- direction of vectors, so the maximum misalignment is 90 deg..

Parameters:
  • other (VecList) – same dimensions as self
  • intermediate ((float, float)) – beyond these prolateness limits, the ellipsoid will be considered pure oblate and prolate respectively, transitioning between the two with a linear ramp between the limits.
  • cosine (bool) – output cosines of angles, else angles
  • degrees (bool) – angles in degrees, else radians
  • invert (bool) – allow sign of vectors to be switched, so that the maximum deviation is 90 degrees.
Returns:

(misalignment, anisotropy-weighed misalignment, weight)
Rtype (float,) x 3:
 

See also

align_vecs to calculate misalignment of all vectors.

See also

align to permute the order of vectors to fine the best match.

See also

align_to_vect, for alignment of the unique vector from a list to a single pre-defined vector.

Weighting is by the geometric mean of (1-anisotropy) so that a spherical atom would have zero weight.

align_vecs(other, permutation=None, cosine=True, degrees=True, invert=True)

Deviation between the directions of permuted self vectors and other.

Parameters:
  • other (VecList) – same dimensions as self
  • permutation (tuple of ints or NoneType) – order of vectors in self to be compared. If, None, use input order.
  • cosine (bool) – output cosines of angles, else angles
  • degrees (bool) – angles in degrees, else radians
  • invert (bool) – allow sign of vectors to be switched, so that the maximum deviation is 90 degrees.
Returns:

angles by which permuted self vectors are aligned from other
Return type:

ndarray
append(vec)

In-place append of a Vec instance.

extend(veclist)

In-place extension by an iterable of Vec instances.

extend_svd(values, uvecs)

In-place extension from the output of numpy.linalg.svd.

Parameters:
  • values (ndarray(shape=N, dtype=float)) – N “s” singular (eigen) values, 2nd object returned by svd decomposition of [..., M, N] matrix(ces).
  • uvecs (ndarray(shape=(N,N) dtype=float)) – N “v” unitary [..., N, N] matrix(ces), 3rd object returned by svd, where each row [..., N, 0:N] (fastest dimension) would be an eigen vector.

If the VecList is to be used for the eigenvectors / principle components of a single tensor, then the input to extend_svd should be the results of linalg.svd applied to the single [M, N] matrix. If linalg.svd is broadcast with [L, M, N] input, then extend_svd should be called with the slices for the single-matrix l: values[l, ...], uvecs[l, ...]

insert(i, vec)

In-place insertion of a Vec instance before item i.

mean()

Average vector length.

norms
permute()

Iterate through all possible orders of Vec in VecList.

Returns:yields (permuted copy of self, self indices in the order of permuted)
Return type:(VecList, int-tuple)
reordered(order)

Reordered copy.

Parameters:order (int-iterable) – indices for elements of self in the order desired
Returns:new
Return type:VecList
sort(cmp=<built-in function cmp>, key=None, reverse=False)
sum()

Sum of vector lengths.

sumproduct(other, normalize=False, absolute=False)

Sum of scalar products of the corresponding vectors in self and other.

Parameters:
  • other (VecList) – (same dimensionality as self)
  • normalize (bool) – noralize, using unit vectors for self and other, then now returning the sum of cosines between paired vectors.
  • absolute (bool) – sum absolute values of products, else signed values.
sumsq()

Sum of vector lengths squared.

class atoms.dummy_chain(xyz)
atoms.is_number(s)
atoms.is_quoted_string(s)
atoms.is_triple_quoted_string(s)
atoms.iso_like(anisou, isotropic_b=None)

Scale anisotropic U tensor to match the isotropic B.

Parameters:
  • anisou (ndarray/NoneType) – U tensor if defined, else None.
  • isotropic_b (float) – B to which U is to be optionally scaled.
Returns:

scaled U if defined, else None
Return type:

numpy.matrix[3,3]/NoneType

See also

Anisotropics.iso_like() for coordinate set.

atoms.isotropic(anisou)

Convert anisotropic U to isotropic B.

Parameters:anisou (ndarray/NoneType) – U tensor.
Returns:isotropic B-factor.
Return type:float

See also

Anisotropics.isotropic() for coordinate set.

atoms.masked_determinants(a)

Determinants of a set of M, NxN matrices in a masked array.

Parameters:a (numpy.MaskedArray) – shape = (M, N, N)
Return inverse:
Rtype numpy.MaskedArray:
 shape = (M, N, N)
atoms.masked_inverses(a)

Inverses of a set of M, NxN matrices in a masked array.

Parameters:a (numpy.MaskedArray) – shape = (M, N, N)
Return inverse:
Rtype numpy.MaskedArray:
 shape = (M, N, N)
atoms.masked_norm(a, axis=0)

Normalize a masked array.

Parameters:
  • a (numpy.ma.MaskedArray) – dtype=float
  • axis (int) – along which the sums will be 1.0
Returns:

normalized, same shape, type as a
Return type:

numpy.ma.MaskedArray
atoms.matmul(a, b)

Poorman’s numpy.matmul(), due in version 1.10, specific for 2 x 3-D arrays

atoms.number_selections(seq)
atoms.quoteString(s)
atoms.triangular(anisou)

Top right triangle of U for PDB output.

Returns:U-tensor [1,1], [2,2], [3,3], [1,2], [1,3], [2,3] units: Å2, noting that above indices start at 1, but array elements from 0.
Return type:ndarray.shape(6)

See also

Anisotropics.triangular() for coordinate set.

atoms.where(condition, atoms1, atoms2)

Where condition is true, yield x,y,z,B,O from atoms1, else atoms2.

Parameters:condition (ndarray or (class Selection)) – Boolean array
Returns:New set of coordinates merged from atoms1, atoms2
Return type:class Atoms
..note:: requires: condition, atoms1, atoms2 to be of same length and
all other attributes in atoms1 & atoms2 to be identical.