atomium.models.molecules

Contains the useful sub-classes of AtomStructure.

atomium.models.molecules.lower(name)[source]

A factory function which creates two functions for querying the lower structures a structure contains - one for returning all, one for returning the first match.

Parameters:name – The kind of structure to look for.
atomium.models.molecules.upper(name)[source]

A factory function which creates a function for querying the upper structure a structure is a part of - or None if there is no single match.

Parameters:name – The kind of structure to look for.
class atomium.models.molecules.Model(*atoms, id=None, name=None)[source]

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

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

Returns the chains in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

set

chain(*args, **kwargs)

Returns the first matching chain in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

Chain

residues(*args, **kwargs)

Returns the residues in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

set

residue(*args, **kwargs)

Returns the first matching residue in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

Residue

ligands(*args, **kwargs)

Returns the ligands in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

set

ligand(*args, **kwargs)

Returns the first matching ligand in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

Ligand

copy()[source]

Creates a copy of the Model, as well as copies of its substructures such as chains etc.

Return type:Model
add(obj)

Adds an atom or other AtomStructure to this structure.

Parameters:obj – The atom or structure to add.
atom(*args, **kwargs)

Returns the first Atom that matches the criteria given.

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

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

Return type:Atom
atoms(**kwargs)

Returns the Atom objects in the structure.

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

Return type:set
atoms_in_sphere(**kwargs)

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

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

Return type:set
center_of_mass

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

Returns:(x, y, z) tuple
charge

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

Return type:float
formula

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

Return type:Counter
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 identifier. Once created it is not modifiable.

Return type:str
mass

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

Return type:float
name

The structure’s name.

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

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

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

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

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

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

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

set

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 element, then by name, then by number of bonds, then IDs, and finally by memory address - this last metric is used to ensure that even when allocation is essentially random, it is at least the same every time two structures are aligned.

Parameters:structure (AtomStructure) – the structure to pair with.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:dict
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(obj)

Removes an atom or other AtomStructure from this structure.

Parameters:obj – The atom or structure to remove.
rmsd_with(structure, superimpose=False)

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

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

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

float

rotate(*args, **kwargs)

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, in the format implied by the extension of the path you provide (i.e. giving a path /path/to/file.xyz will save as .xyz etc.).

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

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

The other structure must have the same number of atoms.

Parameters:other (AtomStructure) – The structure to superimpose onto. This structure does not move.
transform(*args, **kwargs)

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(*args, **kwargs)

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.models.molecules.Chain(*args, rep='', **kwargs)[source]

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

Residues can also be accessed using indexing.

Residues must be connected in series when a chain is created from them. This is necessary because otherwise it won’t know how to return a series of residues in order when you ask for them.

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

Returns the model the structure is part of.

Return type:Model
residue(*args, **kwargs)

Returns the first matching residue in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

Residue

ligands(*args, **kwargs)

Returns the ligands in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

set

ligand(*args, **kwargs)

Returns the first matching ligand in this structure.

Parameters:
  • id (str) – filter by ID.
  • id_regex (str) – filter by ID regex.
  • name (str) – filter by name.
  • name_regex (str) – filter by name regex.
Return type:

Ligand

copy()[source]

Creates a copy of the Chain, as well as copies of its substructures such as ligands etc.

Return type:Chain
verify()[source]

A static method for checking that the residues in a sequence are all connected together, and that there are no gaps in the sequence.

Raises:SequenceConnectivityError – if not properly connected.
Returns:True if the test passes.
length

The number of Residue objects the chain has.

Return type:int
residues(*args, **kwargs)[source]

Returns the Residue objects in the structure.

Warning

If the residues in the chain are not connected together with next and previous, the method will not return all residues. Chains can only be made with connected residues but if you have modified the structure since then, this may produce unexpected results.

Return type:tuple
sequence

Returns the sequence of amino acids as represented in the residues contained.

Return type:str
rep_sequence

The sequence the chain represents, not the actual sequence of the residues present. A model can often have residues missing that the experiment it was created from didn’t capture. This is the true sequence as it should be, not the sequence as it is in the model.

Raises:TypeError – if the sequence given is not str.
add(obj)

Adds an atom or other AtomStructure to this structure.

Parameters:obj – The atom or structure to add.
atom(*args, **kwargs)

Returns the first Atom that matches the criteria given.

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

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

Return type:Atom
atoms(**kwargs)

Returns the Atom objects in the structure.

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

Return type:set
atoms_in_sphere(**kwargs)

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

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

Return type:set
center_of_mass

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

Returns:(x, y, z) tuple
charge

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

Return type:float
formula

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

Return type:Counter
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 identifier. Once created it is not modifiable.

Return type:str
mass

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

Return type:float
name

The structure’s name.

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

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

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

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

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

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

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

set

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 element, then by name, then by number of bonds, then IDs, and finally by memory address - this last metric is used to ensure that even when allocation is essentially random, it is at least the same every time two structures are aligned.

Parameters:structure (AtomStructure) – the structure to pair with.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:dict
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(obj)

Removes an atom or other AtomStructure from this structure.

Parameters:obj – The atom or structure to remove.
rmsd_with(structure, superimpose=False)

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

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

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

float

rotate(*args, **kwargs)

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, in the format implied by the extension of the path you provide (i.e. giving a path /path/to/file.xyz will save as .xyz etc.).

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

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

The other structure must have the same number of atoms.

Parameters:other (AtomStructure) – The structure to superimpose onto. This structure does not move.
transform(*args, **kwargs)

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(*args, **kwargs)

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.models.molecules.Het(*atoms, id=None, name=None)[source]

A component of a chain.

model

Returns the model the structure is part of.

