atomium.models.structures

Contains the base Atom Structure class.

class atomium.models.structures.AtomStructure(*atoms, id=None, name=None)[source]

A structure made of atoms. In practice this class usually acts as a base class to things with more recognisable names, but it can also be used as a generic container of Atom objects, or as a base class for some user defined custom class.

All atom structures are containers of their atoms, and of any sub-structures they might contain.

Parameters:
  • *atoms – The atoms the structure is to be made of. The atoms will be updated with awareness of the new structure they are part of if a sub-class is used. You can also pass in other atom structures here, and their atoms will be used.
  • id (str) – The structure’s ID.
  • name (str) – The structure’s name.
atoms(**kwargs)

Returns the Atom objects in the structure.

You can specify which atoms should be searched in this function. Any atom property can be specified such as name='CA'. String properties can be searched by regex, as in element='[^C]'. Numeric properties can be searched by threshold, as in mass__gt=20.

Return type:set
atom(*args, **kwargs)[source]

Returns the first Atom that matches the criteria given.

Note that atoms are stored unordered in a set so if more than one atom matches the criteria you give, it might not be the same atom that is returned each time you call this method.

You can specify which atoms should be searched in this function. Any atom property can be specified such as name='CA'. String properties can be searched by regex, as in element='[^C]'. Numeric properties can be searched by threshold, as in mass__gt=20.

Return type:Atom
pairwise_atoms(*args, **kwargs)[source]

A generator which yeilds all the pairwise atom combinations of the structure. There will be no duplicates in the returned generator, and the number of returned pairs will be a triangle number.

Return type:tuple
add(obj)[source]

Adds an atom or other AtomStructure to this structure.

Parameters:obj – The atom or structure to add.
remove(obj)[source]

Removes an atom or other AtomStructure from this structure.

Parameters:obj – The atom or structure to remove.
id

The structure’s identifier. Once created it is not modifiable.

Return type:str
name

The structure’s name.

Return type:str
trim(places)[source]

Rounds the coordinate values to a given number of decimal places. Useful for removing floating point rounding errors after transformation.

Parameters:places (int) – The number of places to round the coordinates to. If None, no rounding will be done.
translate(*args, **kwargs)[source]

Translates the structure through space, updating all atom coordinates accordingly. You can provide three values, or a single vector.

Parameters:
  • dx (Number) – The distance to move in the x direction.
  • dy (Number) – The distance to move in the y direction.
  • dz (Number) – The distance to move in the z direction.
  • trim (int) – The amount of rounding to do to the atoms’ coordinates after translating - the default is 12 decimal places but this can be set to None if no rounding is to be done.
transform(*args, **kwargs)[source]

Transforms the structure using a 3x3 matrix supplied. This is useful if the rotate() method isn’t powerful enough for your needs.

Parameters:
  • matrix (array) – A NumPy matrix representing the transformation. You can supply a list of lists if you like and it will be converted to a NumPy matrix.
  • trim (int) – The amount of rounding to do to the atoms’ coordinates after transforming - the default is 12 decimal places but this can be set to None if no rounding is to be done.
rotate(*args, **kwargs)[source]

Rotates the structure about an axis, updating all atom coordinates accordingly.

Parameters:
  • angle (Number) – The angle in radians.
  • axis (str) – The axis to rotate around. Can only be ‘x’, ‘y’ or ‘z’.
  • trim (int) – The amount of rounding to do to the atoms’ coordinates after translating - the default is 12 decimal places but this can be set to None if no rounding is to be done.
mass

The mass of the structure in Daltons - just the sum of its atoms’ masses.

Return type:float
charge

Returns the charge of the structure, based on the charges of its atoms.

Return type:float
formula

Returns the formula (count of each atom) of the structure.

Return type:Counter
center_of_mass

Returns the center of mass of the structure. This is the average of all the atom coordinates, weighted by the mass of each atom.

Returns:(x, y, z) tuple
radius_of_gyration

The radius of gyration of a structure is a measure of how extended it is. It is the root mean square deviation of the atoms’ distance from the structure’s center_of_mass().

Return type:float
pairing_with(structure)[source]

Takes another structure with the same number of atoms as this one, and attempts to find the nearest equivalent of every atom in this structure, in that structure.

Atoms will be aligned first by element, then by name, then by number of bonds, then IDs, and finally by memory address - this last metric is used to ensure that even when allocation is essentially random, it is at least the same every time two structures are aligned.

Parameters:structure (AtomStructure) – the structure to pair with.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:dict
superimpose_onto(other)[source]

Superimoses this structure onto another - it will be translated so that its center of mass matches the other structure’s, then rotated so as to minimise the RMSD.

The other structure must have the same number of atoms.

Parameters:other (AtomStructure) – The structure to superimpose onto. This structure does not move.
rmsd_with(structure, superimpose=False)[source]

Calculates the Root Mean Square Deviation between this structure and another.

You can get the RMSD either of the coordinates as they are, or of superimposed coordinates.

Parameters:
  • structure (AtomStructure) – the structure to check against.
  • superimpose (bool) – if True, the structure will be superimosed first (and then moved back).
Raises:
  • TypeError – if the other structure is not an AtomStructure.
  • ValueError – if the other structure has a different number of atoms.
Return type:

float

grid(size=1, margin=0)[source]

A generator which models a grid around the structure and returns the coordinates of all the points in that grid. The origin is always one of those points, and the grid will be a box.

Parameters:
  • size (int) – The spacing between grid points. The default is 1.
  • margin (int) – How far to extend the grid beyond the structure coordinates. The default is 0.
Return type:

tuple

atoms_in_sphere(**kwargs)

Returns all the atoms in a given sphere within the structure.

You can specify which atoms should be searched in this function. Any atom property can be specified such as name='CA'. String properties can be searched by regex, as in element='[^C]'. Numeric properties can be searched by threshold, as in mass__gt=20.

Return type:set
nearby_atoms(*args, **kwargs)[source]

Gets all atoms within a given cutoff of this structure’s atoms.

You can specify which atoms should be searched in this function. Any atom property can be specified such as name='CA'. String properties can be searched by regex, as in element='[^C]'. Numeric properties can be searched by threshold, as in mass__gt=20.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
nearby_residues(*args, **kwargs)[source]

Gets all atoms within a given cutoff of this structure’s atoms.

You can specify which atoms should be searched in this function. Any atom property can be specified such as name='CA'. String properties can be searched by regex, as in element='[^C]'. Numeric properties can be searched by threshold, as in mass__gt=20.

Parameters:
  • cutoff (float) – the distance cutoff to use.
  • ligands (bool) – if True, ligands will be returned too.
Return type:

set

copy()[source]

Returns a copy of the structure, with its own distinct atoms. Its atoms will have the same ID, location, element, charge, name and bfactor as their counterparts in the original, but will have no bonds, and be a member of no model - even if their counterparts do and are.

Return type:AtomStructure
save(path)[source]

Saves the structure to file, in the format implied by the extension of the path you provide (i.e. giving a path /path/to/file.xyz will save as .xyz etc.).

Parameters:path (str) – The path to save to. The extension you provide here is important as atomium will use that to determine what file format to save as.