Source documentation

atom.py

Base classes for Atom and AtomCollection formats.

Subclasses extend or override attributes and methods as necessary.

class protutils.atom.Atom(record, natom, atom, res, chain, nres, x, y, z, charge)

Bases: object

Base class for an atom description.

Parameters :

record : string {ATOM, HETATM}

The type of atom. ATOM refers to atoms in amino acids, HETATM refers to atoms in other molecules.

natom : int

The atom number.

atom : string

The identifier for this atom.

res : string

The residue of this atom.

chain : string

The chain identifier for this atom.

nres : int

The residue number of this atom.

x : float

The value for the x coordinate of the atom.

y : float

The value for the y coordinate of the atom.

z : float

The value for the z coordinate of the atom.

charge : float

Charge on this atom.

__dict__ = <dictproxy object at 0x106b3d050>

__eq__(other)

__hash__()

__init__(record, natom, atom, res, chain, nres, x, y, z, charge)

__module__ = 'protutils.atom'

__repr__()

__weakref__

list of weak references to the object (if defined)

add_connections_from_list(connections)

Add a list of atom numbers (natom) that connect with this Atom

Parameters :

connections : list

A list of natoms (ints) that connect to this Atom

static angle(atm1, atm2, atm3)

Find angle between three atoms

Parameters :

atm1 : Atom

First atom

atm2 : Atom

Second atom (vertex)

atm3 : Atom

Third angle

Returns :

angle : float

Angle between the atoms

static cross(atm1, atm2)

Find cross product of two Atom coordinates.

Parameters :

atm1 : Atom

First atom

atm2 : Atom

Second atom

Returns :

cross product : float

The cross product, \(\mathbf{A1}_{xyz} \times \mathbf{A2}_{xyz}\)

static dihedral(atm1, atm2, atm3, atm4)

Calculate dihedral angle

Parameters :

atm1 : Atom

First atom

atm2 : Atom

Second atom

atm3 : Atom

Third atom

atm4 : Atom

Fourth atom

Returns :

dihdral angle : float

The dihedral angle in degrees.

static dist(atm1, atm2)

Distance between two atoms.

Parameters :

atm1 : Atom

First atom

atm2 : Atom

Second atom

Returns :

dist : float

The distance between atm1 and atm2

distance(other)

Compute the distance between two Atoms

static dot(atm1, atm2)

Find dot product of two Atoms.

Parameters :

atm1 : Atom

First atom

atm2 : Atom

Second atom

Returns :

dot product : float

The dot product, \(\mathbf{A1}_{xyz} \cdot \mathbf{A2}_{xyz}\)

static nomalize(atom)

Normalize Atom coordinates

Parameters :

atom : Atom

First atom

Returns :

coords : ndarray (1 x 3)

Numpy array of normalized coordinates where \(|| \mathbf{coords} || = 1\)

class protutils.atom.AtomCollection(atoms=None)

Bases: object

Base class for an Atom collection.

Parameters :

atoms : list (optional, default is None)

List of Atom objects

Returns :

result : AtomCollection

__and__(other)

Returns the common atoms between self and other

Parameters :

other : AtomCollection

Returns :

result : AtomCollection

A new object containing atoms common in this and the other collection.

Examples

>>> a = AtomCollection(atoms_1)
>>> b = AtomCollection(atoms_2)
>>> common_atoms = a & b

__contains__(other)

Returns True if all atoms in other are in this collection

Parameters :other : AtomCollection Returns :result : boolean

__dict__ = <dictproxy object at 0x106b4e6a8>

__eq__(other)

Compares two AtomCollections for equality.

Parameters :other : AtomCollection Returns :result : boolean

__getitem__(index)

Get Atom for a given index

Parameters :

index : int

The index of the Atom

Returns :

atom : Atom

The atom at the supplied index

__iand__(other)

__init__(atoms=None)

__ior__(other)

__iter__()

Iterate through the atoms in this collection

__ixor__(other)

__len__()

The number of atoms in this collection.

__module__ = 'protutils.atom'

__or__(other)

Returns the intersection of atoms in self and other

Parameters :

other : AtomCollection

Returns :

result : AtomCollection

A new object containing the atoms in this and the other collection.

Examples

>>> a = AtomCollection(atoms_1)
>>> b = AtomCollection(atoms_2)
>>> all_atoms = a | b

__repr__()

__weakref__

list of weak references to the object (if defined)

