biotite.structure

A subpackage for handling molecular structures.

In this context an atom is described by two kinds of attributes: the coordinates and the annotations. The annotations include information about polypetide chain id, residue id, residue name, hetero atom information, atom name and optionally more. The coordinates are a NumPy float ndarray of length 3, containing the x, y and z coordinates.

An Atom contains data for a single atom, it stores the annotations as scalar values and the coordinates as length 3 ndarray.

An AtomArray stores data for an entire structure model containing n atoms. Therefore the annotations are represented as ndarray objects of length n, the so called annotation arrays. The coordinates are a (n x 3) ndarray.

An AtomArrayStack stores data for m models, where each model contains the same atoms at different positions. Hence, the annotation arrays are represented as ndarray objects of length n like the AtomArray, while the coordinates are a (m x n x 3) ndarray.

Like an AtomArray can be iterated to obtain Atom objects, an AtomArrayStack yields AtomArray objects. All three types must not be subclassed.

The following annotation categories are mandatory:

Category

Type

Examples

Description

chain_id

string (U4)

‘A’,’S’,’AB’, …

Polypeptide chain

res_id

int

1,2,3, …

Sequence position of residue

ins_code

string (U1)

‘’, ‘A’,’B’,..

PDB insertion code (iCode)

res_name

string (U3)

‘GLY’,’ALA’, …

Residue name

hetero

bool

True, False

False for ATOM, true for HETATM

atom_name

string (U6)

‘CA’,’N’, …

Atom name

element

string (U2)

‘C’,’O’,’SE’, …

Chemical Element

For all Atom, AtomArray and AtomArrayStack objects these annotations are initially set with default values. Additionally to these annotations, an arbitrary amount of annotation categories can be added via add_annotation() or set_annotation(). The annotation arrays can be accessed either via the method get_annotation() or directly (e.g. array.res_id).

The following annotation categories are optionally used by some functions:

Category

Type

Examples

Description

atom_id

int

1,2,3, …

Atom serial number

b_factor

float

0.9, 12.3, …

Temperature factor

occupancy

float

.1, .3, .9, …

Occupancy

charge

int

-2,-1,0,1,2, …

Electric charge of the atom

For each type, the attributes can be accessed directly. Both AtomArray and AtomArrayStack support NumPy style indexing. The index is propagated to each attribute. If a single integer is used as index, an object with one dimension less is returned (AtomArrayStack -> AtomArray, AtomArray -> Atom). If a slice, index array or a boolean mask is given, a substructure is returned (AtomArrayStack -> AtomArrayStack, AtomArray -> AtomArray) As in NumPy, these are not necessarily deep copies of the originals: The attributes of the sliced object may still point to the original ndarray. Use the copy() method if a deep copy is required.

Bond information can be associated to an AtomArray or AtomArrayStack by setting the bonds attribute with a BondList. A BondList specifies the indices of atoms that form chemical bonds. Some functionalities require that the input structure has an associated BondList. If no BondList is associated, the bonds attribute is None.

Based on the implementation in NumPy arrays, this package furthermore contains a comprehensive set of functions for structure analysis, manipulation and visualization.

The universal length unit in this package is Å.

Structure types

Atom

A representation of a single atom.

AtomArray

An array representation of a model consisting of multiple atoms.

AtomArrayStack

A collection of multiple AtomArray instances, where each atom array has equal annotation arrays.

array

Create an AtomArray from a list of Atom.

stack

Create an AtomArrayStack from a list of AtomArray.

repeat

Repeat atoms (AtomArray or AtomArrayStack) multiple times in the same model with different coordinates.

from_template

Create an AtomArrayStack using template atoms and given coordinates.

Boxes and unit cells

vectors_from_unitcell

Calculate the three vectors spanning a box from the unit cell lengths and angles.

unitcell_from_vectors

Get the unit cell lengths and angles from box vectors.

box_volume

Get the volume of one ore multiple boxes.

repeat_box

Repeat the atoms in a box by duplicating and placing them in adjacent boxes.

repeat_box_coord

Similar to repeat_box(), repeat the coordinates in a box by duplicating and placing them in adjacent boxes.

move_inside_box

Move all coordinates into the given box, with the box vectors originating at (0,0,0).

remove_pbc

Remove segmentation caused by periodic boundary conditions from a given structure.

remove_pbc_from_coord

Remove segmentation caused by periodic boundary conditions from given coordinates.

coord_to_fraction

Transform coordinates to fractions of box vectors.

fraction_to_coord

Transform fractions of box vectors to coordinates.

is_orthogonal

Check, whether a box or multiple boxes is/are orthogonal.

Bonds

BondList

A bond list stores indices of atoms (usually of an AtomArray or AtomArrayStack) that form chemical bonds together with the type (or order) of the bond.

