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:
Sampler Object: Propose new conformation
Closer Object: Adapt new conformation to the environment
Scorer Object: Score the new conformation
Cooler Object: Accept/Reject new conformation based on the score and a temperature controlled Metropolis criterion
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 resultingpromod3.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:
actual_positions (
promod3.loop.BackboneList
) – Starting point, must not change when calling this function.proposed_positions (
promod3.loop.BackboneList
) – Passed by reference, so the resultingpromod3.loop.BackboneList
is assigned to this parameter.
- 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 sampledtorsion_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 changedproposed_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 sampledtorsion_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 changedproposed_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 ofFragger
objects being available. All parts not covered by any fragger remain rigid.- Parameters:
sequence (
str
) – Overall sequencefraggers (
list
) – A list ofFragger
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 ofBackboneList
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 changedproposed_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:
actual_positions (
promod3.loop.BackboneList
) – Starting point, must not change when calling this function.closed_positions (
promod3.loop.BackboneList
) – Passed by reference, so the resultingpromod3.loop.BackboneList
is assigned to this parameter.
- Returns:
Whether closing procedure was successful
- Return type:
- 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. SeeCCD()
.c_stem (
ost.mol.ResidueHandle
) – Defining stem positions the closed conformation should adapt. SeeCCD()
.sequence (
str
) – Sequence of the conformation to be closed.torsion_sampler (
TorsionSampler
/list
ofTorsionSampler
) – 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:
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.
- 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:
- 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. SeeCalculateLinearCombination()
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 theBackboneScoreEnv
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 scorerstart_resnum (
int
) – Res. number defining the position in the SEQRES.num_residues (
int
) – Number of residues to scorechain_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:
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.
- 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:
- GetTemperature()¶
- Returns:
current temperature
- Reset()¶
Sets current temperature back to start_temperature and the internal counter to 0