Fitting Loops Into Gaps¶
Loops often need to undergo conformational changes to fit into gaps defined by stem residues. ProMod3 implements two algorithms performing this task:
Cyclic coordinate descent (CCD) [canutescu2003]
Kinematic closure (KIC) [coutsias2005]
In case of small gaps or small issues in the loop you might also consider the
BackboneRelaxer
.
CCD¶
The ProMod3 implementation of the cyclic coordinate descent first superposes the n-stem of the input loop with the provided n-stem positions. In every iteration of the algorithm, we loop over all residues of the loop and find the ideal phi/psi angles to minimize the RMSD between the c-stem and the target c-stem positions. Iterations continue until a c-stem RMSD threshold is reached or the number of iterations hits a limit. By performing CCD, unfavorable backbone dihedral pairs can be introduced. It is therefore optionally possible to use torsion samplers to guide the iterative process. In this case, the algorithm calculates the probability of observing the dihedral pair before and after performing the phi/psi update. If the fraction after/before is smaller than a uniform random number in the range [0,1[, the proposed dihedral pair gets rejected. Please note, that this increases the probability of non-convergence.
- class promod3.modelling.CCD¶
Class, that sets up everything you need to perform a particular loop closing action.
- CCD(sequence, n_stem, c_stem, torsion_sampler, max_steps, rmsd_cutoff, seed)¶
All runs with this CCD object will be with application of torsion samplers to avoid moving into unfavourable regions of the backbone dihedrals.
- Parameters:
sequence (
str
) – Sequence of the backbones to be closedn_stem (
ost.mol.ResidueHandle
) – Residue defining the n_stem. If the residue before n_stem doesn’t exist, the torsion sampler will use a default residue (ALA) and and phi angle (-1.0472) to evaluate the first angle.c_stem (
ost.mol.ResidueHandle
) – Residue defining the c_stem. If the residue after c_stem doesn’t exist, the torsion sampler will use a default residue (ALA) and psi angle (-0.7854) to evaluate the last angle.torsion_sampler (
TorsionSampler
/list
ofTorsionSampler
) – To extract probabilities for the analysis of the backbone dihedrals. Either a list of torsion samplers (one for for every residue of the loop to be closed) or a single one (used for all residues).max_steps (
int
) – Maximal number of iterationsrmsd_cutoff (
float
) – The algorithm stops as soon as the c_stem of the loop to be closed has RMSD below the c_stemseed (
int
) – Seed of random number generator to decide whether new phi/psi pair should be accepted.
- Raises:
RuntimeError
if a list of torsion samplers is given with inconsistent length regarding the sequence. Another requirement is that all backbone atoms of the stems must be present.
- CCD(n_stem, c_stem, max_steps, rmsd_cutoff)¶
All runs with this CCD object will be without application of torsion samplers. This is faster but might lead to weird backbone dihedral pairs.
- Parameters:
n_stem (
ost.mol.ResidueHandle
) – Residue defining the n_stemc_stem (
ost.mol.ResidueHandle
) – Residue defining the c_stemmax_steps (
int
) – Maximal number of iterationsrmsd_cutoff (
float
) – The algorithm stops as soon as the c_stem of the loop to be closed has RMSD below the given c_stem
- Close(bb_list)¶
Closes given bb_list with the settings set at initialization.
- Parameters:
bb_list (
BackboneList
) – Loop to be closed- Returns:
Whether rmsd_cutoff has been reached
- Return type:
- Raises:
RuntimeError
if the CCD object has been initialized withTorsionSampler
support and the length of the bb_list is not consistent with the initial sequence.
KIC¶
The kinematic closure leads to a fragmentation of the loop based on given pivot residues. It then calculates possible relative orientations of these fragments by considering constraints of bond length and bond angles at these pivot residues. Due to the internal mathematical formalism, up to 16 solutions can be found for a given loop closing problem.
- class promod3.modelling.KIC¶
Class, that sets up everything you need to perform a particular loop closing action.
- KIC(n_stem, c_stem)¶
All runs of this KIC closing object will adapt the input loops to these stem residues.
- Parameters:
n_stem – Residue describing the stem towards n_ter
c_stem – Residue describing the stem towards c_ter
- Close(bb_list, pivot_one, pivot_two, pivot_three)¶
Applies KIC algorithm, so that the output loops match the given stem residues
- Parameters:
bb_list (
BackboneList
) – Loop to be closedpivot_one (
int
) – Index of first pivot residuepivot_two (
int
) – Index of second pivot residuepivot_three (
int
) – Index of third pivot residue
- Returns:
List of closed loops (maximum of 16 entries)
- Return type:
list
ofBackboneList
- Raises:
RuntimeError
in case of invalid pivot indices.
Relaxing Backbones¶
In many cases one wants to quickly relax a loop. This can be useful to close
small gaps in the backbone or resolve the most severe clashes. The
BackboneRelaxer
internally sets up a topology for the input loop.
Once setup, every loop of the same length and sequence can be relaxed by
the relaxer.
- class promod3.modelling.BackboneRelaxer(bb_list, ff, fix_nterm=True, fix_cterm=True)¶
Sets up a molecular mechanics topology for given bb_list. Every
BackboneList
of same length and sequence can then be relaxed. The parametrization is taken from ff, simply neglecting all interactions to non backbone atoms. The electrostatics get neglected completely by setting all charges to 0.0.- Parameters:
bb_list (
BackboneList
) – Basis for topology creationff (
promod3.loop.ForcefieldLookup
) – Source for parametrizationfix_nterm (
bool
) – Whether N-terminal backbone positions (N, CA, CB) should be kept rigid during relaxation (C and O are left to move).fix_cterm (
bool
) – Whether C-terminal backbone positions (CA, CB, C, O) should be kept rigid during relaxation (N is left to move).
- class promod3.modelling.BackboneRelaxer(bb_list, density, resolution, fix_nterm=True, fix_cterm=True)¶
- Parameters:
bb_list (
BackboneList
) – Basis for topology creationfix_nterm (
bool
) – Whether N-terminal backbone positions (N, CA, CB) should be kept rigid during relaxation.fix_cterm (
bool
) – Whether C-terminal backbone positions (CA, CB, C, O) should be kept rigid during relaxation.
- Raises:
RuntimeError
if size of bb_list is below 2
- Run(bb_list, steps=100, stop_criterion=0.01)¶
Performs steepest descent on given BackboneList. The function possibly fails if there are particles (almost) on top of each other, resulting in NaN positions in the OpenMM system. The positions of bb_list are not touched in this case and the function returns an infinit potential energy. In Python you can check for that with float(“inf”).
- Parameters:
bb_list (
BackboneList
) – To be relaxedsteps (
int
) – number of steepest descent stepsstop_criterion (
float
) – If maximum force acting on a particle falls below that threshold, the relaxation aborts.
- Returns:
Forcefield energy upon relaxation, infinity in case of OpenMM Error
- Return type:
- Raises:
RuntimeError
if bb_list has not the same size or sequence as the initial one.
- AddNRestraint(idx, pos, force_constant=100000)¶
Adds harmonic position restraint for nitrogen atom at specified residue
- Parameters:
idx (
int
) – Idx of residuepos (
ost.geom.Vec3
) – Restraint Position (in Angstrom)force_constant (
float
) – Force constant in kJ/mol/nm^2
- Raises:
RuntimeError
if idx is too large
- AddCARestraint(idx, pos, force_constant=100000)¶
Adds harmonic position restraint for CA atom at specified residue
- Parameters:
idx (
int
) – Idx of residuepos (
ost.geom.Vec3
) – Restraint Position (in Angstrom)force_constant (
float
) – Force constant in kJ/mol/nm^2
- Raises:
RuntimeError
if idx is too large
- AddCBRestraint(idx, pos, force_constant=100000)¶
Adds harmonic position restraint for CB atom at specified residue, doesn’t do anything if specified residue is a glycine
- Parameters:
idx (
int
) – Idx of residuepos (
ost.geom.Vec3
) – Restraint Position (in Angstrom)force_constant (
float
) – Force constant in kJ/mol/nm^2
- Raises:
RuntimeError
if idx is too large
- AddCRestraint(idx, pos, force_constant=100000)¶
Adds harmonic position restraint for C atom at specified residue
- Parameters:
idx (
int
) – Idx of residuepos (
ost.geom.Vec3
) – Restraint Position (in Angstrom)force_constant (
float
) – Force constant in kJ/mol/nm^2
- Raises:
RuntimeError
if idx is too large
- AddORestraint(idx, pos, force_constant=100000)¶
Adds harmonic position restraint for O atom at specified residue
- Parameters:
idx (
int
) – Idx of residuepos (
ost.geom.Vec3
) – Restraint Position (in Angstrom)force_constant (
float
) – Force constant in kJ/mol/nm^2
- Raises:
RuntimeError
if idx is too large
- SetNonBondedCutoff(nonbonded_cutoff)¶
Defines cutoff to set for non bonded interactions. By default, all atom- pairs are compared which is the fastest for small backbones (e.g. in
CloseSmallDeletions()
). Otherwise, a cutoff around 5 is reasonable as we ignore electrostatics.- Parameters:
nonbonded_cutoff (
float
) – Cutoff to set for non bonded interactions. Negative means no cutoff.
Relaxing All Atom Loops¶
After the reconstruction of loop sidechains with the
Reconstruct()
method of
SidechainReconstructor
, it may be desired to
quickly relax the loop. The AllAtomRelaxer
class takes care of that.
Example usage:
from ost import io
from promod3 import modelling, loop
# load example (has res. numbering starting at 1)
prot = io.LoadPDB('data/1CRN.pdb')
res_list = prot.residues
seqres_str = ''.join([r.one_letter_code for r in res_list])
# initialize AllAtom environment and sidechain reconstructor
env = loop.AllAtomEnv(seqres_str)
env.SetInitialEnvironment(prot)
sc_rec = modelling.SidechainReconstructor()
sc_rec.AttachEnvironment(env)
# "reconstruct" subset (res. num. 6..10) -> sidechains kept here
sc_result = sc_rec.Reconstruct(6, 5)
# setup sys creator
ff_lookup = loop.ForcefieldLookup.GetDefault()
mm_sys = loop.MmSystemCreator(ff_lookup)
relaxer = modelling.AllAtomRelaxer(sc_result, mm_sys)
# relax loop
pot_e = relaxer.Run(sc_result, 300, 0.1)
print("Potential energy after: %g" % pot_e)
# update environment with solution
env.SetEnvironment(sc_result.env_pos)
# store all positions of environment
io.SavePDB(env.GetAllAtomPositions().ToEntity(), 'aa_relax_test.pdb')
- class promod3.modelling.AllAtomRelaxer(sc_data, mm_system_creator)¶
Setup relaxer for a given sidechain reconstruction result and a given MM system creator, which takes care of generating a simulation object.
N/C stems of loop are fixed if they are non-terminal.
- Parameters:
sc_data (
SidechainReconstructionData
) – Sidechain reconstruction resultmm_system_creator (
MmSystemCreator
) – System creator to be used here
- Run(sc_data, steps=100, stop_criterion=0.01)¶
Performs steepest descent for this system and writes updated positions into sc_data.env_pos.all_pos. The function possibly fails if there are particles (almost) on top of each other, resulting in NaN positions in the OpenMM system. The positions of sc_data.env_pos.all_pos are not touched in this case and the function returns an infinit potential energy. In Python you can check for that with float(“inf”).
- Parameters:
sc_data (
SidechainReconstructionData
) – Sidechain reconstruction result to be updatedsteps (
int
) – Number of steepest descent stepsstop_criterion (
float
) – If maximum force acting on a particle falls below that threshold, the relaxation aborts.
- Returns:
Potential energy after relaxation, infinity in case of OpenMM Error
- Return type:
- Raises:
RuntimeError
if sc_data is incompatible with the one given in the constructor.
- UpdatePositions(sc_data)¶
Resets simulation positions to a new set of positions. It is assumed that this sc_data object has the same amino acids as loops and surrounding and the same disulfid bridges as the one given in the constructor.
- Parameters:
sc_data (
SidechainReconstructionData
) – Get new positions from sc_data.env_pos.all_pos- Raises:
RuntimeError
if sc_data is incompatible with the one given in the constructor.
- GetSystemCreator()¶
- Returns:
MM system creator passed in the constructor
- Return type: