Generating Loops De Novo
The Monte Carlo capabilities of |project| 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:
- :ref:`mc-sampler-object`: Propose new conformation
- :ref:`mc-closer-object`: Adapt new conformation to the environment
- :ref:`mc-scorer-object`: Score the new conformation
- :ref:`mc-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 :func:`SampleMonteCarlo` function. For example, here we show how to apply Monte Carlo sampling to the N-terminal part of crambin:
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 :class:`SamplerBase`.
Abstract base class defining the functions that must be implemented by any sampler.
The PhiPsiSampler randomly draws and sets phi/psi dihedral angles from a distribution provided by the torsion_sampler.
| param sequence: | Sequence that should be sampled |
|---|---|
| param torsion_sampler: | 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. |
| param n_stem_phi: | 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. |
| param c_stem_psi: | 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. |
| param prev_aa: | 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) |
| param next_aa: | 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) |
| param seed: | Seed for the internal random number generators. |
| type sequence: | :class:`str` |
| type torsion_sampler: | :class:`~promod3.loop.TorsionSampler` |
| type n_stem_phi: | :class:`float` |
| type c_stem_psi: | :class:`float` |
| type prev_aa: | :class:`str` |
| type next_aa: | :class:`str` |
| type seed: | :class:`int` |
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.
| param sequence: | Sequence that should be sampled |
|---|---|
| param torsion_sampler: | 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. |
| param max_dev: | Maximal deviation of dihedral angle from its original value per sampling step. |
| param n_stem_phi: | 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. |
| param c_stem_psi: | 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. |
| param prev_aa: | 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) |
| param next_aa: | 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) |
| param seed: | Seed for the internal random number generators. |
| type sequence: | :class:`str` |
| type torsion_sampler: | :class:`~promod3.loop.TorsionSampler` |
| type n_stem_phi: | :class:`float` |
| type c_stem_psi: | :class:`float` |
| type prev_aa: | :class:`str` |
| type next_aa: | :class:`str` |
| type seed: | :class:`int` |
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 :class:`CloserBase`.
Abstract base class defining the functions that must be implemented by any closer.
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.
| param n_stem: | Defining stem positions the closed conformation should adapt. See :meth:`~CCD.CCD()`. |
|---|---|
| param c_stem: | Defining stem positions the closed conformation should adapt. See :meth:`~CCD.CCD()`. |
| param sequence: | Sequence of the conformation to be closed. |
| param torsion_sampler: | 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. |
| param seed: | Seed for internal random generators. |
| type n_stem: | :class:`ost.mol.ResidueHandle` |
| type c_stem: | :class:`ost.mol.ResidueHandle` |
| type sequence: | :class:`str` |
| type torsion_sampler: | :class:`~promod3.loop.TorsionSampler` / :class:`list` of :class:`~promod3.loop.TorsionSampler` |
| type seed: | :class:`int` |
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 :class:`CCDCloser`.
| param n_stem: | Defining stem positions the closed conformation should adapt. |
|---|---|
| param c_stem: | Defining stem positions the closed conformation should adapt. |
| type n_stem: | :class:`ost.mol.ResidueHandle` |
| type c_stem: | :class:`ost.mol.ResidueHandle` |
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.
| param n_stem: | Defining stem positions the closed conformation should adapt. |
|---|---|
| param c_stem: | Defining stem positions the closed conformation should adapt. |
| param seed: | Seed for internal random generators. |
| type n_stem: | :class:`ost.mol.ResidueHandle` |
| type c_stem: | :class:`ost.mol.ResidueHandle` |
| type seed: | :class:`int` |
The :class:`NTerminalCloser` simply takes the conformation and closes by superposing the c_stem with the desired positions.
| param c_stem: | Defining stem positions the closed conformation should adapt. |
|---|---|
| type c_stem: | :class:`ost.mol.ResidueHandle` |
The :class:`CTerminalCloser` simply takes the conformation and closes by superposing the n_stem with the desired positions.
| param n_stem: | Defining stem positions the closed conformation should adapt. |
|---|---|
| type n_stem: | :class:`ost.mol.ResidueHandle` |
In case of sampling a full stretch, you dont have external constraints. The closer has a rather boring job in this case.
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 :class:`ScorerBase`.
Abstract base class defining the functions that must be implemented by any scorer.
The LinearScorer allows to combine the scores available from :class:`~promod3.scoring.BackboneOverallScorer` in a linear manner. See :meth:`~promod3.scoring.BackboneOverallScorer.CalculateLinearCombination` for a detailed description of the arguments.
Warning
The provided scorer_env will be altered in every :func:`GetScore` call. You might consider the Stash / Pop mechanism of the :class:`~promod3.scoring.BackboneScoreEnv` to restore to the original state once the sampling is done.
| param scorer: | Scorer Object with set environment for the particular loop modelling problem. |
|---|---|
| type scorer: | :class:`~promod3.scoring.BackboneOverallScorer` |
| param scorer_env: | The environment that is linked to the scorer |
| type scorer_env: | :class:`~promod3.scoring.BackboneScoreEnv` |
| param start_resnum: | Res. number defining the position in the SEQRES. |
| type start_resnum: | :class:`int` |
| param num_residues: | Number of residues to score |
| type num_residues: | :class:`int` |
| param chain_idx: | Index of chain the loop(s) belong to. |
| type chain_idx: | :class:`int` |
| param linear_weights: | Weights for each desired scorer. |
| type linear_weights: | :class:`dict` (keys: :class:`str`, values: :class:`float`) |
| raises: | :exc:`~exceptions.RuntimeError` if linear_weights has a key for which no scorer exists |
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 :class:`CoolerBase`.
Abstract base class defining the functions that must be implemented by any cooler.
The exponential cooler starts with a given start_temperature and counts the calls to its :meth:`GetTemperature` function. According to the change_frequency, the returned temperature gets multiplied by the cooling_factor.
| param change_frequency: | Frequency to change temperature |
|---|---|
| param start_temperature: | temperature to start with |
| param cooling_factor: | Factor to decrease temperature |
| type change_frequency: | :class:`int` |
| type start_temperature: | :class:`float` |
| type cooling_factor: | :class:`float` |