You are reading the documentation for version 3.1 of ProMod3.
You may also want to read the documentation for:
3.0
1.3
2.0
2.1
Generating Loops De Novo
The Monte Carlo capabilities of ProMod3 are mainly targeted at generating de
novo structure candidates for loops or N/CTermini. 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 Nterminal 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_len1])
# 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 nterminus
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.

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.

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 .

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.

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
