hydrogens and submodule contents

hydrogens

Hydrogen optimization module for PDB2PQR.

This is an module for hydrogen optimization routines.

Todo

This module has too many lines and should be simplified.

Code author: Todd Dolinsky

Code author: Jens Erik Nielsen

Code author: Yong Huang

Code author: Nathan Baker

class pdb2pqr.hydrogens.HydrogenRoutines(debumper, handler)[source]

The main routines for hydrogen optimization.

Todo

This class really needs to be refactored.

__init__(debumper, handler)[source]

Initialize object.

Parameters:
cleanup()[source]

Delete extra carboxylic atoms.

If there are any extra carboxlyic *1 atoms, delete them. This may occur when no optimization is chosen.

initialize_full_optimization()[source]

Initialize the full optimization.

Detects all optimizeable donors and acceptors and sets the internal optlist.

initialize_wat_optimization()[source]

Initialize optimization for waters only.

Detects all optimizeable donors and acceptors and sets the internal optlist.

is_optimizeable(residue)[source]

Check to see if the given residue is optimizeable. There are three ways to identify a residue:

  1. By name (i.e., HIS)
  2. By reference name - a PDB file HSP has a HIS reference name
  3. By patch - applied by propka, terminal selection
Parameters:residue (Residue) – the residue in question
Returns:None if not optimizeable, otherwise the OptimizationHolder instance that corresponds to the residue.
Return type:None or OptimizationHolder
optimize_hydrogens()[source]

The main driver for the optimization.

Note

Should be called only after the optlist has been initialized.

Todo

Remove hard-coded progress threshold and increment values.

Todo

This function needs to be simplified.

parse_hydrogen(res, topo)[source]

Parse a list of lines in order to make a hydrogen definition.

This is the current definition: Name Ttyp  A R # Stdconf HT Chi OPTm

Todo

The type of the res appears to be incorrect.

Todo

This function is too long and needs to be simplified.

Parameters:
Returns:

the hydrogen definition object

Return type:

HydrogenDefinition

classmethod pka_switchstate(amb, state_id_)[source]

Switch a residue to a new state by first removing all hydrogens. This routine is used in pKa calculations only!

Parameters:
  • amb (tup) – the amibiguity to switch
  • state_id (int) – the state id to switch to
read_hydrogen_def(topo)[source]

Read the hydrogen definition file

Parameters:topo (Topology object) – Topology object
set_optimizeable_hydrogens()[source]

Set any hydrogen listed in HYDROGENS.xml that is optimizeable.

Used BEFORE hydrogen optimization to label atoms so that they won’t be debumped - i.e. if SER HG is too close to another atom, don’t debump but wait for optimization.

Note

This function should not be used if full optimization is not taking place.

switchstate(states, amb, state_id)[source]

Switch a residue to a new state by first removing all hydrogens.

Parameters:
  • states (list) – the list of states
  • amb (tup) – the amibiguity to switch
  • state_id (int) – the state id to switch to
pdb2pqr.hydrogens.create_handler(hyd_path='HYDROGENS.xml')[source]

Create and populate a hydrogen handler.

Parameters:hyd_def_file (string or pathlib.Path object) – path to hydrogen definition file
Returns:HydrogenHandler object
Return type:HydrogenHandler

hydrogens.optimize

Hydrogen optimization routines.

Code author: Todd Dolinsky

Code author: Jens Erik Nielsen

Code author: Yong Huang

Code author: Nathan Baker

class pdb2pqr.hydrogens.optimize.OptimizationHolder[source]

A holder class for the XML parser.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

class pdb2pqr.hydrogens.optimize.Optimize[source]

The holder class for the hydrogen optimization routines.

Individual optimization types inherit off of this class. Any functions used by multiple types appear here.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

static get_hbond_angle(atom1, atom2, atom3)[source]

Get the angle between three atoms

Parameters:
  • atom1 (Atom) – the first atom
  • atom2 (Atom) – the second (vertex) atom
  • atom3 (Atom) – the third atom