BondType

This enum type represents the type of a chemical bond.

connect_via_residue_names

Create a BondList for a given atom array (stack), based on the deposited bonds for each residue in the RCSB components.cif dataset.

connect_via_distances

Create a BondList for a given atom array, based on pairwise atom distances.

find_connected

Get indices to all atoms that are directly or inderectly connected to the root atom indicated by the given index.

find_rotatable_bonds

Find all rotatable bonds in a given BondList.

Geometry

displacement

Measure the displacement vector, i.e. the vector difference, from one array of atom coordinates to another array of coordinates.

index_displacement

Measure the displacement, i.e. the vector difference, between pairs of atoms.

distance

Measure the euclidian distance between atoms.

index_distance

Measure the euclidian distance between pairs of atoms.

angle

Measure the angle between 3 atoms.

index_angle

Measure the angle between triples of atoms.

dihedral

Measure the dihedral angle between 4 atoms.

index_dihedral

Measure the dihedral angle between quadruples of atoms.

centroid

Measure the centroid of a structure.

mass_center

Calculate the center(s) of mass of an atom array or stack.

gyration_radius

Compute the radius/radii of gyration of an atom array or stack.

rdf

Compute the radial distribution function g(r) (RDF) for one or multiple given central positions based on a given system of particles.

Transformations

translate

Translate the given atoms or coordinates by a given vector.

rotate

Rotate the given atoms or coordinates about the x, y and z axes by given angles.

rotate_centered

Rotate the given atoms or coordinates about the x, y and z axes by given angles.

rotate_about_axis

Rotate the given atoms or coordinates about a given axis by a given angle.

align_vectors

Apply a transformation to atoms or coordinates, that would transfer a origin vector to a target vector.

orient_principal_components

Translate and rotate the atoms to be centered at the origin with the principal axes aligned to the Cartesian axes, as specified by the order parameter.

superimpose

Superimpose structures onto a fixed structure.

superimpose_apply

Superimpose structures using a given transformation tuple.

Filters

filter_canonical_nucleotides

Filter all atoms of one array that belong to canonical nucleotides.

filter_nucleotides

Filter all atoms of one array that belong to nucleotides.

filter_canonical_amino_acids

Filter all atoms of one array that belong to canonical amino acid residues.

filter_amino_acids

Filter all atoms of one array that belong to amino acid residues.

filter_carbohydrates

Filter all atoms of one array that belong to carbohydrates.

filter_backbone

Filter all peptide backbone atoms of one array.

filter_solvent

Filter all atoms of one array that are part of the solvent.

filter_monoatomic_ions

