atomium.structures
Structure classes.
- class atomium.structures.Atom(element, x, y, z, id, name, charge, bvalue, anisotropy, is_hetatm=False)[source]
An atom in space - a point particle with a location, element, charge etc.
Atoms are the building blocks of all structures in atomium.
Two atoms are equal if they have the same properties (not including ID).
- 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.
- property anisotropy
The atom’s directional uncertainty, represented by a list of six numbers.
- Return type
list
- bond(other)[source]
Bonds the atom to some other atom.
- Parameters
other (Atom) – the other atom to bond to.
- property bonded_atoms
Returns the atoms this atom is bonded to.
- Return type
set`
- property bvalue
The atom’s B-value - the uncertainty in its position in all directions.
- Return type
float
- property chain
Returns the
Chain
the atom is part of, orNone
if it is not part of one.- Return type
Chain
- property charge
The atom’s charge - usually just zero, or ‘neutral’.
- Return type
float
- copy(id=None)[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
- property covalent_radius
The atom’s covalent radius, based on the atom’s
element()
. If the element doesn’t match any symbol on the Periodic Table, a radius of 0 will be returned.The element lookup is case-insensitive.
- Return type
float
- 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
- property element
The atom’s element symbol. This is used to calculate its mass using a Periodic Table.
- Return type
str
- property het
Returns the
Residue
orLigand
the atom is part of, orNone
if it is not part of one.- Return type
Het`
- property 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
- property is_backbone
Returns
True
if the atom has a backbone atom name.- Return type
bool
- property is_metal
Checks whether the atom’s element matches a metal element.
The element lookup is case-insensitive.
- Return type
bool
- property is_side_chain
Returns
True
if the atom has a side chain atom name.- Return type
bool
- property location
The atom’s location.
- Return type
tuple
- property 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
- property model
Returns the
Model
the atom is part of, orNone
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.
- property 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_chains(*args, **kwargs)[source]
Returns all chain structures 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 chains will be returned.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_hets(*args, residues=True, ligands=True, **kwargs)[source]
Returns all residues and ligands 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.- 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.
- 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.
- 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.
- class atomium.structures.AtomStructure(id=None, name=None)[source]
A structure made of atoms. This contains various useful methods that rely on a
atoms()
method, which the inheriting object must supply itself. All atomic structures also have IDs and names.Two atomic structures are equal if every pairwise atom in their pairing are equal.
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. This will be a lot faster if the structure is a
Model
and ifoptimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
location (tuple) – the centre of the sphere.
radius (float) – the radius of the sphere.
- Return type
set
- property 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
- property charge
The structure’s charge - the sum of all its atoms’ charges.
- Return type
float
- check_ids()[source]
Looks through all the structure’s sub-structures and raises a warning if they have duplicate ID.
- create_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
- property formula
The structure’s formula as a
Counter
dictionary - the count of all its atoms’ elements.- Return type
Counter
- property id
The structure’s unique ID.
- Return type
str
- property mass
The structure’s mass - the sum of all its atoms’ masses.
- Return type
float
- property 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.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_chains(*args, **kwargs)[source]
Returns all other chain structures within a given distance of this structure, excluding itself.
- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_hets(*args, **kwargs)[source]
Returns all other het structures within a given distance of this structure, excluding itself.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all 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
- property 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.
- 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.
- save(path)[source]
Saves the structure to file. The file extension given in the filename will be used to determine which file format to save in.
If the structure you are saving has any duplicate IDs, a warning will be issued, as the file saved will likely be nonsensical.
- Parameters
path (str) – the filename and location to save to.
- 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.
- class atomium.structures.Chain(*residues, sequence='', helices=None, strands=None, **kwargs)[source]
A sequence of residues. Unlike other structures, they are iterable, 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.
helices (list) – the alpha helices within the chain.
strands (list) – the beta strands within the chain.
- atoms_in_sphere(location, radius, *args, **kwargs)
Returns all the atoms in a given sphere within this structure. This will be a lot faster if the structure is a
Model
and ifoptimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
location (tuple) – the centre of the sphere.
radius (float) – the radius of the sphere.
- Return type
set
- property 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
- property charge
The structure’s charge - the sum of all its atoms’ charges.
- Return type
float
- check_ids()
Looks through all the structure’s sub-structures and raises a warning if they have duplicate ID.
- copy(id=None, residue_ids=None, atom_ids=None)[source]
Creates a copy of the chain, with new atoms and residues.
- Parameters
id (str) – if given, the ID of the new chain.
residue_ids (function) – a callable which, if given, will generate new residue IDs.
atom_ids (function) – a callable which, if given, will generate new atom IDs.
- Return type
Chain
- create_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
- property formula
The structure’s formula as a
Counter
dictionary - the count of all its atoms’ elements.- Return type
Counter
- property helices
The alpha helix residues in the chain
- Return type
tuple
- property id
The structure’s unique ID.
- Return type
str
- property internal_id
The molecule’s internal ID - how it is refered to by atomium operations. This will be identical to regular IDs when the model comes from a .pdb file, but .cif and .mmtf files make this distinction.
- Return type
str
- property length
Returns the number of residues in the chain.
- Return type
int
- property mass
The structure’s mass - the sum of all its atoms’ masses.
- Return type
float
- property 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.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_chains(*args, **kwargs)
Returns all other chain structures within a given distance of this structure, excluding itself.
- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_hets(*args, **kwargs)
Returns all other het structures within a given distance of this structure, excluding itself.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all 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
- property present_sequence
The sequence of residues actually present in the atoms present.
- Return type
str
- property 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.
- 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.
- save(path)
Saves the structure to file. The file extension given in the filename will be used to determine which file format to save in.
If the structure you are saving has any duplicate IDs, a warning will be issued, as the file saved will likely be nonsensical.
- Parameters
path (str) – the filename and location to save to.
- property 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
- property strands
The beta strand residues in the chain
- Return type
tuple
- 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(id, name, full_name, *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.
- atoms_in_sphere(location, radius, *args, **kwargs)
Returns all the atoms in a given sphere within this structure. This will be a lot faster if the structure is a
Model
and ifoptimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
location (tuple) – the centre of the sphere.
radius (float) – the radius of the sphere.
- Return type
set
- property 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
- property chain
Returns the
Chain
the structure is part of (if a residue) or associated with (if a ligand).- Return type
Chain
- property charge
The structure’s charge - the sum of all its atoms’ charges.
- Return type
float
- check_ids()
Looks through all the structure’s sub-structures and raises a warning if they have duplicate ID.
- create_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
- property formula
The structure’s formula as a
Counter
dictionary - the count of all its atoms’ elements.- Return type
Counter
- property 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. Or you can just supply a full name when you instantiate the Het.
- Return type
str
- property id
The structure’s unique ID.
- Return type
str
- property mass
The structure’s mass - the sum of all its atoms’ masses.
- Return type
float
- property 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.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_chains(*args, **kwargs)
Returns all other chain structures within a given distance of this structure, excluding itself.
- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_hets(*args, **kwargs)
Returns all other het structures within a given distance of this structure, excluding itself.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all 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
- property 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.
- 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.
- save(path)
Saves the structure to file. The file extension given in the filename will be used to determine which file format to save in.
If the structure you are saving has any duplicate IDs, a warning will be issued, as the file saved will likely be nonsensical.
- Parameters
path (str) – the filename and location to save to.
- 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.Ligand(*atoms, chain=None, water=False, **kwargs)[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.
- atoms(*args, **kwargs)
Returns the atoms in the ligand.
- Return type
set
- atoms_in_sphere(location, radius, *args, **kwargs)
Returns all the atoms in a given sphere within this structure. This will be a lot faster if the structure is a
Model
and ifoptimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
location (tuple) – the centre of the sphere.
radius (float) – the radius of the sphere.
- Return type
set
- property 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
- property chain
Returns the
Chain
the structure is part of (if a residue) or associated with (if a ligand).- Return type
Chain
- property charge
The structure’s charge - the sum of all its atoms’ charges.
- Return type
float
- check_ids()
Looks through all the structure’s sub-structures and raises a warning if they have duplicate ID.
- copy(id=None, atom_ids=None)[source]
Creates a copy of the ligand, with new atoms.
- Parameters
id (str) – if given, the ID of the new ligand.
atom_ids (function) – a callable which, if given, will generate new atom IDs.
- Return type
Ligand
- create_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
- property formula
The structure’s formula as a
Counter
dictionary - the count of all its atoms’ elements.- Return type
Counter
- property 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. Or you can just supply a full name when you instantiate the Het.
- Return type
str
- property id
The structure’s unique ID.
- Return type
str
- property internal_id
The molecule’s internal ID - how it is refered to by atomium operations. This will be identical to regular IDs when the model comes from a .pdb file, but .cif and .mmtf files make this distinction.
- Return type
str
- property is_water
Returns
True
if the ligand is a water ligand.- Return type
bool
- property mass
The structure’s mass - the sum of all its atoms’ masses.
- Return type
float
- property 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.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_chains(*args, **kwargs)
Returns all other chain structures within a given distance of this structure, excluding itself.
- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_hets(*args, **kwargs)
Returns all other het structures within a given distance of this structure, excluding itself.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all 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
- property 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.
- 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.
- save(path)
Saves the structure to file. The file extension given in the filename will be used to determine which file format to save in.
If the structure you are saving has any duplicate IDs, a warning will be issued, as the file saved will likely be nonsensical.
- Parameters
path (str) – the filename and location to save to.
- 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.Model(*molecules, file=None)[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.
- atoms_in_sphere(location, radius, *args, **kwargs)
Returns all the atoms in a given sphere within this structure. This will be a lot faster if the structure is a
Model
and ifoptimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
location (tuple) – the centre of the sphere.
radius (float) – the radius of the sphere.
- Return type
set
- property 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
- property charge
The structure’s charge - the sum of all its atoms’ charges.
- Return type
float
- check_ids()
Looks through all the structure’s sub-structures and raises a warning if they have duplicate ID.
- create_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
- property formula
The structure’s formula as a
Counter
dictionary - the count of all its atoms’ elements.- Return type
Counter
- property id
The structure’s unique ID.
- Return type
str
- property mass
The structure’s mass - the sum of all its atoms’ masses.
- Return type
float
- property 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.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_chains(*args, **kwargs)
Returns all other chain structures within a given distance of this structure, excluding itself.
- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_hets(*args, **kwargs)
Returns all other het structures within a given distance of this structure, excluding itself.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- optimise_distances()[source]
Calling this method makes finding atoms within a sphere faster, and consequently makes all ‘nearby’ methods faster. It organises the atoms in the model into grids, so that only relevant atoms are checked for distances.
- 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
- property 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.
- 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.
- save(path)
Saves the structure to file. The file extension given in the filename will be used to determine which file format to save in.
If the structure you are saving has any duplicate IDs, a warning will be issued, as the file saved will likely be nonsensical.
- Parameters
path (str) – the filename and location to save to.
- 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(id, name, internal_id)[source]
A molecule is a top-level constituent of a
Model
- a chain, a ligand, or a water molecule. They can have internal IDs, separate from the standard ID.- atoms_in_sphere(location, radius, *args, **kwargs)
Returns all the atoms in a given sphere within this structure. This will be a lot faster if the structure is a
Model
and ifoptimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
location (tuple) – the centre of the sphere.
radius (float) – the radius of the sphere.
- Return type
set
- property 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
- property charge
The structure’s charge - the sum of all its atoms’ charges.
- Return type
float
- check_ids()
Looks through all the structure’s sub-structures and raises a warning if they have duplicate ID.
- create_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
- property formula
The structure’s formula as a
Counter
dictionary - the count of all its atoms’ elements.- Return type
Counter
- property id
The structure’s unique ID.
- Return type
str
- property internal_id
The molecule’s internal ID - how it is refered to by atomium operations. This will be identical to regular IDs when the model comes from a .pdb file, but .cif and .mmtf files make this distinction.
- Return type
str
- property mass
The structure’s mass - the sum of all its atoms’ masses.
- Return type
float
- property 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.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_chains(*args, **kwargs)
Returns all other chain structures within a given distance of this structure, excluding itself.
- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_hets(*args, **kwargs)
Returns all other het structures within a given distance of this structure, excluding itself.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all 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
- property 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.
- 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.
- save(path)
Saves the structure to file. The file extension given in the filename will be used to determine which file format to save in.
If the structure you are saving has any duplicate IDs, a warning will be issued, as the file saved will likely be nonsensical.
- Parameters
path (str) – the filename and location to save to.
- 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.Residue(*atoms, **kwargs)[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.
- atoms(*args, **kwargs)
Returns the atoms in the ligand.
- Return type
set
- atoms_in_sphere(location, radius, *args, **kwargs)
Returns all the atoms in a given sphere within this structure. This will be a lot faster if the structure is a
Model
and ifoptimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
location (tuple) – the centre of the sphere.
radius (float) – the radius of the sphere.
- Return type
set
- property 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
- property chain
Returns the
Chain
the structure is part of (if a residue) or associated with (if a ligand).- Return type
Chain
- property charge
The structure’s charge - the sum of all its atoms’ charges.
- Return type
float
- check_ids()
Looks through all the structure’s sub-structures and raises a warning if they have duplicate ID.
- property 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(id=None, atom_ids=None)[source]
Creates a copy of the residue, with new atoms.
- Parameters
id (str) – if given, the ID of the new residue.
atom_ids (function) – a callable which, if given, will generate new atom IDs.
- Return type
Residue
- create_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
- property formula
The structure’s formula as a
Counter
dictionary - the count of all its atoms’ elements.- Return type
Counter
- property 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. Or you can just supply a full name when you instantiate the Het.
- Return type
str
- property helix
Returns
True
if the residue is part of an alpha helix.- Return type
bool
- property id
The structure’s unique ID.
- Return type
str
- property mass
The structure’s mass - the sum of all its atoms’ masses.
- Return type
float
- property 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.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_chains(*args, **kwargs)
Returns all other chain structures within a given distance of this structure, excluding itself.
- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- nearby_hets(*args, **kwargs)
Returns all other het structures within a given distance of this structure, excluding itself.
This will be a lot faster if the model’s
optimise_distances()
has been called, as it won’t have to search all atoms.- Parameters
cutoff (float) – the distance cutoff to use.
- Return type
set
- property 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
- property 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
- property 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.
- 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.
- save(path)
Saves the structure to file. The file extension given in the filename will be used to determine which file format to save in.
If the structure you are saving has any duplicate IDs, a warning will be issued, as the file saved will likely be nonsensical.
- Parameters
path (str) – the filename and location to save to.
- property strand
Returns
True
if the residue is part of a beta strand.- Return type
bool
- 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.