Returns:

the angle between the atoms in degrees

Return type:

float

static get_pair_energy(donor, acceptor)[source]

Get the energy between two atoms

Todo

Lots of code in this function could be accelerated with numpy.

Todo

Lots of hard-coded parameters in this function that need to be abstracted out.

Parameters:
  • donor (Atom) – the first atom in the pair
  • acceptor (Atom) – the second atom in the pair
Returns:

the energy of the pair

Return type:

float

classmethod get_position_with_three_bonds(atom)[source]

Find position for last bond in tetrahedral geometry.

Todo

Should this be a staticmethod rather than a classmethod?

Todo

Remove hard-coded values in function.

If there’s three bonds in a tetrahedral geometry, there’s only one available position. Find that position.

Parameters:atom (Atom) – atom to check
Returns:coordinates
Return type:(float, float, float)
classmethod get_positions_with_two_bonds(atom)[source]

Return possible coordinates for new bonds.

Todo

Remove some hard-coded values in this function.

Given a tetrahedral geometry with two existing bonds, return the two potential sets of coordinates that are possible for a new bond.

Parameters:atom (Atom) – atom to test for bonds
Returns:2-tuple of coordinates (floats)
Return type:tuple
is_hbond(donor, acc)[source]

Determine whether this donor acceptor pair is a hydrogen bond.

Todo

Remove hard-coded hydrogen bond distance and angles.

Parameters:
  • donor – donor atom
  • acc – acceptor atom
Returns:

whether this pair is a hydrogen bond

Return type:

bool

make_atom_with_no_bonds(atom, closeatom, addname)[source]

Create an atom with no bonds.

Called for water oxygen atoms with no current bonds. Uses the closeatom to place the new atom directly colinear with the atom and the closeatom.

Parameters:
  • atom (Atom) – the oxygen atom of the water
  • closeatom (Atom) – the nearby atom (donor/acceptor)
  • addname (str) – the name of the atom to add
classmethod make_atom_with_one_bond_h(atom, addname)[source]

Add a hydrogen to an alcoholic donor with one existing bond.

Todo

Does this need to be a classmethod or could it be a staticmethod?

Parameters:
  • atom (Atom) – existing atom
  • addname (str) – name of atom to add
classmethod make_atom_with_one_bond_lp(atom, addname)[source]

Add a lone pair to an alcoholic donor with one existing bond.

Todo

Does this need to be a classmethod or could it be a staticmethod?

Parameters:
  • atom (Atom) – existing atom
  • addname (str) – name of atom to add
classmethod make_water_with_one_bond(atom, addname)[source]

Add an atom to a water residue that already has one bond.

Uses the water reference structure to align the new atom.

Todo

Does this need to be a classmethod or could it be a staticmethod?

Parameters:
  • atom (Atom) – existing atom
  • addname (str) – name of atom to add
try_positions_three_bonds_h(donor, acc, newname, loc)[source]

Try making a hydrogen bond with the lone available position.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
  • newname (str) – name for new atom
Returns:

indication of whether atom was added

Return type:

bool

try_positions_three_bonds_lp(acc, donor, newname, loc)[source]

Make a hydrogen bond in the only position possible.

Try making a hydrogen bond using the lone available hydrogen position.

Parameters:
  • acc (Atom) – hydrogen bond acceptor
  • donor (Atom) – hydrogen bond donor
  • newname (str) – new atom name
  • loc ((float, float, float)) – location for atom (coordinates)
Returns:

indication whether atom was added

Return type:

bool

try_positions_with_two_bonds_h(donor, acc, newname, loc1, loc2)[source]

Try adding a new hydrogen to the two potential locations. If both form hydrogen bonds, place at whatever returns the best bond as determined by get_pair_energy.

Parameters:
Returns:

indication whether atom was added

Return type:

bool