__xor__(other)

Returns atoms in self that are not in other and the atoms in other not in self.

Parameters :

other : AtomCollection

Returns :

result : AtomCollection

A new object that contains atoms in this collection that are not in the other collection.

Examples

>>> all_atoms = AtomCollection(atoms)
>>> protons = all_atoms.select(atom__startswith='H')
>>> removed_hydrogens = all_atoms ^ protons

align(other)

Align this object to another and return a new object with the aligned coordinates.

Parameters :

other : AtomCollection

An atom colection containing the same number of atoms as this object.

Returns :

results : AtomCollection

New object with coordinates aligned to the other object.

See also

AtomCollection.cealign

aligned_rmsd(other)

Return the RMSD of the aligned structures of this and another object. Both objects must have the same number of atoms.

Parameters :

other : AtomCollection

An atom colection containing the same number of atoms as this object.

Returns :

rmsd : float

The root-mean-square deviation between the two AtomCollections after alignment.

See also

AtomCollection.rmsd

assign(attr, value)

Assign new value(s) to an Atom attribute

Parameters :

attr: Atom attribute :

value : int, string, float, list, tuple

The value or values to reassign to the selected attribute

backbone()

Return a new object containing all backbone atoms

Returns :

result : AtomCollection

A new object containing only backbone atoms

See also

AtomCollection.protein, AtomCollection.ligand, AtomCollection.sidechains

cealign(other, alphas=True)

Align using the cealign algorithm from pymol.

Parameters :

other : AtomCollection

An atom colection to align this object. The number of atoms in the two objects can be different.

alphas : Boolean, optional (default=True)

If True, align CA carbons only. If False, the full selection is aligned.

Returns :

result : AtomCollection

New object with coordinates aligned to the other object.

See also

AtomCollection.align

chains

Return a list of the chains in this object.

Returns :

chains : lists

A list of the unique chain identifiers in this collection.

exclude(**kwargs)

Create new AtomCollection where specified atoms are excluded

Parameters :

kwargs :

Refer to AtomCollection.select documentation

Returns :

results : AtomCollection

A new object containing atoms that are not specified by the selection criteria.

See also

AtomCollection.select

groupby_residue()

Return dict of residue records grouped by ‘nres_chain’ keys

ligand()

Return a new object containing HETATM records.

Returns :

result : AtomCollection

A new object containing non-protein atoms.

See also

AtomCollection.protein, AtomCollection.backbone, AtomCollection.sidechains

new_coordinates(matrix)

Create new object with new coordinates

Parameters :

matrix : numpy N x 3 matrix

A matrix with the same shape as self.matrix

Returns :

result : AtomCollection

A new object with the supplied coordinates

orient()

Orient the protein to be centered at the origin with the principle axes aligned properly.

Returns :

result : AtomCollection

A new object with coordinates centered at the origin, with principle axes aligned with the Cartesian axes.

protein()

Return a new object containing ATOM records.

Returns :

results : AtomCollection

A new object containing only protein atoms.

See also

AtomCollection.ligand, AtomCollection.backbone, AtomCollection.sidechains

ramachandran_plot()

Creates Ramachandran plot for the protein atoms in this collection.

remove_protons()

Remove protons from collection.

renumber_atoms(start=1)

Renumber atoms.

Parameters :

start : int, optional (default=1)

The new number of the first atom.

renumber_residues(start=1)

Renumber residues beginning with start.

Parameters :

start : int, optional (default=1)

The new number of the first residue

resi

Return a list of residue numbers.

residues

Returns a list of residues.

rmsd(other)

Return the root-mean-square deviation (RMSD) between this and another object.

\(\mathrm{RMSD} = \sqrt{\frac{1}{N}\sum_{i = 1}^{N}||v_i - w_i||^2}\)

Parameters :

other : AtomCollection

An atom colection containing the same number of atoms as this object.

Returns :

rmsd : float

The root-mean-square deviation between the two AtomCollections,

See also

AtomCollection.aligned_rmsd

select(**kwargs)

Select atoms based on logical criteria

Parameters :

kwargs : various

Keys are composed of an atom attribute:

• chain
• atom
• natom
• nres
• record
• etc

and a boolean operator:

