You are reading the documentation for version 3.3 of ProMod3. You may also want to read the documentation for: 1.3 2.0 2.1 3.0 3.1 3.2

Generating Loops De Novo

The Monte Carlo capabilities of ProMod3 are mainly targeted at generating de novo structure candidates for loops or N-/C-Termini. Every iteration of the sampling process consists basically of four steps and we define objects for each step:

These steps can be arbitrarily combined to generate custom Monte Carlo sampling pipelines. This combination either happens manually or by using the convenient SampleMonteCarlo() function. For example, here we show how to apply Monte Carlo sampling to the N-terminal part of crambin:

from ost import io
from promod3 import loop, scoring, modelling
import numpy as np

# setup protein
prot = io.LoadPDB('data/1CRN.pdb')

chain_index = 0
start_resnum = 1
terminal_len = 8

seqres = ''.join([r.one_letter_code for r in prot.residues])
terminal_seqres = seqres[:terminal_len]

# setup mc_sampler
torsion_sampler = loop.LoadTorsionSampler()
mc_sampler = modelling.SoftSampler(terminal_seqres, torsion_sampler,
                                   10.0 / 180 * np.pi)

# setup mc_closer
mc_closer = modelling.NTerminalCloser(prot.residues[terminal_len-1])

# setup backbone scorer with clash and cbeta scoring
score_env = scoring.BackboneScoreEnv(seqres)
score_env.SetInitialEnvironment(prot)
scorer = scoring.BackboneOverallScorer()
scorer["cbeta"] = scoring.LoadCBetaScorer()
scorer["clash"] = scoring.ClashScorer()
scorer.AttachEnvironment(score_env)

# set up mc_scorer
weights = dict()
weights["cbeta"] = 10.0
weights["clash"] = 0.1
mc_scorer = modelling.LinearScorer(scorer, score_env,
                                   start_resnum, terminal_len,
                                   chain_index, weights)

# setup mc_cooler
mc_cooler = modelling.ExponentialCooler(100, 100, 0.9)

# create BackboneList from n-terminus
bb_list = loop.BackboneList(terminal_seqres,
                            prot.residues[:terminal_len])

# shake it!
modelling.SampleMonteCarlo(mc_sampler, mc_closer, mc_scorer,
                           mc_cooler, 10000, bb_list, False, 0)

# save down the result
io.SavePDB(bb_list.ToEntity(), "sampled_frag.pdb")
promod3.modelling.SampleMonteCarlo(sampler, closer, scorer, cooler, steps, bb_list, initialize, seed=0, lowest_energy_conformation=True)

A convenient function to perform Monte Carlo sampling using a simulated annealing scheme. In every iteration, a new loop conformation gets proposed by the provided sampler and closed by the closer. Upon scoring, this new conformation gets accepted/rejected using a metropolis criterion based on the temperature given by the cooler => acceptance probability: exp(-delta_score/T). The result is stored in bb_list (passed by reference, so NO return value) and is either the lowest energy conformation ever encountered or the last accepted proposal.

Parameters:
  • sampler (Sampler Object) – Sampler object capable of initializing and altering conformations.
  • closer (Closer Object) – Closer object to adapt a new conformation to the environment.
  • scorer (Scorer Object) – Scorer object to score new loop conformations.
  • cooler (Cooler Object) – Cooler object to control the temperature of the Monte Carlo trajectory.
  • steps (int) – Number of Monte Carlo iterations to be performed.
  • bb_list (BackboneList) – The chosen conformation gets stored here.
  • initialize (bool) – Whether a new bb_list should be generated as starting point, based on the samplers Initialize function. The input bb_list gets used otherwise.
  • seed (int) – Seed for internal random number generator.
  • lowest_energy_conformation (bool) – If True, we choose the lowest scoring conformation of the trajectory. Otherwise, the last accepted proposal.

Sampler Object

The sampler objects can be used to generate initial conformations and propose new conformations for a sequence of interest. They build the basis for any Monte Carlo sampling pipeline. You can either use one of the provided samplers or any object that implements the functionality of SamplerBase.

class promod3.modelling.SamplerBase

Abstract base class defining the functions that must be implemented by any sampler.

Initialize(bb_list)

Supposed to initialize structural information from scratch. The sequence of the generated promod3.loop.BackboneList is taken from bb_list.

Parameters:bb_list (promod3.loop.BackboneList) – Passed by reference, so the resulting promod3.loop.BackboneList is assigned to this parameter. Sequence / length stay the same.
Returns:None
ProposeStep(actual_positions, proposed_positions)