Filter all atoms of an atom array, that are monoatomic ions (e.g.

filter_intersection

Filter all atoms of one array that exist also in another array.

filter_first_altloc

Filter all atoms, that have the first altloc ID appearing in a residue.

filter_highest_occupancy_altloc

For each residue, filter all atoms, that have the altloc ID with the highest occupancy for this residue.

Checks

check_bond_continuity

Check if the peptide backbone atoms ("N","CA","C") have a non-reasonable distance to the next atom.

check_id_continuity

Check if the residue IDs are incremented by more than 1 or decremented, from one atom to the next one.

check_atom_id_continuity

Check if the atom IDs are incremented by more than 1 or decremented, from one atom to the next one.

check_res_id_continuity

Check if the residue IDs are incremented by more than 1 or decremented, from one atom to the next one.

check_duplicate_atoms

Check if a structure contains duplicate atoms, i.e. two atoms in a structure have the same annotations (coordinates may be different).

Residue level utility

get_residue_starts

Get indices for an atom array, each indicating the beginning of a residue.

get_residues

Get the residue IDs and names of an atom array (stack).

apply_residue_wise

Apply a function to intervals of data, where each interval corresponds to one residue.

spread_residue_wise

Expand residue-wise data to atom-wise data.

get_residue_masks

Get boolean masks indicating the residues to which the given atom indices belong.

get_residue_starts_for

For each given atom index, get the index that points to the start of the residue that atom belongs to.

get_residue_positions

For each given atom index, obtain the position of the residue corresponding to this index in the input array.

get_residue_count

Get the amount of residues in an atom array (stack).

residue_iter

Iterate over all residues in an atom array (stack).

Chain level utility

get_chain_starts

Get the indices in an atom array, which indicates the beginning of a new chain.

apply_chain_wise

Apply a function to intervals of data, where each interval corresponds to one chain.

spread_chain_wise

Expand chain-wise data to atom-wise data.

get_chain_masks

Get boolean masks indicating the chains to which the given atom indices belong.

get_chain_starts_for

For each given atom index, get the index that points to the start of the chain that atom belongs to.

get_chain_positions

For each given atom index, obtain the position of the chain corresponding to this index in the input array.

chain_iter

Iterate over all chains in an atom array (stack).

get_chains

Get the chain IDs of an atom array (stack).

get_chain_count

Get the amount of chains in an atom array (stack).

chain_iter

Iterate over all chains in an atom array (stack).

Molecule level utility

get_molecule_indices

Get an index array for each molecule in the given structure.

get_molecule_masks

Get a boolean mask for each molecule in the given structure.

molecule_iter

Iterate over each molecule in a input structure.

Structure comparison

average

Calculate an average structure.

rmsd

Calculate the RMSD between two structures.

rmsf

Calculate the RMSF between two structures.

General analysis

sasa

Calculate the Solvent Accessible Surface Area (SASA) of a protein.

hbond

Find hydrogen bonds in a structure using the Baker-Hubbard algorithm.

hbond_frequency

Get the relative frequency of each hydrogen bond in a multi-model structure.

partial_charges

Compute the partial charge of the individual atoms comprised in a given AtomArray depending on their electronegativity.

density

Compute the density of the selected atoms.

Proteins

dihedral_backbone

Measure the characteristic backbone dihedral angles of a protein structure.

annotate_sse

Calculate the secondary structure elements (SSE) of a peptide chain based on the P-SEA algorithm.

Nucleic acids

Edge

This enum type represents the interacting edge for a given base.

GlycosidicBond

This enum type represents the relative glycosidic bond orientation for a given base pair.

map_nucleotide

Map a nucleotide to one of the 5 common bases Adenine, Guanine, Thymine, Cytosine, and Uracil.

base_pairs

Use DSSR criteria to find the base pairs in an AtomArray.

base_stacking

Find pi-stacking interactions between aromatic rings in nucleic acids.

pseudoknots

Identify the pseudoknot order for each base pair in a given set of base pairs.

base_pairs_edge

Get the interacting edges for given base pairs in an AtomArray according to the Leontis-Westhof nomenclature.

base_pairs_glycosidic_bond

Calculate the glycosidic bond orientation for given base pairs in an AtomArray according to the Leontis-Westhof nomenclature.

dot_bracket

Represent a nucleic acid strand in dot-bracket-letter-notation (DBL-notation).

dot_bracket_from_structure

Represent a nucleic-acid-strand in dot-bracket-letter-notation (DBL-notation).

base_pairs_from_dot_bracket

Extract the base pairs from a nucleic-acid-strand in dot-bracket-letter-notation (DBL-notation).

Miscellaneous

BadStructureError

Indicates that a structure is not suitable for a certain operation.

CellList

This class enables the efficient search of atoms in vicinity of a defined location.

IncompleteStructureWarning

Indicates that a structure is not complete.

UnexpectedStructureWarning

Indicates that a structure was not expected.

coord

Get the atom coordinates of the given array.

renumber_atom_ids

Renumber the atom IDs of the given array.

renumber_res_ids

Renumber the residue IDs of the given array.

Subpackages

biotite.structure.io

A subpackage for reading and writing structure related data.

biotite.structure.io.tng

This subpackage is used for reading and writing trajectories in the compressed Gromacs TNG format.

biotite.structure.io.trr

This subpackage is used for reading and writing trajectories in the uncompressed Gromacs TRR format.

biotite.structure.io.mmtf

This subpackage is used for reading and writing an AtomArray or AtomArrayStack using the binary MMTF format.

biotite.structure.io.dcd

This subpackage is used for reading and writing trajectories in the CDC format used by software like CHARMM, OpenMM and NAMD.

biotite.structure.io.pdbqt

This subpackage is used for reading and writing an AtomArray or AtomArrayStack using the PDBQT format used by the AutoDock software series.

biotite.structure.io.gro

This subpackage is used for reading and writing an AtomArray or AtomArrayStack using the Gro format used by the gromacs software package.

biotite.structure.io.pdb

This subpackage is used for reading and writing an AtomArray or AtomArrayStack using the popular PDB format.

biotite.structure.io.mol

The MOL format is used to depict atom positions and bonds for small molecules.

biotite.structure.io.pdbx

This subpackage provides support for the the modern PDBx/mmCIF file format.

biotite.structure.io.netcdf

This subpackage is used for reading and writing trajectories in the AMBER NetCDF format.

biotite.structure.io.npz

This subpackage is used for reading and writing an AtomArray or AtomArrayStack using the internal NPZ file format.

biotite.structure.io.xtc

This subpackage is used for reading and writing trajectories in the compressed Gromacs XTC format.

biotite.structure.graphics

A subpackage for visualizing structure related objects.

biotite.structure.info

A subpackage for obtaining all kinds of chemical information about atoms and residues, including masses, radii, bonds, etc.