• contains value in attr
• ncontains value not in attr
• eq attr == value
• ne attr != value
• ge attr >= value
• gt attr > value
• isin attr in value(s)
• isnotin attr not in values
• isclose np.isclose(attr, value), for floats
• isnotclose not np.isclose(attr, value)
• le attr <= value
• lt attr < value
• endswith attr.endswith(value), strings only
• nendswith not attr.endswith(value)
• startswith attr.startswith(value), strings only
• nstartswith not attr.startswith(value)

separated by two underscore characters __. For example: chain__eq, nres__gt, atom__contains.

Returns :

selection : AtomCollection

New object containing the selected subset of Atoms.

See also

AtomCollection.exclude

Examples

>>> prot = AtomCollection(atoms)
>>> chain_a = prot.select(chain__eq='A')
>>> other_chains = prot.select(chain__ne='A')
>>> residues_1_to_250 = prot.select(nres__le=250)
>>> hydrogens = prot.select(atom__startswith='H')
>>> res356_A = prot.select(chain='A', nres=356)  # default is 'eq'
>>> pos_res = prot.select(res__isin={'LYS', 'ARG'})
>>> # Select neutral residues
>>> charged = set(['LYS', 'ARG', 'ASP', 'GLU'])
>>> neutral_res = prot.select(res__isnotin=charged)
>>> # select creates new object. Allows chaining:
>>> selection = prot.select(nres__gt=200, nres__lt=245).sidechains()

sequence

Returns one-letter code sequence of collection. Missing residues are filled in with -‘s

Returns :

sequence : string

The sequence of the protein residues in this AtomCollection. Gaps in the sequence are indicated by ‘-‘.

sidechains()

Return a new object containing all sidechain atoms.

Returns :

result : AtomCollection

A new object containing only sidechain atoms.

See also

AtomCollection.protein, AtomCollection.ligand, AtomCollection.backbone

within(distance, other)

Get atoms in this instance within some distance of atoms in other instance.

Parameters :

distance : float

The maximum distance between atoms in this object and the other object.

other : AtomCollection

The other object...

Returns :

result : AtomCollection

New object containing Atoms in this object that are less than the selected distance from the other object.

bgf.py

class protutils.bgf.BGFAtom(record, natom, atom, res, chain, nres, x, y, z, fftype, nbond, nlonepair, charge, fixed)

Bases: protutils.atom.Atom

Parse, store, and manipulate RECORD line data from a BGF file.

__init__(record, natom, atom, res, chain, nres, x, y, z, fftype, nbond, nlonepair, charge, fixed)

__module__ = 'protutils.bgf'

__repr__()

add_connections_from_line(line)

Add connection data

classmethod from_line(line)

Parse a RECORD line from a BGF file.

Parameters :

line : string

BGF-formatted line

Returns :

result : BGFAtom

Instantiates a BGFAtom object

writeline()

Write BGF ATOM/HETATM line and CONECT info.

Returns :

result : tuple

A two-element tuple containing the ATOM/HETATOM record, and the CONECT information.

class protutils.bgf.BGFFile(biogrf='332', descrp='', ff='DREIDING', atoms=None)

Bases: protutils.atom.AtomCollection

Store and manipulate BGF files.

__init__(biogrf='332', descrp='', ff='DREIDING', atoms=None)

Initialize a BGFFile object.

Creates a blank BGF object by default.

Parameters :

biogrf : str, optional (default=‘332’)

Biogrf format

descrp : str, optional

BGF description.

ff : str, optional (default=’DREIDING’)

Forcefield used to calculate atom charges and fftype

atoms : list, optional

List of BGFAtom objects used to create BGFFile instance

Returns :

BF : BGFFile

__module__ = 'protutils.bgf'

fftypes

classmethod from_file(filename)

Create a new BGFFile object from a file.

Parses BGF file header and RECORD lines.

Returns :

BF : BGFFile

New BGFFile object containing data from the file.

set_movable(movable=True)

to_pdb()

Create PDBFile object.

Returns :result : PDBFile

write_bgf(filename)

Write object to file

Parameters :

filename : path

Path to desired file

write_pdb(filename)

Write object contents as a PDB file.

pdb.py

class protutils.pdb.PDBAtom(record, natom, atom, altloc, res, chain, nres, icode, x, y, z, occupancy, bfactor, element, charge)

Bases: protutils.atom.Atom

PDB file class

__init__(record, natom, atom, altloc, res, chain, nres, icode, x, y, z, occupancy, bfactor, element, charge)

__module__ = 'protutils.pdb'

__repr__()

add_connections_from_line(line)

classmethod from_line(line)