Takes current positions and proposes a new conformation. There is no guarantee on maintining any special RT state. The Closer Object is supposed to sort that out.

Parameters:
Returns:

None
class promod3.modelling.PhiPsiSampler(sequence, torsion_sampler, n_stem_phi=-1.0472, c_stem_psi=-0.78540, prev_aa='A', next_aa='A', seed=0)

The PhiPsiSampler randomly draws and sets phi/psi dihedral angles from a distribution provided by the torsion_sampler.

Parameters:
  • sequence (str) – Sequence that should be sampled
  • torsion_sampler (TorsionSampler) – Sampler, from which the phi/psi pairs are drawn. It is also possible to pass a list of samplers with same size as the sequence to assign a specific sampler per residue.
  • n_stem_phi (float) – Phi angle of the n_stem. This angle is not defined in the sampling region. If the first residue gets selected for changing the dihedral angles, it draws a psi angle given n_stem_phi.
  • c_stem_psi (float) – Psi angle of c_stem. This angle is not defined in the sampling region. If the last residue gets selected for changing the dihedral angles, it draws a phi angle given c_stem_psi.
  • prev_aa (str) – This parameter is necessary to extract the according histogram index for the first residue from the torsion_sampler. (Remember: The torsion sampler always considers triplets)
  • next_aa (str) – This parameter is necessary to extract the according histogram index for the last residue from the torsion_sampler. (Remember: The torsion sampler always considers triplets)
  • seed (int) – Seed for the internal random number generators.
Initialize(bb_list)

Sets up a new BackboneList by randomly drawing phi/psi dihedral angles.

Parameters:bb_list (BackboneList) – The newly created conformation gets stored in here
ProposeStep(actual_positions, proposed_position)

Randomly selects one of the residues and resets its phi/psi values according to a random draw from the internal torsion samplers. In case of the first residue, only a psi given phi is drawn. Same principle also applies for the last residue.

Parameters:
  • actual_positions (BackboneList) – Conformation to be changed
  • proposed_positions (BackboneList) – Changed conformation gets stored in here
Raises:

RuntimeError If size of actual_positions is not consistent with the internal sequence. Note, that the sequence itself doesn’t get checked for efficiency reasons.
class promod3.modelling.SoftSampler(sequence, torsion_sampler, max_dev, n_stem_phi=-1.0472, c_stem_psi=-0.78540, prev_aa='A', next_aa='A', seed=0)

Instead of drawing completely new values for a residues phi/psi angles, only one angle gets altered by a maximum value of max_dev in the SoftSampler.

Parameters:
  • sequence (str) – Sequence that should be sampled
  • torsion_sampler (TorsionSampler) – Sampler, from which the phi/psi probablities are extracted. It is also possible to pass a list of samplers with same size as the sequence to assign a specific sampler per residue.
  • max_dev – Maximal deviation of dihedral angle from its original value per sampling step.
  • n_stem_phi (float) – Phi angle of the n_stem. This angle is not defined in the sampling region. If the psi angle of the first residue gets selected to be changed, n_stem_phi is used to calculate the phi/psi probability to estimate the acceptance probability.
  • c_stem_psi (float) – Psi angle of c_stem. This angle is not defined in the sampling region. If the phi angle of the last residue gets selected to be changed, c_stem_psi is used to calculate the phi/psi probability to estimate the acceptance probability.
  • prev_aa (str) – This parameter is necessary to extract the according histogram index for the first residue from the torsion_sampler. (Remember: The torsion sampler always considers triplets)
  • next_aa (str) – This parameter is necessary to extract the according histogram index for the last residue from the torsion_sampler. (Remember: The torsion sampler always considers triplets)
  • seed (int) – Seed for the internal random number generators.
Initialize(bb_list)

Sets up a new BackboneList by randomly drawing phi/psi dihedral angles.

Parameters:bb_list (BackboneList) – The newly created conformation gets stored in here
ProposeStep(actual_positions, proposed_position)

In an iterative process, the SoftSampler randomly selects one of the possible dihedral angles in a conformation and changes it by a random value in [-max_dev, max_dev]. The acceptance probability of this change is the fraction of the phi/psi probability before and after changing the single angle in the particular residue. There is a maximum of 100 iterations. It is therefore theoretically possible, that nothing happens when a new step should be proposed

