parmed.modeller package

Submodules

• parmed.modeller.residue module
• parmed.modeller.standardtemplates module

Module contents

This package contains functionality necessary to carry out basic molecular modelling tasks.

class parmed.modeller.AmberOFFLibrary

Bases: object

Class containing static methods responsible for parsing and writing OFF libraries

Methods

id_format(filename)	Sees if an open file is an OFF library file.
parse(filename)	Parses an Amber OFF library
write(lib, dest)	Writes a dictionary of ResidueTemplate units to a file in OFF format

static id_format(filename)

Sees if an open file is an OFF library file.

Parameters

filenamestr

The name of the file to see if it is an OFF file format

Returns

is_fmtbool

True if it is recognized as OFF, False otherwise

static parse(filename)

Parses an Amber OFF library

Parameters

filenamestr or file-like iterable

The file name or file object to parse. If it is an iterable, it will be exhausted

Returns

residuesOrderedDict {str

Dictionary pairing residue names with their ResidueTemplate objects

Raises

ValueError if the first line does not match the file format. This line

will be consumed

IOError if filename is the name of a file that does not exist

RuntimeError if EOF is reached prematurely or other formatting issues

found

static write(lib, dest)

Writes a dictionary of ResidueTemplate units to a file in OFF format

Parameters

libdict {str

Items can be either ResidueTemplate or ResidueTemplateContainer instances

deststr or file-like

Either a file name or a file-like object to write the file to

class parmed.modeller.PatchTemplate(name='')

Bases: parmed.modeller.residue.ResidueTemplate

A residue patch (typically used for CHARMM) that is used to modify existing residues in some way (e.g., terminal patches, disulfide bridges, etc.)

Parameters

namestr, optional

If provided, this is the name of the residue

See also

ResidueTemplate

Notes

This class basically just provides an additional list of atoms that need to be deleted when applying this patch – something that does not apply to standard Residues

Attributes

add_bondslist of (str, str, order)

List of bonds that need to be added in applying the patch

delete_atomslist of str

List of atom names that need to be deleted in applying the patch

delete_improperslist of tuple of str

List of impropers (tuple of atom names) that need to be deleted in applying the patch

Methods

add_atom(atom)	Adds an atom to this residue template
add_bond(atom1, atom2[, order])	Adds a bond between the two provided atoms in the residue
apply_patch(patch[, precision])	Apply the specified PatchTemplate to the ResidueTemplate.
delete_atom(atom)	Delete an atom from this residue template, along with corresponding bonds.
delete_bond(bond)	Delete a bond from this residue template.
fix_charges([to, precision])	Adjusts the partial charge of all atoms in the residue to match the requested target charge.
from_residue(residue)	This constructor creates a ResidueTemplate from a particular Residue object Parameters ———- residue : Residue The residue from which to create a template
patch_is_compatible(patch)	Determine whether a specified patch is compatible with this residue.
save(fname[, format, overwrite])	Saves the current ResidueTemplate in the requested file format.
to_dataframe()	Create a pandas dataframe from the atom information
to_networkx([include_extra_particles])	Create a NetworkX graph of atoms and bonds
to_structure()	Generates a Structure instance with a single residue from this ResidueTemplate

class parmed.modeller.ResidueTemplate(name='')

Bases: object

This is a residue template, which contains a listing of the atoms in the residue template as well as a mapping of which atoms are bonded to other atoms.

Parameters

namestr, optional

If provided, this is the name of the residue

Attributes

atomsAtomList

List of atoms in this residue

bondsTrackedList

List of the bonds between the atoms in this residue

coordinatesnp.ndarray(natom, 3)

Atomic coordinates, in Angstroms, of all atoms in the template

connectionslist of Atom

A list of all atoms that should form connections with atoms of another residue besides the head and tail atoms

headAtom or None

The atom that is connected to the residue that comes before this one

tailAtom or None

The atom that is connected to the next residue after this one

first_patchResidueTemplate or None

If it is not None, this is the patch whose tail is added to the head atom of this residue when this residue is the first in a chain

last_patchResidueTemplate or None

If it is not None, this is the patch whose head is added to the tail atom of this residue when this residue is the last in a chain

groupslist of list(Atom)

If set, each group is a list of Atom instances making up each group

override_levelinteger

For use with OpenMM ResidueTemplates. If OpenMM ForceField is given multiple identically-matching residue templates with the same names it choses (overrides with) the one with the highest override_level (overrideLevel in OpenMM). Default is 0.

Methods

add_atom(atom)	Adds an atom to this residue template
add_bond(atom1, atom2[, order])	Adds a bond between the two provided atoms in the residue
apply_patch(patch[, precision])	Apply the specified PatchTemplate to the ResidueTemplate.
delete_atom(atom)	Delete an atom from this residue template, along with corresponding bonds.
delete_bond(bond)	Delete a bond from this residue template.
fix_charges([to, precision])	Adjusts the partial charge of all atoms in the residue to match the requested target charge.
from_residue(residue)	This constructor creates a ResidueTemplate from a particular Residue object Parameters ———- residue : Residue The residue from which to create a template
patch_is_compatible(patch)	Determine whether a specified patch is compatible with this residue.
save(fname[, format, overwrite])	Saves the current ResidueTemplate in the requested file format.
to_dataframe()	Create a pandas dataframe from the atom information
to_networkx([include_extra_particles])	Create a NetworkX graph of atoms and bonds
to_structure()	Generates a Structure instance with a single residue from this ResidueTemplate

add_atom(atom)

Adds an atom to this residue template

Parameters

atomAtom

The atom to add to this residue

Raises

ValueError if atom has the same name as another atom in this

residue already

add_bond(atom1, atom2, order=1.0)

Adds a bond between the two provided atoms in the residue

Parameters

atom1Atom or int or str

One of the atoms in the bond. It must be in the atoms list of this ResidueTemplate. It can also be the atom index (index from 0) of the atom in the bond.

atom2Atom or int or str

The other atom in the bond. It must be in the atoms list of this ResidueTemplate. It can also be the atom index (index from 0) of the atom in the bond.

orderfloat

The bond order of this bond. Bonds are classified as follows:

1.0 – single bond 2.0 – double bond 3.0 – triple bond 1.5 – aromatic bond 1.25 – amide bond

Default is 1.0

Raises

IndexError if atom1 or atom2 are integers that are out of range of the

number of atoms already in this template

RuntimeError if atom1 or atom2 are Atom instances but they are

not in the atoms list of this ResidueTemplate

Notes

If atom1 and atom2 are already bonded, this routine does nothing. If atom1 or atom2 are strings, then they will match the first instance of the atom name that is the same as the atom name passed.

apply_patch(patch, precision=4)

Apply the specified PatchTemplate to the ResidueTemplate.

This only handles patches that affect a single residue.

An exception is thrown if patch is incompatible because * The patch specifies that an atom is to be deleted that doesn’t exist in the residue * A bond specified as being added in the patch does not have both atom names present after adding/deleting atoms from the patch * The new net charge is not integral to the specified precision * The residue is not modified in any way (no atoms or bonds added/changed/deleted)

Parameters

patchPatchTemplate

The patch to apply to this residue

precisionint, optional

Each valid patch should be produce a net charge that is integral to this many decimal places. Default is 4

Returns

residueResidueTemplate

A new ResidueTemplate corresponding to the patched residue is returned. The original remains unmodified.

property coordinates

Atomic coordinates, in Angstroms, of all atoms in the template

delete_atom(atom)

Delete an atom from this residue template, along with corresponding bonds.

Parameters

atomAtom or str

The atom or atom name to be deleted

delete_bond(bond)

Delete a bond from this residue template.

Parameters

bondBond

The bond to be deleted

property empirical_chemical_formula

Return the empirical chemical formula (in Hill notation) as a string (e.g. ‘H2O’, ‘C6H12’), omitting EPs

fix_charges(to=None, precision=4)

Adjusts the partial charge of all atoms in the residue to match the requested target charge. The default target charge is the closest integer

Parameters

tofloat, optional

The desired net charge of this residue template. Default is the closest integer charge

precisionint, optional

The number of decimal places that each charge should be rounded to. Default is 4

Returns

selfResidueTemplate

The current residue template whose charges are being modified

Raises

ValueError

If you try to call fix_charges on a residue template with no atoms

Notes

This method modifies the atomic charges of this residue template in-place. Any residual charge (which is accumulated roundoff beyond the requested precision) is added to the first atom of the residue. This will typically be 10^-precision in magnitude, and should almost never be higher than 2*10^-precision. As long as a reasonable precision is chosen (no fewer than 3 or 4 decimal places), this will have only a negligible impact on a force field.

If provided, “to” will be rounded to the precision’th decimal place to make sure that the sum of the charges come out as close as possible to the target charge while still obeying the requested precision.

classmethod from_residue(residue)

This constructor creates a ResidueTemplate from a particular Residue object Parameters ———- residue : Residue

The residue from which to create a template

property map

property net_charge

patch_is_compatible(patch)

Determine whether a specified patch is compatible with this residue.

Compatibility is determined by whether Residue.Template.apply_patch(patch) raises as exception or not.

Parameters

patchPatchTemplate

The patch to be applied to this residue.

Returns

is_compatiblebool

True if patch is compatible with the residue; False if not.

save(fname, format=None, overwrite=False, **kwargs)

Saves the current ResidueTemplate in the requested file format. Supported formats can be specified explicitly or determined by file-name extension. The following formats are supported, with the recognized suffix shown in parentheses:

• MOL2 (.mol2)

• MOL3 (.mol3)

• OFF (.lib/.off)

• PDB (.pdb)

• PQR (.pqr)

Parameters

fnamestr

Name of the file to save. If format is None (see below), the file type will be determined based on the filename extension. If the type cannot be determined, a ValueError is raised.

formatstr, optional

The case-insensitive keyword specifying what type of file fname should be saved as. If None (default), the file type will be determined from filename extension of fname

overwritebool, optional

If True, allow the target file to be overwritten. Otherwise, an IOError is raised if the file exists. Default is False

kwargskeyword-arguments

Remaining arguments are passed on to the file writing routines that are called by this function

Raises

ValueError if either filename extension or format are not recognized

TypeError if the structure cannot be converted to the desired format for

whatever reason

to_dataframe()

Create a pandas dataframe from the atom information

Returns

dfpandas.DataFrame

The pandas DataFrame with all of the atomic properties

Notes

The DataFrame will be over all atoms. The columns will be the attributes of the atom (as well as its containing residue). Some columns will always exist. Others will only exist if those attributes have been set on the Atom instances (see the Atom docs for possible attributes and their meaning). The columns that will always be present are:

• number : int

• name : str

• type : str

• atomic_number : int

• charge : float

• mass : float

• nb_idx : int

• solvent_radius : float

• screen : float

• occupancy : float

• bfactor : float

• altloc : str

• tree : str

• join : int

• irotat : int

• rmin : float

• epsilon : float

• rmin_14 : float

• epsilon_14 : float

The following attributes are optionally present if they were present in the original file defining the structure:

• xx : float (x-coordinate position)

• xy : float (y-coordinate position)

• xz : float (z-coordinate position)

• vx : float (x-coordinate velocity)

• vy : float (y-coordinate velocity)

• vz : float (z-coordinate velocity)

to_networkx(include_extra_particles=True)

Create a NetworkX graph of atoms and bonds

Parameters

include_extra_particlesbool

Whether to include “atoms” that actually represent extra particles (atomic_number == 0).

Returns

Gnetworkx.Graph

A NetworkX Graph representing the molecule

to_structure()

Generates a Structure instance with a single residue from this ResidueTemplate

Returns

structparmed.structure.Structure

The Structure with all of the bonds and connectivity of this template

class parmed.modeller.ResidueTemplateContainer(name='')

Bases: list

A container of ResidueTemplate objects representing a unit with multiple residues

Parameters

namestr, optional

The name of the residue container

Methods

append(object, /)	Append object to the end of the list.
clear(/)	Remove all items from list.
copy(/)	Return a shallow copy of the list.
count(value, /)	Return number of occurrences of value.
extend(iterable, /)	Extend list by appending elements from the iterable.
fix_charges([precision])	Adjusts the net charge of all residues in this ResidueContainer to match the closest integer charge
from_library(library[, copy])	Converts a dictionary of ResidueTemplate items into a ResidueTemplateContainer.
from_structure(struct[, term_decorate])	Instantiates a ResidueTemplateContainer from a Structure instance filled with residues
index(value[, start, stop])	Return first index of value.
insert(index, object, /)	Insert object before index.
pop([index])	Remove and return item at index (default last).
remove(value, /)	Remove first occurrence of value.
reverse(/)	Reverse IN PLACE.
save(fname[, format])	Saves the current ResidueTemplateContainer in the requested file format.
sort(*[, key, reverse])	Stable sort IN PLACE.
to_library()	Converts the ResidueTemplateContainer instance to a library of unique ResidueTemplate instances.

fix_charges(precision=4)

Adjusts the net charge of all residues in this ResidueContainer to match the closest integer charge

Parameters

precisionint, optional

The number of decimal places that each charge should be rounded to. Default is 4

Returns

selfResidueTemplateContainer

The current residue template container whose ResidueTemplates are being modified

Raises

ValueError

If you try to call fix_charges on a container with no templates

Notes

This method modifies everything in-place.

classmethod from_library(library, copy=False)

Converts a dictionary of ResidueTemplate items into a ResidueTemplateContainer.

Parameters

librarydict or OrderedDict

The library of ResidueTemplate objects to add to this container

copybool, optional

If True, copies of each ResidueTemplate in library is added to the ResidueTemplateContainer. Default is False

Returns

contResidueTemplateContainer

A ResidueTemplateContainer containing all of the residues defined in library

Raises

TypeError if any of the items in the input library is not a

ResidueTemplate instance (or an instance of a subclass)

Notes

If the library is ordered, that order is maintained

classmethod from_structure(struct, term_decorate=True)

Instantiates a ResidueTemplateContainer from a Structure instance filled with residues

Parameters

structparmed.structure.Structure

The structure from which to generate the ResidueTemplateContainer from

term_decoratebool, optional

If True, terminal amino and nucleic acid residues will be adorned as follows:

• N-prepended if it is an N-terminal amino acid

• C-prepended if it is a C-terminal amino acid

• 5-appended if it is a 5’-terminal nucleic acid

• 3-appended if it is a 3’-terminal nucleic acid

For example, an N-terminal GLY will become NGLY, while a 5’-terminal DA will become DA5. Default is True

save(fname, format=None, **kwargs)

Saves the current ResidueTemplateContainer in the requested file format. Supported formats can be specified explicitly or determined by file-name extension. The following formats are supported, with the recognized suffix and format keyword shown in parentheses:

• MOL2 (.mol2)

• MOL3 (.mol3)

• OFF (.lib/.off)

Parameters

fnamestr

Name of the file to save. If format is None (see below), the file type will be determined based on the filename extension. If the type cannot be determined, a ValueError is raised.

formatstr, optional

The case-insensitive keyword specifying what type of file fname should be saved as. If None (default), the file type will be determined from filename extension of fname

kwargskeyword-arguments

Remaining arguments are passed on to the file writing routines that are called by this function

Raises

ValueError if either filename extension or format are not recognized

TypeError if the structure cannot be converted to the desired format for

whatever reason

Notes

Mol2 and Mol3 files are saved as concatenated multiple @<MOLECULE>s. By contrast, Structure.save will save a single @<MOLECULE> mol2 file with multiple residues if the mol2 format is requested.

to_library()

Converts the ResidueTemplateContainer instance to a library of unique ResidueTemplate instances. The first of each kind of residue is taken

Returns

residuesdict {str

The residue library with all residues from this residue collection