Parse a PDB RECORD line.

Parameters :

line : string

A RECORD line (ATOM/HETATM) from a PDB file

Returns :

result : PDBAtom

writeline()

Write object data as formated RECORD and CONECT strings

Returns :

line : tuple

A two-element tuple containing the RECORD (ATOM/HETATM) line and the CONECT line (if applicable).

class protutils.pdb.PDBFile(atoms=None)

Bases: protutils.atom.AtomCollection

__module__ = 'protutils.pdb'

classmethod fetch(pdb_code)

Fetch pdb from RCSB Protein Data Bank.

Parameters :

pdb_code : str

Four character PDB code.

Returns :

PF : PDBFile

New PDBFile object.

classmethod fetch_ligand(cci)

Fetch ligand from Ligand Expo

Parameters :

cci : string

Three-letter chemical component identifier

Returns :

PF : PDFFile

New PDBFile object

classmethod from_file(filename)

Initialize from file

Parameters :

filename : path

Path to a PDB file

Returns :

result : PDBFile

ramachandran_plot()

Creates Ramachandran plot of phi and psi backbone angles.

write_pdb(filename)

Write object to PDB file

Parameters :

filename : path

Path to save PDB file.

class protutils.pdb.PDBResidue(res, nres, chain, icode, atoms)

Bases: protutils.residue.Residue

__init__(res, nres, chain, icode, atoms)

__module__ = 'protutils.pdb'

classmethod from_atoms(atoms)

Instantiate new residue object from sorted atom list

Parameters :

atoms : list

A list of PDBAtom objects sorted by natom. List must contain only one residue.

Returns :

result : PDBResidue

get_next()

Returns key for ‘next’ residue

get_prev()

Returns key for ‘previous’ residue

class protutils.pdb.PDBResidues(atoms)

Bases: protutils.residue.Residues

__init__(atoms)

__module__ = 'protutils.pdb'

pqr.py

class protutils.pqr.PQRAtom(record, natom, atom, res, chain, nres, x, y, z, charge, radius)

Bases: protutils.atom.Atom

Parse PQR atom format

__init__(record, natom, atom, res, chain, nres, x, y, z, charge, radius)

__module__ = 'protutils.pqr'

__repr__()

classmethod from_line(line)

PQR files are whitespace delimited

writeline()

class protutils.pqr.PQRFile(ff, atoms=None)

Bases: protutils.atom.AtomCollection

__init__(ff, atoms=None)

__module__ = 'protutils.pqr'

classmethod from_file(filename)

to_pdb()

Convert PQR to PDB

Returns :

result : PDBFile

A new PDBFile object with unknown the values for the occupancy and b-factor have been set to 0.00

write_pdb(filename)

Write object to a PQR file with PDB-style formatting.

Uses PQRFile.to_pdb() to convert to pdb object before writing data to file.

See also

PQRFile.to_pdb

write_pqr(filename)

Write object to a PQR file with PDB-style formatting.

residue.py

class protutils.residue.Residue(res, nres, chain, atoms)

Bases: object

Container for a residue

__dict__ = <dictproxy object at 0x107005590>

__getitem__(name)

Return Atom object with selected name

__init__(res, nres, chain, atoms)

__module__ = 'protutils.residue'

__weakref__

list of weak references to the object (if defined)

classmethod from_atoms(atoms)

get_next()

Returns key for ‘next’ residue

get_prev()

Returns key for ‘previous’ residue

class protutils.residue.Residues(atoms)

Bases: object

__dict__ = <dictproxy object at 0x106f786a8>

__getitem__(key)

__init__(atoms)

Instantiates new Residues object.

Parameters :

atoms : list

Sorted collection of Atom objects.

__module__ = 'protutils.residue'

__weakref__

list of weak references to the object (if defined)

phi(residue)

Get \(\phi\) angle for indicated residue

Parameters :

residue : string

Key for residue in the form {NRES}_{CHAIN}

Returns :

result : float

The \(\phi\) (phi) dihedral angle, in degrees, for this residue.

See also

Residues.psi

psi(residue)

Get \(\psi\) angle for indicated residue

Parameters :

residue : string

Key for residue in the form {NRES}_{CHAIN}

Returns :

result : float

The \(\psi\) (psi) dihedral angle, in degrees, for this residue.

See also

Residues.phi

ramachandran_plot()

Plot \(\psi\) versus \(\phi\) angles for all residues.