Parameters:
  • actual_positions (BackboneList) – Conformation to be changed
  • proposed_positions (BackboneList) – Changed conformation gets stored in here
Raises:

RuntimeError If size of actual_positions is not consistent with the internal sequence. Note, that the sequence itself doesn’t get checked for efficiency reasons.
class promod3.modelling.FragmentSampler(sequence, fraggers, init_bb_list=BackboneList(sequence), sampling_start_index=0, init_fragments=3, seed=0)

The FragmentSampler samples by replacing full fragments originating from a list of Fragger objects. The region, that actually gets sampled is determined by sampling_start_index and number of Fragger objects being available. All parts not covered by any fragger remain rigid.

Parameters:
  • sequence (str) – Overall sequence
  • fraggers (list) – A list of Fragger objects. The first fragger covers the region starting at the letter sampling_start_index of the sequence and so on. All fraggers must contain fragments of equal size.
  • init_bb_list (BackboneList) – Initial conformation, that serves as a starting point for sampling. The default gets constructed using the default constructor of BackboneList and results in a helix.
  • sampling_start_index (int) – Defines the beginning of the region, that actually gets sampled.
  • init_fragments (int) – When calling the Initialize function, the positions get set to the ones of init_bb_list. This is the number of fragments that gets randomly selected and inserted.
  • seed (int) – Seed for the internal random number generators
Initialize(bb_list)

Sets up a new BackboneList by setting the setting bb_list = init_bb_list and randomly replace n fragments with n = init_fragments

Parameters:bb_list (BackboneList) – The newly created conformation gets stored in here
ProposeStep(actual_step, proposed_position)

Randomly selects a position and selects a random fragment from the according fragger object to alter the conformation.

Parameters:
  • actual_positions (BackboneList) – Conformation to be changed
  • proposed_positions (BackboneList) – Changed conformation gets stored in here

Closer Object

After the proposal of new conformations by the sampler objects, the conformations typically have to undergo some structural changes, so they fit to a given environment. This can either be structural changes, that the stems of the sampled conformation overlap with given stem residues or or simple stem superposition in case of terminal sampling. You can either use any of the provided closers or any object that implements the functionality of CloserBase.

class promod3.modelling.CloserBase

Abstract base class defining the functions that must be implemented by any closer.

Close(actual_positions, closed_positions)

Takes current positions and proposes a new conformation that fits to a given environment.

Parameters:
Returns:

Whether closing procedure was successful
Return type:

bool
class promod3.modelling.CCDCloser(n_stem, c_stem, sequence, torsion_sampler, seed)

The CCDCloser applies the CCD algorithm to the sampled conformation to enforce the match between the conformations stem residue and the stems given by the closer. The torsion_sampler is used to avoid moving into unfavourable phi/psi ranges.

Parameters:
  • n_stem (ost.mol.ResidueHandle) – Defining stem positions the closed conformation should adapt. See CCD().
  • c_stem (ost.mol.ResidueHandle) – Defining stem positions the closed conformation should adapt. See CCD().
  • sequence (str) – Sequence of the conformation to be closed.
  • torsion_sampler (TorsionSampler / list of TorsionSampler) – To enforce valid phi/psi ranges. Alternatively, you can also pass a list of sampler objects to assign a unique torsion sampler to every residue of the conformation to be closed.
  • seed (int) – Seed for internal random generators.
Close(actual_positions, closed_positions)
Parameters:
  • actual_positions (BackboneList) – Conformation to be closed.
  • closed_positions (BackboneList) – Closed conformation gets stored in here.
Returns:

Whether CCD converged
class promod3.modelling.DirtyCCDCloser(n_stem, c_stem)

The DirtyCCDCloser applies the CCD algorithm to the sampled conformation to enforce the match between the conformations stem residue and the stems given by the closer. There is no check for reasonable backbone dihedral angles as it is the case for the CCDCloser.

Parameters:
Close(actual_positions, closed_positions)
Parameters:
  • actual_positions (BackboneList) – Conformation to be closed.
  • closed_positions (BackboneList) – Closed conformation gets stored in here.
Returns:

Whether CCD converged
class promod3.modelling.KICCloser(n_stem, c_stem, seed)

The KIC closer randomly picks three pivot residues in the conformation to be closed and applies the KIC algorithm. KIC gives up to 16 possible solutions. The KICCloser simply picks the first one.

Parameters:
  • n_stem (ost.mol.ResidueHandle) – Defining stem positions the closed conformation should adapt.
  • c_stem (ost.mol.ResidueHandle) – Defining stem positions the closed conformation should adapt.
  • seed (int) – Seed for internal random generators.