try_positions_with_two_bonds_lp(acc, donor, newname, loc1, loc2)[source]

Attempt to place a LP on an atom.

Try placing an LP on a tetrahedral geometry with two existing bonds. If this isn’t a hydrogen bond it can return - otherwise ensure that the H(D)-A-LP angle is minimized.

Parameters:
  • acc (Atom) – hydrogen bond acceptor
  • donor (Atom) – hydrogen bond donor
  • newname (str) – name for lone pair
  • loc1 ((float, float, float)) – first location to try
  • loc2 ((float, float, float)) – second location to try
Returns:

indication of whether LP was added

Return type:

bool

try_single_alcoholic_h(donor, acc, newatom)[source]

Attempt to add an atom to make a hydrogen bond.

Todo

Remove some hard-coded values in this function.

After a new bond has been added using makeAtomWithOneBond(), try to find the best orientation by rotating to form a hydrogen bond. If a bond cannot be formed, remove the newatom (thereby returning to a single bond).

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
  • newatom (Atom) – new atom to add
Returns:

indication whether atom was added

Return type:

bool

try_single_alcoholic_lp(acc, donor, newatom)[source]

Attempt to add an atom to make a hydrogen bond.

Todo

Remove some hard-coded values in this function and figure out where others (e.g., “72”) come from.

After a new bond has been added using makeAtomWithOneBond(), ensure that a hydrogen bond has been made. If so, try to minimze the H(D)-A-LP angle. If that cannot be minimized, ignore the bond and remove the atom.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
  • newatom (Atom) – new atom to add
Returns:

indication whether atom was added

Return type:

bool

hydrogens.structures

Topology-related classes for hydrogen optimization.

class pdb2pqr.hydrogens.structures.Alcoholic(residue, optinstance, routines)[source]

The class for alcoholic residue.

__init__(residue, optinstance, routines)[source]

Initialize the alcoholic class by removing the alcoholic hydrogen if it exists.

Parameters:
  • residue (Residue) – the residue to optimize
  • optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize
  • routines (Debump) – debumping routines object
complete()[source]

Complete an alcoholic optimization.

Call finalize() and then remove all extra LP atoms.

finalize()[source]

Finalize an alcoholic residue.

Todo

Replace hard-coded values in the function.

Try to minimize conflict with nearby atoms by building away from them. Called when LPs are still present so as to account for their bonds.

try_acceptor(acc, donor)[source]

Add a lone pair to an optimizeable residue.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
Returns:

indication of whether addition was successful

Return type:

bool

try_both(donor, acc, accobj)[source]

Attempt to optimize both the donor and acceptor.

If one is fixed, we only need to try one side. Otherwise first try to satisfy the donor - if that’s succesful, try to satisfy the acceptor. An undo may be necessary if the donor is satisfied and the acceptor isn’t.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
  • accobj (Flip) – a Flip-like hydrogen bond structure object
Returns:

indication of whether hydrogen was added

Return type:

bool

try_donor(donor, acc)[source]

Add hydrogen to an optimizable residue.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
Returns:

indication of whether addition was successful

Return type:

bool

class pdb2pqr.hydrogens.structures.Carboxylic(residue, optinstance, routines)[source]

The class for carboxylic residues

__init__(residue, optinstance, routines)[source]

Initialize carboxylic optimization class.

Initialize a case where the lone hydrogen atom can have four different orientations. Works similar to initializeFlip() by pre-adding the necessary atoms.

This also takes into account that the carboxyl group has different bond lengths for the two C-O bonds - this is probably due to one bond being assigned as a C=O. As a result hydrogens are only added to the C-O (longer) bond.

Parameters:
  • residue (Residue) – the residue to flip
  • optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize
  • routines (Debump) – debumping routines object
complete()[source]

If not already fixed, finalize the optimization.

finalize()[source]

Finalize a protontated residue.

Try to minimize conflict with nearby atoms.

fix(donor, acc)[source]

Fix the carboxylic residue.

