src.routines (1 August 2008) | index /Users/d3y382/workspaces/apbs/pdb2pqr/branches/pdb2pqr-1.8/src/routines.py

`Routines for PDB2PQR
This module contains the protein object used in PDB2PQR and methods
used to correct, analyze, and optimize that protein.
----------------------------
PDB2PQR -- An automated pipeline for the setup, execution, and analysis of
Poisson-Boltzmann electrostatics calculations
Copyright (c) 2002-2011, Jens Erik Nielsen, University College Dublin;
Nathan A. Baker, Battelle Memorial Institute, Developed at the Pacific
Northwest National Laboratory, operated by Battelle Memorial Institute,
Pacific Northwest Division for the U.S. Department Energy.;
Paul Czodrowski & Gerhard Klebe, University of Marburg.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the names of University College Dublin, Battelle Memorial Institute,
Pacific Northwest National Laboratory, US Department of Energy, or University
of Marburg nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
----------------------------`

Modules

``

copy getopt | math os | re xml.sax | string sys

Classes

``

Cells
Routines

class Cells

``

`The cells object provides a better way to search for nearby atoms. A
pure all versus all search is O(n^2) - for every atom, every other atom
must be searched. This is rather inefficient, especially for large
proteins where cells may be tens of angstroms apart. The cell class
breaks down the xyz protein space into several 3-D cells of desired
size - then by simply examining atoms that fall into the adjacent
cells one can quickly find nearby cells.
NOTE: Ideally this should be somehow separated from the routines
object...
`

Methods defined here:

__init__(self, cellsize)
  `Initialize the cells.
  Parameters
  cellsize: The size of each cell (int)`

addCell(self, atom)
  `Add an atom to the cell
  Parameters
  atom: The atom to add (atom)`

assignCells(self, protein)
  `Place each atom in a virtual cell for easy neighbor comparison`

getNearCells(self, atom)
  `Find all atoms in bordering cells to an atom
  Parameters
  atom: The atom to use (atom)
  Returns
  closeatoms: A list of nearby atoms (list)`

removeCell(self, atom)
  `Remove the atom from a cell
  Parameters
  atom: The atom to add (atom)`

class Routines

``

Methods defined here:

__init__(self, protein, verbose, definition=None)
  `Initialize the Routines class. The class contains most
  of the main routines that run PDB2PQR
  Parameters
  protein: The protein to run PDB2PQR on (Protein)
  verbose: A flag to determine whether to write to
  stdout`

addHydrogens(self)
  `Add the hydrogens to the protein. This requires either
  the rebuildTetrahedral function for tetrahedral geometries
  or the standard quatfit methods. These methods use three
  nearby bonds to rebuild the atom; the closer the bonds, the
  more accurate the results. As such the peptide bonds are
  used when available.`

applyForcefield(self, forcefield)
  `Apply the forcefield to the atoms within the protein
  Parameters
  forcefield: The forcefield object (forcefield)
  Returns
  hitlist: A list of atoms that were found in
  the forcefield (list)
  misslist: A list of atoms that were not found in
  the forcefield (list)`

applyNameScheme(self, forcefield)
  `Apply the naming scheme of the given forcefield to the atoms
  within the protein
  Parameters
  forcefield: The forcefield object (forcefield)`

applyPatch(self, patchname, residue)
  `Apply a patch to the given residue. This is one of the key
  functions in PDB2PQR. A similar function appears in
  definitions.py - that version is needed for residue level
  subtitutions so certain protonation states (i.e. CYM, HSE)
  are detectatble on input.
  This version looks up the particular patch name in the
  patchmap stored in the protein, and then applies the
  various commands to the reference and actual residue
  structures.
  See the inline comments for a more detailed explanation.
  Parameters
  patchname: The name of the patch (string)
  residue: The residue to apply the patch to (residue)`

assignTermini(self, chain, neutraln=False, neutralc=False)
  `Assign the termini for the given chain by looking at
  the start and end residues.`

calculateDihedralAngles(self)
  `Calculate the dihedral angle for every residue within the protein`

debumpProtein(self)
  `Make sure that none of the added atoms were rebuilt
  on top of existing atoms. See each called function
  for more information.`