Return type:Model
chain

Returns the chain the structure is part of.

Return type:Chain
add(obj)

Adds an atom or other AtomStructure to this structure.

Parameters:obj – The atom or structure to add.
atom(*args, **kwargs)

Returns the first Atom that matches the criteria given.

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

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

Return type:Atom
atoms(**kwargs)

Returns the Atom objects in the structure.

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

Return type:set
atoms_in_sphere(**kwargs)

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

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

Return type:set
center_of_mass

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

Returns:(x, y, z) tuple
charge

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

Return type:float
copy()

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

Return type:AtomStructure
formula

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

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 identifier. Once created it is not modifiable.

Return type:str
mass

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

Return type:float
name

The structure’s name.

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

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

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

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

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

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

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

set

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 element, then by name, then by number of bonds, then IDs, and finally by memory address - this last metric is used to ensure that even when allocation is essentially random, it is at least the same every time two structures are aligned.

Parameters:structure (AtomStructure) – the structure to pair with.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:dict
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(obj)

Removes an atom or other AtomStructure from this structure.

Parameters:obj – The atom or structure to remove.
rmsd_with(structure, superimpose=False)

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

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

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

float

rotate(*args, **kwargs)

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, in the format implied by the extension of the path you provide (i.e. giving a path /path/to/file.xyz will save as .xyz etc.).

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

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

The other structure must have the same number of atoms.

Parameters:other (AtomStructure) – The structure to superimpose onto. This structure does not move.
transform(*args, **kwargs)

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(*args, **kwargs)

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.models.molecules.Ligand(*atoms, id=None, name=None)[source]

A small molecule associated with a chain but not connected to it.

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

Adds an atom or other AtomStructure to this structure.

Parameters:obj – The atom or structure to add.
atom(*args, **kwargs)

Returns the first Atom that matches the criteria given.

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

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

Return type:Atom
atoms(**kwargs)

Returns the Atom objects in the structure.

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

Return type:set
atoms_in_sphere(**kwargs)

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

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

Return type:set
center_of_mass

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

Returns:(x, y, z) tuple
chain

Returns the chain the structure is part of.

Return type:Chain
charge

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

Return type:float
copy()

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

Return type:AtomStructure
formula

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

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 identifier. Once created it is not modifiable.

Return type:str
mass

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

Return type:float
model

Returns the model the structure is part of.

Return type:Model
name

The structure’s name.

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

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

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

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

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

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

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

set

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 element, then by name, then by number of bonds, then IDs, and finally by memory address - this last metric is used to ensure that even when allocation is essentially random, it is at least the same every time two structures are aligned.

Parameters:structure (AtomStructure) – the structure to pair with.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:dict
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(obj)

Removes an atom or other AtomStructure from this structure.

Parameters:obj – The atom or structure to remove.
rmsd_with(structure, superimpose=False)

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

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

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

float

rotate(*args, **kwargs)

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, in the format implied by the extension of the path you provide (i.e. giving a path /path/to/file.xyz will save as .xyz etc.).

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

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

The other structure must have the same number of atoms.

Parameters:other (AtomStructure) – The structure to superimpose onto. This structure does not move.
transform(*args, **kwargs)

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(*args, **kwargs)

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.models.molecules.Residue(*atoms, **kwargs)[source]

A small subunit within a chain.

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

Returns the full name of the reside if it is one of the 20 canonical amino acids - otherwise it just returns the name itself.

Return type:str
code

Returns the amino acid code of the reside if it is one of the 20 canonical amino acids - otherwise it just returns ‘X’.

Return type:str
add(obj)

Adds an atom or other AtomStructure to this structure.

Parameters:obj – The atom or structure to add.
atom(*args, **kwargs)

Returns the first Atom that matches the criteria given.

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

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

Return type:Atom
atoms(**kwargs)

Returns the Atom objects in the structure.

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

Return type:set
atoms_in_sphere(**kwargs)

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

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

Return type:set
center_of_mass

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

Returns:(x, y, z) tuple
chain

Returns the chain the structure is part of.

Return type:Chain
charge

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

Return type:float
copy()

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

Return type:AtomStructure
formula

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

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 identifier. Once created it is not modifiable.

Return type:str
mass

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

Return type:float
model

Returns the model the structure is part of.

Return type:Model
name

The structure’s name.

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

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

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

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

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

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

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

set

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. Creating a connection of this kind implies no, and requires no, explicit bonding.

Parameters:residue (Residue) – The residue to connect to. If None is given, any existing connection downstream of this residue will be broken.
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 element, then by name, then by number of bonds, then IDs, and finally by memory address - this last metric is used to ensure that even when allocation is essentially random, it is at least the same every time two structures are aligned.

Parameters:structure (AtomStructure) – the structure to pair with.
Raises:ValueError – if the other structure has a different number of atoms.
Return type:dict
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(obj)

Removes an atom or other AtomStructure from this structure.

Parameters:obj – The atom or structure to remove.
rmsd_with(structure, superimpose=False)

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

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

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

float

rotate(*args, **kwargs)

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, in the format implied by the extension of the path you provide (i.e. giving a path /path/to/file.xyz will save as .xyz etc.).

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

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

The other structure must have the same number of atoms.

Parameters:other (AtomStructure) – The structure to superimpose onto. This structure does not move.
transform(*args, **kwargs)

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(*args, **kwargs)

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.
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 from that. Note that is a separate concept from bonds. Creating a connection of this kind implies no, and requires no, explicit bonding.

Parameters:residue (Residue) – The residue to connect to. If None is given, any existing connection upstream of this residue will be broken.
Raises:ValueError – if you try to connect a residue to itself.
Return type:Residue