is_carboxylic_hbond(donor, acc)[source]

Determine whether this donor acceptor pair is a hydrogen bond.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
  • accobj (Flip) – a Flip-like hydrogen bond structure object
Returns:

indication of whether hydrogen was added

Return type:

bool

rename(hydatom)[source]

Rename the optimized atoms appropriately.

This is done since the forcefields tend to require that the hydrogen is linked to a specific oxygen, and this atom may have different parameter values.

Parameters:hydatom (Atom) – the hydrogen atom that was added
try_acceptor(acc, donor)[source]

Add lone pair to an optimizable residue.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
Returns:

indication of whether addition was successful

Return type:

bool

try_both(donor, acc, accobj)[source]

Attempt to optimize donor and acceptor.

Called when both the donor and acceptor are optimizeable. If one is fixed, we only need to try one side. Otherwise first try to satisfy the donor - if that’s succesful, try to satisfy the acceptor. An undo may be necessary if the donor is satisfied and the acceptor isn’t.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
  • accobj (Flip) – a Flip-like hydrogen bond structure object
Returns:

indication of whether hydrogen was added

Return type:

bool

try_donor(donor, acc)[source]

Add hydrogen to an optimizable residue.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
Returns:

indication of whether addition was successful

Return type:

bool

class pdb2pqr.hydrogens.structures.Flip(residue, optinstance, routines)[source]

The holder for optimization of flippable residues.

__init__(residue, optinstance, routines)[source]

Initialize a potential flip.

Rather than flipping the given residue back and forth, take each atom that would be flipped and pre-flip it, making a new *FLIP atom in its place.

Parameters:
  • residue (Residue) – the residue to flip
  • optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize
  • routines (Debump) – debumping routines object
complete()[source]

Complete the flippable residue optimization.

Call the finalize() function, and then rename all FLIP atoms back to their standard names.

finalize()[source]

Finalize a flippable group back to its original state.

Since the original atoms are now *FLIP, it deletes the * atoms and renames the *FLIP atoms back to *.

fix_flip(bondatom)[source]

Remove atoms if hydrogen bond has been found for specified atom.

If bondatom is of type *FLIP, remove all * atoms, otherwise remove all *FLIP atoms.

Parameters:bondatom (Atom) – atom to flip
try_acceptor(acc, donor)[source]

Aa lone pair to an optimizable residue.

Parameters:
  • acc (Atom) – hydrogen bond acceptor
  • donor (Atom) – hydrogen bond donor
Returns:

indication of whether addition was successful

Return type:

bool

try_both(donor, acc, accobj)[source]

Try to optimize both donor and acceptor bonds.

Called when both the donor and acceptor are optimizeable. If one is fixed, we only need to try one side. Otherwise first try to satisfy the donor - if that’s succesful, try to satisfy the acceptor. An undo may be necessary if the donor is satisfied and the acceptor isn’t.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
  • accobj (Flip) – a Flip-like hydrogen bond structure object
Returns:

indication of whether hydrogen was added

Return type:

bool

try_donor(donor, acc)[source]

Add hydrogen to an optimizable residue.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
Returns:

indication of whether addition was successful

Return type:

bool

class pdb2pqr.hydrogens.structures.Generic(residue, optinstance, routines)[source]

Generic optimization class

__init__(residue, optinstance, routines)[source]

Initialize a potential optimization.

Parameters:
  • residue (Residue) – the residue to optimize
  • optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize
  • routines (Debump) – debumping routines object
complete()[source]

If not already fixed, finalize.

finalize()[source]

Initialize some variable and pass.

class pdb2pqr.hydrogens.structures.HydrogenAmbiguity(residue, hdef, routines)[source]

Contains information about ambiguities in hydrogen conformations.

__init__(residue, hdef, routines)[source]

If the residue has a rotateable hydrogen, remove it.

If it can be flipped, pre-flip the residue by creating all additional atoms.