Close(actual_positions, closed_positions)
Parameters:
  • actual_positions (BackboneList) – Conformation to be closed.
  • closed_positions (BackboneList) – Closed conformation gets stored in here.
Returns:

Whether KIC found a solution
class promod3.modelling.NTerminalCloser(c_stem)

The NTerminalCloser simply takes the conformation and closes by superposing the c_stem with the desired positions.

Parameters:c_stem (ost.mol.ResidueHandle) – Defining stem positions the closed conformation should adapt.
Close(actual_positions, closed_positions)
Parameters:
  • actual_positions (BackboneList) – Conformation to be closed (or in this case transformed in space).
  • closed_positions (BackboneList) – Closed (transformed) conformation gets stored in here.
Returns:

Whether closing was successful
class promod3.modelling.CTerminalCloser(n_stem)

The CTerminalCloser simply takes the conformation and closes by superposing the n_stem with the desired positions.

Parameters:n_stem (ost.mol.ResidueHandle) – Defining stem positions the closed conformation should adapt.
Close(actual_positions, closed_positions)
Parameters:
  • actual_positions (BackboneList) – Conformation to be closed (or in this case transformed in space).
  • closed_positions (BackboneList) – Closed (transformed) conformation gets stored in here.
Returns:

Whether closing was successful
class promod3.modelling.DeNovoCloser

In case of sampling a full stretch, you dont have external constraints. The closer has a rather boring job in this case.

Close(actual_positions, closed_positions)

Does absolutely nothing, except copying over the coordinates from actual_positions to closed_positions and return true.

Scorer Object

The scorer asses a proposed conformation and are intended to return a pseudo energy, the lower the better. You can either use the provided scorer or any object implementing the functionality defined in ScorerBase.

class promod3.modelling.ScorerBase

Abstract base class defining the functions that must be implemented by any scorer.

GetScore(bb_list)

Takes coordinates and spits out a score given some internal structural environment.

Parameters:bb_list (promod3.loop.BackboneList) – Coordinates to be scored
Returns:The score
Return type:float
class promod3.modelling.LinearScorer(scorer, scorer_env, start_resnum, num_residues, chain_idx, linear_weights)

The LinearScorer allows to combine the scores available from BackboneOverallScorer in a linear manner. See CalculateLinearCombination() for a detailed description of the arguments.

Warning

The provided scorer_env will be altered in every GetScore() call. You might consider the Stash / Pop mechanism of the BackboneScoreEnv to restore to the original state once the sampling is done.

Parameters:
  • scorer (BackboneOverallScorer) – Scorer Object with set environment for the particular loop modelling problem.
  • scorer_env (BackboneScoreEnv) – The environment that is linked to the scorer
  • start_resnum (int) – Res. number defining the position in the SEQRES.
  • num_residues (int) – Number of residues to score
  • chain_idx (int) – Index of chain the loop(s) belong to.
  • linear_weights (dict (keys: str, values: float)) – Weights for each desired scorer.
Raises:

RuntimeError if linear_weights has a key for which no scorer exists
GetScore(bb_list)
Parameters:bb_list (BackboneList) – Loop to be scored.
Returns:A linear combination of the scores
Return type:float

Cooler Object

The cooler objects control the temperature of the Monte Carlo trajectory. They’re intended to deliver steadily decreasing temperatures with calls to their GetTemperature function. You can either use the provided cooler or any object implementing the functionality defined in CoolerBase.

class promod3.modelling.CoolerBase

Abstract base class defining the functions that must be implemented by any cooler.

GetTemperature()
Returns:The Temperature
Return type:float
Reset()

Resets to original state, so a new Monte Carlo trajectory can be generated

class promod3.modelling.ExponentialCooler(change_frequency, start_temperature, cooling_factor)

The exponential cooler starts with a given start_temperature and counts the calls to its GetTemperature() function. According to the change_frequency, the returned temperature gets multiplied by the cooling_factor.

Parameters:
  • change_frequency (int) – Frequency to change temperature
  • start_temperature (float) – temperature to start with
  • cooling_factor (float) – Factor to decrease temperature
GetTemperature()
Returns:current temperature
Reset()

Sets current temperature back to start_temperature and the internal counter to 0

Contents

Search

Enter search terms or a module, class or function name.

Previous topic

Fitting Loops Into Gaps

Next topic

Sidechain Reconstruction

You are here