atomium.models.atoms

Contains the atom class.

class atomium.models.atoms.Atom(element, x=0, y=0, z=0, id=0, name=None, charge=0, bfactor=0, anisotropy=(0, 0, 0, 0, 0, 0))[source]

An atom in space - a point particle with a location, element, charge etc.

Atoms are the building blocks of all structures in atomium.

Parameters:
  • element (str) – The atom’s elemental symbol.
  • x (number) – The atom’s x coordinate.
  • y (number) – The atom’s y coordinate.
  • z (number) – The atom’s z coordinate.
  • id (int) – An integer ID for the atom.
  • name (str) – The atom’s name.
  • charge (number) – The charge of the atom.
  • bfactor (number) – The B-factor of the atom (its uncertainty).
  • anisotropy (list) – The directional uncertainty of the atom.
element

The atom’s element symbol. This is used to calculate its mass using a Periodic Table.

Return type:str
x

The atom’s x-coordinate.

Return type:float
y

The atom’s y-coordinate.

Return type:float
z

The atom’s z-coordinate.

Return type:float
id

The atom’s unique integer ID. It cannot be updated - the ID the atom is created with is its ID forever.

Return type:int
name

The atom’s name. This is often used to determine what ‘kind’ of atom it is.

Return type:str
charge

The atom’s charge - usually just zero, or ‘neutral’.

Return type:float
bfactor

The atom’s B-factor - the uncertainty in its position in all directions.

Return type:float
anisotropy

The atom’s directional uncertainty, represented by a list of six numbers.

Return type:list
location

The atom’s Cartesian coordinates in (x, y, z) format.

Return type:tuple
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(dx=0, dy=0, dz=0, trim=12)[source]

Translates an atom in 3D space. You can provide three values, or a single vector.

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

Moves the atom to the coordinates given.

Parameters:
  • x (number) – The atom’s new x coordinate.
  • y (number) – The atom’s new y coordinate.
  • z (number) – The atom’s new z coordinate.
transform(matrix, trim=12)[source]

Transforms the atom 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 atom’s coordinates after transforming - the default is 12 decimal places but this can be set to None if no rounding is to be done.
rotate(angle, axis, *args, **kwargs)[source]

Rotates the atom by an angle in radians, around one of the the three axes.

Parameters:
  • angle (float) – The angle to rotate by in radians.
  • axis (str) – the axis to rotate around.
  • trim (int) – The amount of rounding to do to the atom’s coordinates after rotating - the default is 12 decimal places but this can be set to None if no rounding is to be done.
mass

The atom’s molar mass according to the Periodic Table, based on the atom’s element(). If the element doesn’t match any symbol on the Periodic Table, a mass of 0 will be returned.

The element lookup is case-insensitive.

Return type:float
is_metal

Checks whether the atom’s element matches a metal element.

The element lookup is case-insensitive.

Return type:bool
angle(atom1, atom2)[source]

Gets the angle between two atom vectors with this atom as the origin.

Parameters:
  • atom1 (Atom) – The first atom.
  • atom2 (Atom) – Thne second atom.
distance_to(other)[source]

Returns the distance (in whatever units the coordinates are defined in) between this atom and another. You can also give a (x, y, z) tuple instead of another atom if you so wish.

Parameters:other (Atom) – The other atom (or location tuple).
Return type:float
ligand

Returns the Ligand the atom is part of, or None if it is not part of one.

Return type:Ligand
residue

Returns the Residue the atom is part of, or None if it is not part of one.

Return type:Residue
chain

Returns the Chain the atom is part of, or None if it is not part of one.

Return type:Chain
model

Returns the Model the atom is part of, or None if it is not part of one.

Return type:Model
bonded_atoms

Returns the atoms bonded to this one.

Return type:set
bond_to(other)[source]

Bonds the atom to some other atom. The two atoms will be placed inside each other’s bonded_atoms().

Parameters:other (Atom) – The atom to bond to.
unbond_from(other)[source]

Unbonds the atom from some other atom. If they aren’t bonded to begin with, nothing bad will happen.

Parameters:other (Atom) – The atom to unbond from.
nearby_atoms(cutoff, *args, **kwargs)[source]

Returns all atoms in the associated Model that are within a given distance (in the units of the atom coordinates) of this atom. If the atom is not part of a model, no atoms will be returned.

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 radius to search within.
Return type:set
nearby_residues(*args, ligands=False, **kwargs)[source]

Returns all residues in the associated Model that are within a given distance (in the units of the atom coordinates) of this atom. If the atom is not part of a model, no residues will be returned.

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 atom. The new atom will have the same element, location, name, charge, ID, bfactor etc. as the original, but will not be part of any model or other molecule, and will not have any bonds.

Return type:Atom
atomium.models.atoms.atom_query(func)[source]

Decorator which can be applied to any function which returns atoms. It lets you query the output.

The new function looks for keyword arguments which match atom attributes, or which are atom attributes with _regex or __ in them. It then gets the atoms that the unmodified function would return, with the remaining arguments, and then filters them with each specification in the query.

It will also update the new function’s docstring with the explanatory text above.

Parameters:func (function) – The function to enhance.
Return type:function