Parameters:
  • residue (Residue) – the residue in question
  • hdef – the hydrogen definition matching the residue
  • routines (Debump) – the debumping routines object
class pdb2pqr.hydrogens.structures.HydrogenConformation(hname, boundatom, bondlength)[source]

Class for possible hydrogen conformations.

The HydrogenConformation class contains data about possible hydrogen conformations as specified in the hydrogen data file.

__init__(hname, boundatom, bondlength)[source]
Parameters:
  • hname – The hydrogen name (string)
  • boundatom – The atom the hydrogen is bound to (string)
  • bondlength – The bond length (float)
add_atom(atom)[source]

Add an atom to the list of atoms.

Parameters:atom (DefinitionAtom) – the atom to be added
class pdb2pqr.hydrogens.structures.HydrogenDefinition(name, opttype, optangle, map_)[source]

Class for potential ambiguities in amino acid hydrogens.

It is essentially the hydrogen definition file in object form.

__init__(name, opttype, optangle, map_)[source]

Initialize the object with information from the definition file.

See HYDROGENS.XML for more information.

Parameters:
  • name (str) – the name of the grouping
  • opttype (str) – the optimization type of the grouping
  • optangle (str) – the optimization angle of the grouping
  • map – the map of hydrogens
add_conf(conf)[source]

Add a hydrogen conformation to the list.

Parameters:conf (HydrogenConformation) – the conformation to be added
class pdb2pqr.hydrogens.structures.HydrogenHandler[source]

Extends the SAX XML Parser to parse the Hydrogens.xml class.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

characters(text)[source]

Set a given attribute of the object to the text.

Parameters:text (str) – value of the attribute
endElement(name)[source]

Complete object is passed in by name parameter.

Todo

Rename this and related methods to conform with PEP8

Parameters:name (str) – name for element
startElement(name, _)[source]

Create optimization holder objects or atoms.

Todo

Rename this and related methods to conform with PEP8

Parameters:name (str) – name for element
class pdb2pqr.hydrogens.structures.PotentialBond(atom1, atom2, dist)[source]

A class containing the hydrogen bond structure.

__init__(atom1, atom2, dist)[source]

Initialize the class.

Parameters:
  • atom1 (Atom) – the first atom in the potential bond
  • atom2 (Atom) – the second atom in the potential bond
  • dist (float) – the distance between the two atoms
class pdb2pqr.hydrogens.structures.Water(residue, optinstance, routines)[source]

The class for water residues.

__init__(residue, optinstance, routines)[source]

Initialize the water optimization class.

Parameters:
  • residue (Residue) – the residue to flip
  • optinstance (OptimizationHandler) – the optimization instance containing information about what to optimize
  • routines (Debump) – debumping routines object
complete()[source]

Complete the water optimization process.

finalize()[source]

Finalize a water residue.

Try to minimize conflict with nearby atoms by building away from them. Called when LPs are still present so as to account for their bonds.

try_acceptor(acc, donor)[source]

The main driver for adding an LP to an optimizeable residue.

Todo

This looks like a bug: donorh ends up being the last item in donor.bonds. This may be fixed by setting a best_donorh to go with bestdist and using best_donorh in the function below

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
Returns:

indication of whether addition was successful

Return type:

bool

try_both(donor, acc, accobj)[source]

Attempt to optimize both the donor and the acceptor.

If one is fixed, we only need to try one side. Otherwise first try to satisfy the donor - if that’s successful, try to satisfy the acceptor. An undo may be necessary if the donor is satisfied and the acceptor isn’t.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
  • accobj (Flip) – a Flip-like hydrogen bond structure object
Returns:

indication of whether hydrogen was added

Return type:

bool

try_donor(donor, acc)[source]

Add hydrogen to an optimizable residue.

Parameters:
  • donor (Atom) – hydrogen bond donor
  • acc (Atom) – hydrogen bond acceptor
Returns:

indication of whether addition was successful

Return type:

bool