debumpProteinTopology(self)
  `Make sure that none of the added atoms in testtop.py were
  rebuilt on top of existing atoms. See each called function
  for more information.`

debumpResidue(self, residue, conflictnames)
  `Debump a specific residue. Only should be called
  if the residue has been detected to have a conflict.
  If called, try to rotate about dihedral angles to
  resolve the conflict.
  Parameters
  residue: The residue in question
  conflictnames: A list of atomnames that were
  rebuilt too close to other atoms
  Returns
  1 if successful, 0 otherwise`

debumpResidueTopology(self, residue, conflictnames)
  `Debump a specific residue for testtop. Only should
  be called if the residue has been detected to have a
  conflict. If called, try to rotate about dihedral
  angles to resolve the conflict.
  Parameters
  residue: The residue in question
  conflictnames: A list of atomnames that were
  rebuilt too close to other atoms
  Returns
  1 if successful, 0 otherwise`

findMissingHeavy(self)
  `Repair residues that contain missing heavy (non-Hydrogen) atoms`

findNearbyAtoms(self, atom)
  `Find nearby atoms for conflict-checking. Uses
  neighboring cells to compare atoms rather than an all
  versus all O(n^2) algorithm, which saves a great deal
  of time. There are several instances where we ignore
  potential conflicts; these include donor/acceptor pairs,
  atoms in the same residue, and bonded CYS bridges.
  Parameters
  atom: Find nearby atoms to this atom (Atom)
  Returns
  nearatoms: A list of atoms close to the atom.`

findNearbyAtomsTopology(self, atom)
  `Find nearby atoms for conflict-checking in testtop.
  Uses neighboring cells to compare atoms rather than
  an all versus all O(n^2) algorithm.
  Parameters
  atom: Find nearby atoms to this atom (Atom)
  Returns
  nearatoms: A list of atoms close to the atom.`

getClosestAtom(self, atom)
  `Get the closest atom that does not form a donor/acceptor pair.
  Used to detect potential conflicts.
  NOTE: Cells must be set before using this function.
  Parameters
  atom: The atom in question (Atom)
  Returns
  bestatom: The closest atom to the input atom that does not
  satisfy a donor/acceptor pair.`

getMoveableNames(self, residue, pivot)
  `Return all atomnames that are further away than the
  pivot atom.
  Parameters
  residue: The residue to use
  pivot: The pivot atomname`

getWarnings(self)
  `Get all warnings generated from routines`

getbumpscore(self, residue)
  `Get an bump score for the current structure`

getbumpscore_atom(self, atom)
  `Find nearby atoms for conflict-checking. Uses
  neighboring cells to compare atoms rather than an all
  versus all O(n^2) algorithm, which saves a great deal
  of time. There are several instances where we ignore
  potential conflicts; these include donor/acceptor pairs,
  atoms in the same residue, and bonded CYS bridges.
  Parameters
  atom: Find nearby atoms to this atom (Atom)
  Returns
  bumpscore: a bump score sum((dist-cutoff)**20 for all near atoms
  Jens rewrote this function from findNearbyAtoms to
  be usable for detecting bumps for optimzable hydrogens`

pickDihedralAngle(self, residue, conflictnames, oldnum=None)
  `Choose an angle number to use in debumping
  Algorithm
  Instead of simply picking a random chiangle, this function
  uses a more intelligent method to improve efficiency.
  The algorithm uses the names of the conflicting atoms
  within the residue to determine which angle number
  has the best chance of fixing the problem(s). The method
  also insures that the same chiangle will not be run twice
  in a row.
  Parameters
  residue: The residue that is being debumped (Residue)
  conflictnames: A list of atom names that are currently
  conflicts (list)
  oldnum : The old dihedral angle number (int)
  Returns
  bestnum : The new dihedral angle number (int)`

removeHydrogens(self)

repairHeavy(self)
  `Repair all heavy atoms. Unfortunately the first time we
  get to an atom we might not be able to rebuild it - it
  might depend on other atoms to be rebuild first (think side
  chains). As such a 'seenmap' is used to keep track of what
  we've already seen and subsequent attempts to rebuild the
  atom.`

