atomium.structures

Structure classes.

class atomium.structures.Atom(element, x, y, z, id, name, charge, bvalue, anisotropy)[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.
  • bvalue (number) – The B-value of the atom (its uncertainty).
  • anisotropy (list) – The directional uncertainty of the atom.
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.
anisotropy

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

Return type:list
bvalue

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

Return type:float
chain

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

Return type:Chain
charge

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

Return type:float
copy()[source]

Returns a copy of the atom. The new atom will have the same element, location, name, charge, ID, bvalue etc. as the original, but will not be part of any model or other molecule.

Return type: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
element

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

Return type:str
equivalent_to(other)[source]

Two atoms are equivalent if they occupy the same position and have the same properties.

Parameters:other (Atom) – the atom to compare with.
Return type:bool`
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
is_metal

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

The element lookup is case-insensitive.

Return type:bool
location

The atom’s location in space.

Return type:tuple
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
model

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

Return type:Model
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.
name

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

Return type:str
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.

Parameters:cutoff (float) – The radius to search within.
Return type:set
nearby_structures(*args, residues=True, ligands=True, waters=False, **kwargs)[source]

Returns all residues and ligandsin 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.

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

set

rotate(angle, axis, trim=12)[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.
static rotate_atoms(angle, axis, *atoms, **kwargs)[source]

Rotates multiple atoms using an axis and an angle.

Parameters:
  • angle (float) – the angle to rotate by in radians.
  • axis (str) – the axis to rotate around (x, y, or z).
  • *atoms – the atoms to rotate.
structure

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

Return type:Het`
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.
static transform_atoms(matrix, *atoms)[source]

Transforms multiple atoms using some matrix.

Parameters:
  • matrix – the transformation matrix.
  • *atoms – the atoms to transform.
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.
static translate_atoms(vector, *atoms)[source]

Translates multiple atoms using some vector.

Parameters:
  • vector – the three values representing the delta position.
  • *atoms – the atoms to translate.
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.
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
class atomium.structures.AtomStructure[source]

A structure made of atoms. This contains various useful methods that rely on a atoms() method, which the inheriting object must supply itself.

The class would never be instantiated directly.

atoms_in_sphere(location, radius, *args, **kwargs)[source]

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

Parameters:
  • location (tuple) – the centre of the sphere.
  • radius (float) – the radius of the sphere.
Return type:

set

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.

Return type:tuple
charge

The structure’s charge - the sum of all its atoms’ charges.

Return type:float
equivalent_to(other)[source]

Two structures are equivalent if (1) they have the same number of atoms and (2) their atoms can be paired using pairing_with() such that each atom is equivalent to its pair.

Parameters:other (AtomStructure) – the structure to compare with.
Return type:bool
formula

The structure’s formula as a Counter dictionary - the count of all its atoms’ elements.

Return type:Counter
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

id

The structure’s unique ID.

Return type:str
mass

The structure’s mass - the sum of all its atoms’ masses.

Return type:float
name

The structure’s name.

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

Returns all atoms within a given distance of this structure, excluding the structure’s own atoms.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
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 ID (if equal), then element, then by name, 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
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
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
rmsd_with(structure)[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.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:float
rotate(angle, axis, trim=12)[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.
transform(matrix, trim=12)[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.
translate(dx=0, dy=0, dz=0, trim=12)[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.
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.
class atomium.structures.Chain(*residues, id=None, internal_id=None, sequence='')[source]

A sequence of residues. Unlike other structures, they are iterables, and have a length.

Residues can also be accessed using indexing.

Parameters:
  • *residues – The residues that will make up the chain.
  • id (str) – the chain’s unique ID.
  • internal_id (str) – the internal ID used for transformations.
  • sequence (str) – the actual sequence the chain should have.
atoms_in_sphere(location, radius, *args, **kwargs)

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

Parameters:
  • location (tuple) – the centre of the sphere.
  • radius (float) – the radius of the sphere.
Return type:

set

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.

Return type:tuple
charge

The structure’s charge - the sum of all its atoms’ charges.

Return type:float
copy()[source]

Creates a copy of the chain, with new atoms and residues.

Return type:Chain
equivalent_to(other)

Two structures are equivalent if (1) they have the same number of atoms and (2) their atoms can be paired using pairing_with() such that each atom is equivalent to its pair.

Parameters:other (AtomStructure) – the structure to compare with.
Return type:bool
formula

The structure’s formula as a Counter dictionary - the count of all its atoms’ elements.

Return type:Counter
grid(size=1, margin=0)

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

id

The structure’s unique ID.

Return type:str
length

Returns the number of residues in the chain.

Return type:int
mass

The structure’s mass - the sum of all its atoms’ masses.

Return type:float
model

Returns the molecules Model.

Return type:Model
name

The structure’s name.

Return type:str
nearby_atoms(*args, **kwargs)

Returns all atoms within a given distance of this structure, excluding the structure’s own atoms.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
pairing_with(structure)

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 ID (if equal), then element, then by name, 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
pairwise_atoms(*args, **kwargs)

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
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
rmsd_with(structure)

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.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:float
rotate(angle, axis, trim=12)

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.
sequence

Returns the sequence associated with the chain. Note that this is the sequence that the molecule actually has in real life - some may be missing from the actual sequence of residues in the structure.

Return type:str
transform(matrix, trim=12)

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.
translate(dx=0, dy=0, dz=0, trim=12)

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.
trim(places)

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.
class atomium.structures.Het(*atoms)[source]

A direct container of atoms, such as a residue or ligand. Though never instantiated directly, there is an initaliser method for setting up the atom dictionary.

add(atom)[source]

Adds an Atom to the structure.

Parameters:atom (Atom) – the atom to add.
chain

Returns the Chain the structure is part of (if a residue) or associated with (if a ligand).

Return type:Chain
model

Returns the Model the structure is part of, via its chain.

Return type:Model
nearby_structures(*args, **kwargs)[source]

Returns all other het structures within a given distance of this structure, excluding itself.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
remove(atom)[source]

Removes an Atom from the structure.

Parameters:atom (Atom) – the atom to remove.
class atomium.structures.Ligand(*atoms, id=None, name=None, internal_id=None, chain=None, water=False)[source]

A small molecule, usually associated with a polymer chain.

Parameters:
  • *atoms – The atoms that will make up the ligand.
  • id (str) – the ligand’s unique ID.
  • name (str) – the ligand’s name.
  • internal_id (str) – the internal ID used for transformations.
  • chain (Chain) – the chain the ligand is associated with.
  • water (bool) – if True, the ligand will be treated as water.
add(atom)

Adds an Atom to the structure.

Parameters:atom (Atom) – the atom to add.
atoms_in_sphere(location, radius, *args, **kwargs)

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

Parameters:
  • location (tuple) – the centre of the sphere.
  • radius (float) – the radius of the sphere.
Return type:

set

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.

Return type:tuple
chain

Returns the Chain the structure is part of (if a residue) or associated with (if a ligand).

Return type:Chain
charge

The structure’s charge - the sum of all its atoms’ charges.

Return type:float
copy()[source]

Creates a copy of the ligand, with new atoms, and no chain.

Return type:Ligand
equivalent_to(other)

Two structures are equivalent if (1) they have the same number of atoms and (2) their atoms can be paired using pairing_with() such that each atom is equivalent to its pair.

Parameters:other (AtomStructure) – the structure to compare with.
Return type:bool
formula

The structure’s formula as a Counter dictionary - the count of all its atoms’ elements.

Return type:Counter
grid(size=1, margin=0)

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

id

The structure’s unique ID.

Return type:str
mass

The structure’s mass - the sum of all its atoms’ masses.

Return type:float
model

Returns the molecules Model.

Return type:Model
name

The structure’s name.

Return type:str
nearby_atoms(*args, **kwargs)

Returns all atoms within a given distance of this structure, excluding the structure’s own atoms.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
nearby_structures(*args, **kwargs)

Returns all other het structures within a given distance of this structure, excluding itself.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
pairing_with(structure)

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 ID (if equal), then element, then by name, 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
pairwise_atoms(*args, **kwargs)

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
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
remove(atom)

Removes an Atom from the structure.

Parameters:atom (Atom) – the atom to remove.
rmsd_with(structure)

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.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:float
rotate(angle, axis, trim=12)

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.
transform(matrix, trim=12)

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.
translate(dx=0, dy=0, dz=0, trim=12)

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.
trim(places)

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.
water

Returns True if the ligand is a water ligand.

Return type:bool
class atomium.structures.Model(*molecules)[source]

The universe in which all other molecules live, interact, and generally exist.

It is a cotainer of its molecules, residues, and atoms.

Parameters:*molecules – The chains, ligands, and waters that will inhabit the model.
add(molecule)[source]

Add a molecule to the model.

Parameters:molecule – the chain/ligand to add.
atoms_in_sphere(location, radius, *args, **kwargs)

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

Parameters:
  • location (tuple) – the centre of the sphere.
  • radius (float) – the radius of the sphere.
Return type:

set

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.

Return type:tuple
charge

The structure’s charge - the sum of all its atoms’ charges.

Return type:float
dehydrate()[source]

Removes all water ligands from the model.

equivalent_to(other)

Two structures are equivalent if (1) they have the same number of atoms and (2) their atoms can be paired using pairing_with() such that each atom is equivalent to its pair.

Parameters:other (AtomStructure) – the structure to compare with.
Return type:bool
formula

The structure’s formula as a Counter dictionary - the count of all its atoms’ elements.

Return type:Counter
grid(size=1, margin=0)

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

id

The structure’s unique ID.

Return type:str
mass

The structure’s mass - the sum of all its atoms’ masses.

Return type:float
name

The structure’s name.

Return type:str
nearby_atoms(*args, **kwargs)

Returns all atoms within a given distance of this structure, excluding the structure’s own atoms.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
pairing_with(structure)

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 ID (if equal), then element, then by name, 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
pairwise_atoms(*args, **kwargs)

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
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
remove(molecule)[source]

Removes a molecule from the model.

Parameters:molecule – the chain/ligand to remove.
rmsd_with(structure)

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.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:float
rotate(angle, axis, trim=12)

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.
transform(matrix, trim=12)

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.
translate(dx=0, dy=0, dz=0, trim=12)

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.
trim(places)

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.
class atomium.structures.Molecule[source]

A molecule is a top-level constituent of a Model - a chain, a ligand, or a water molecule.

model

Returns the molecules Model.

Return type:Model
class atomium.structures.Residue(*atoms, id=None, name=None)[source]

A small subunit within a chain.

Parameters:
  • *atoms – The atoms the residue is to be made of.
  • id (str) – The residue’s ID.
  • name (str) – The residue’s name.
add(atom)

Adds an Atom to the structure.

Parameters:atom (Atom) – the atom to add.
atoms_in_sphere(location, radius, *args, **kwargs)

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

Parameters:
  • location (tuple) – the centre of the sphere.
  • radius (float) – the radius of the sphere.
Return type:

set

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.

Return type:tuple
chain

Returns the Chain the structure is part of (if a residue) or associated with (if a ligand).

Return type:Chain
charge

The structure’s charge - the sum of all its atoms’ charges.

Return type:float
code

Returns the single letter code, based on its three letter name - or just ‘X’ if it doesn’t match anything.

Return type:str
copy()[source]

Creates a copy of the residue, with new atoms.

Return type:Residue
equivalent_to(other)

Two structures are equivalent if (1) they have the same number of atoms and (2) their atoms can be paired using pairing_with() such that each atom is equivalent to its pair.

Parameters:other (AtomStructure) – the structure to compare with.
Return type:bool
formula

The structure’s formula as a Counter dictionary - the count of all its atoms’ elements.

Return type:Counter
full_name

Returns the residue’s full name, based on its three letter name - or just the three letter name if it doesn’t match anything.

Return type:str
grid(size=1, margin=0)

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

id

The structure’s unique ID.

Return type:str
mass

The structure’s mass - the sum of all its atoms’ masses.

Return type:float
model

Returns the Model the structure is part of, via its chain.

Return type:Model
name

The structure’s name.

Return type:str
nearby_atoms(*args, **kwargs)

Returns all atoms within a given distance of this structure, excluding the structure’s own atoms.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
nearby_structures(*args, **kwargs)

Returns all other het structures within a given distance of this structure, excluding itself.

Parameters:cutoff (float) – the distance cutoff to use.
Return type:set
next

Residues can be linked to each other in a linear chain. This property returns the Residue downstream of this one. Alternatively, if you supply a residue, that residue will be assigned as the ‘next’ one downstream to this, and this residue will be upstream to that. Note that is a separate concept from bonds.

Raises:ValueError – if you try to connect a residue to itself.
Return type:Residue
pairing_with(structure)

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 ID (if equal), then element, then by name, 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
pairwise_atoms(*args, **kwargs)

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
previous

Residues can be linked to each other in a linear chain. This property returns the Residue upstream of this one. Alternatively, if you supply a residue, that residue will be assigned as the ‘previous’ one upstream to this, and this residue will be downstream to that.

Raises:ValueError – if you try to connect a residue to itself.
Return type:Residue
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
remove(atom)

Removes an Atom from the structure.

Parameters:atom (Atom) – the atom to remove.
rmsd_with(structure)

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.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:float
rotate(angle, axis, trim=12)

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.
transform(matrix, trim=12)

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.
translate(dx=0, dy=0, dz=0, trim=12)

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.
trim(places)

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.