runPROPKA(self, ph, ff, rootname, outname, options)
  `Run PROPKA on the current protein, setting protonation states to
  the correct values
  Parameters
  ph: The desired pH of the system
  ff: The forcefield name to be used
  outname: The name of the PQR outfile`

setDihedralAngle(self, residue, anglenum, angle)
  `Rotate a residue about a given angle. Uses the quatfit
  methods to perform the matrix mathematics.
  Parameters
  residue: The residue to rotate
  anglenum: The number of the angle to rotate as
  listed in residue.dihedrals
  angle: The desired angle.`

setDonorsAndAcceptors(self)
  `Set the donors and acceptors within the protein`

setReferenceDistance(self)
  `Set the distance to the CA atom in the residue.
  This is necessary for determining which atoms are
  allowed to move during rotations. Uses the
  shortestPath algorithm found in utilities.py.`

setStates(self)
  `Set the state of each residue. This is the last step
  before assigning the forcefield, but is necessary so
  as to distinguish between various protonation states.
  See aa.py for residue-specific functions.`

setTermini(self, neutraln=False, neutralc=False)
  `Set the termini for the protein. First set all known
  termini by looking at the ends of the chain. Then
  examine each residue, looking for internal chain breaks.`

updateBonds(self)
  `Update the bonding network of the protein. This happens
  in 3 steps:
  1. Applying the PEPTIDE patch to all Amino residues
  so as to add reference for the N(i+1) and C(i-1)
  atoms
  2. UpdateInternalBonds for inter-residue linking
  3. Set the links to the N(i+1) and C(i-1) atoms`

updateInternalBonds(self)
  `Update the internal bonding network using the reference
  objects in each atom.`

updateResidueTypes(self)
  `Find the type of residue as notated in the Amino Acid definition`

updateSSbridges(self)
  `Check for SS-bridge partners, and if present, set appropriate
  partners`

write(self, message, indent=0)
  `Write a message to stderr for debugging if verbose
  Parameters
  message: The message to write (string)
  indent : The indent level (int, default=0)`

Static methods defined here:

rebuildTetrahedral(residue, atomname)
  `Rebuild a tetrahedral hydrogen group. This is necessary
  due to the shortcomings of the quatfit routine - given a
  tetrahedral geometry and two existing hydrogens, the
  quatfit routines have two potential solutions. This function
  uses basic tetrahedral geometry to fix this issue.
  Parameters
  residue: The residue in question (residue)
  atomname: The atomname to add (string)
  Returns
  1 if successful, 0 otherwise`

Data

``

AAPATH = 'dat/AA.xml'
AAS = ['ALA', 'ARG', 'ASH', 'ASN', 'ASP', 'CYS', 'CYM', 'GLN', 'GLU', 'GLH', 'GLY', 'HIS', 'HID', 'HIE', 'HIP', 'HSD', 'HSE', 'HSP', 'ILE', 'LEU', ...]
BACKBONE = ['N', 'CA', 'C', 'O', 'O2', 'HA', 'HN', 'H', 'tN']
BONDED_SS_LIMIT = 2.5
BUMP_DIST = 2.0
BUMP_HDIST = 1.5
CELL_SIZE = 2
DIHEDRAL = 57.2958
INSTALLDIR = '/Users/d3y382/pdb2pqr/'
NAPATH = 'dat/NA.xml'
NAS = ['A', 'A5', 'A3', 'C', 'C5', 'C3', 'G', 'G5', 'G3', 'T', 'T5', 'T3', 'U', 'U5', 'U3', 'RA', 'RG', 'RC', 'RU', 'DA', ...]
PATCHPATH = 'dat/PATCHES.xml'
PEPTIDE_DIST = 1.7
REPAIR_LIMIT = 10
SMALL = 9.9999999999999995e-08
TMPDIR = 'tmp/'
__author__ = 'Jens Erik Nielsen, Todd Dolinsky, Yong Huang'
__date__ = '1 August 2008'

Author
`` |  | Jens Erik Nielsen, Todd Dolinsky, Yong Huang