From cafcf25a37b350551779f2ff74ffd6c4e293c1db Mon Sep 17 00:00:00 2001
From: Gerardo Tauriello <gerardo.tauriello@unibas.ch>
Date: Fri, 30 Sep 2016 11:25:42 +0200
Subject: [PATCH] SCHWED-1421: Added documentation for SidechainReconstructor.
---
doc/tests/CMakeLists.txt | 1 +
doc/tests/scripts/sidechain_reconstruct.py | 4 +-
doc/tests/scripts/sidechain_reconstructor.py | 20 +++
doc/tests/scripts/sidechain_steps.py | 2 +-
doc/tests/test_doctests.py | 8 +
modelling/doc/monte_carlo.rst | 6 +-
sidechain/doc/CMakeLists.txt | 1 +
sidechain/doc/graph.rst | 5 +-
sidechain/doc/index.rst | 46 +++--
sidechain/doc/loading.rst | 2 +-
sidechain/doc/reconstruct.rst | 167 +++++++++++++++++++
sidechain/pymod/_reconstruct_sidechains.py | 4 +-
12 files changed, 227 insertions(+), 39 deletions(-)
create mode 100644 doc/tests/scripts/sidechain_reconstructor.py
create mode 100644 sidechain/doc/reconstruct.rst
diff --git a/doc/tests/CMakeLists.txt b/doc/tests/CMakeLists.txt
index df61bbb8..db07dd88 100644
--- a/doc/tests/CMakeLists.txt
+++ b/doc/tests/CMakeLists.txt
@@ -47,6 +47,7 @@ set (DOC_TEST_SCRIPTS
scripts/modelling_loop_candidates.py
scripts/sidechain_reconstruct.py
+ scripts/sidechain_reconstructor.py
scripts/sidechain_steps.py
)
diff --git a/doc/tests/scripts/sidechain_reconstruct.py b/doc/tests/scripts/sidechain_reconstruct.py
index e08c6dde..f1e12512 100644
--- a/doc/tests/scripts/sidechain_reconstruct.py
+++ b/doc/tests/scripts/sidechain_reconstruct.py
@@ -2,10 +2,10 @@ from ost import io, mol
from promod3 import sidechain
# load a protein
-prot = io.LoadPDB('data/1eye.pdb')
+prot = io.LoadPDB('data/1CRN.pdb')
# get only amino acids
prot = mol.CreateEntityFromView(prot.Select("peptide=true"), True)
io.SavePDB(prot, 'sidechain_test_orig.pdb')
# reconstruct sidechains
-sidechain.Reconstruct(prot)
+sidechain.Reconstruct(prot, keep_sidechains=False)
io.SavePDB(prot, 'sidechain_test_rec.pdb')
diff --git a/doc/tests/scripts/sidechain_reconstructor.py b/doc/tests/scripts/sidechain_reconstructor.py
new file mode 100644
index 00000000..254d7656
--- /dev/null
+++ b/doc/tests/scripts/sidechain_reconstructor.py
@@ -0,0 +1,20 @@
+from ost import io
+from promod3 import sidechain, 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 = sidechain.SidechainReconstructor(keep_sidechains=False)
+sc_rec.AttachEnvironment(env)
+
+# reconstruct subset (res. num. 6..10)
+res = sc_rec.Reconstruct(6, 5)
+# update environment with solution
+env.SetEnvironment(res.env_pos)
+# store all positions of environment
+io.SavePDB(env.GetAllAtomPositions().ToEntity(), 'sc_rec_test.pdb')
diff --git a/doc/tests/scripts/sidechain_steps.py b/doc/tests/scripts/sidechain_steps.py
index ca6d2c5c..c2f5a4f4 100644
--- a/doc/tests/scripts/sidechain_steps.py
+++ b/doc/tests/scripts/sidechain_steps.py
@@ -2,7 +2,7 @@ from ost import io,mol
from promod3 import sidechain
# load a protein
-prot = io.LoadPDB('data/1eye.pdb')
+prot = io.LoadPDB('data/1CRN.pdb')
# load rotamer library and settings with default values
settings = sidechain.RotamerSettings()
library = sidechain.LoadDunbrackLib()
diff --git a/doc/tests/test_doctests.py b/doc/tests/test_doctests.py
index 201aee01..e06f3f48 100644
--- a/doc/tests/test_doctests.py
+++ b/doc/tests/test_doctests.py
@@ -363,6 +363,14 @@ class DocTests(unittest.TestCase):
os.remove('sidechain_test_orig.pdb')
os.remove('sidechain_test_rec.pdb')
+ def testSidechainReconstructor(self):
+ # run it
+ self.checkPMRun('sidechain_reconstructor.py', [], 0)
+ # check that result exists and is readable
+ io.LoadPDB('sc_rec_test.pdb')
+ # clean up
+ os.remove('sc_rec_test.pdb')
+
def testSidechainSteps(self):
# run it
self.checkPMRun('sidechain_steps.py', [], 0)
diff --git a/modelling/doc/monte_carlo.rst b/modelling/doc/monte_carlo.rst
index a7a37b91..dbb394d6 100644
--- a/modelling/doc/monte_carlo.rst
+++ b/modelling/doc/monte_carlo.rst
@@ -22,8 +22,8 @@ Carlo sampling to the N-terminal part of crambin:
.. literalinclude:: ../../../tests/doc/scripts/modelling_monte_carlo.py
.. method:: SampleMonteCarlo(sampler, closer, scorer, cooler, steps,\
- bb_list, initialize=true, seed=0,\
- lowest_energy_conformation=true)
+ bb_list, initialize=True, 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
@@ -47,7 +47,7 @@ Carlo sampling to the N-terminal part of crambin:
point, based on the samplers Initialize function.
The input *bb_list* gets used otherwise.
:param seed: Seed for internal random number generator.
- :param lowest_energy_conformation: If true, we choose the lowest scoring
+ :param lowest_energy_conformation: If True, we choose the lowest scoring
conformation of the trajectory. Otherwise,
the last accepted proposal.
diff --git a/sidechain/doc/CMakeLists.txt b/sidechain/doc/CMakeLists.txt
index 75e2722a..451e2307 100644
--- a/sidechain/doc/CMakeLists.txt
+++ b/sidechain/doc/CMakeLists.txt
@@ -1,5 +1,6 @@
set(SIDECHAIN_RST
index.rst
+reconstruct.rst
rotamer.rst
rotamer_id.rst
frame.rst
diff --git a/sidechain/doc/graph.rst b/sidechain/doc/graph.rst
index 3f37634a..965355b4 100644
--- a/sidechain/doc/graph.rst
+++ b/sidechain/doc/graph.rst
@@ -1,4 +1,4 @@
-Coming to a solution
+Rotamer Graph
================================================================================
.. currentmodule:: promod3.sidechain
@@ -12,9 +12,6 @@ decomposition and dead end elimination, decomposes the graph in a tree form
and finally comes back with a solution.
-The Rotamer Graph
---------------------------------------------------------------------------------
-
.. class:: RotamerGraph
The Graph object has no constructor exported to python. It is meant to be
diff --git a/sidechain/doc/index.rst b/sidechain/doc/index.rst
index e8528c16..62cc9b2d 100644
--- a/sidechain/doc/index.rst
+++ b/sidechain/doc/index.rst
@@ -6,32 +6,27 @@
.. currentmodule:: promod3.sidechain
-Tools and algorithms to model sidechains given backbone coordinates.
-The full module is heavily based on SCWRL4 [krivov2009]_ .
-The according paper describes the modelling of sidechains using two different
-rotamer models. A rigid model, as well as a flexible model. Both models are
-implemented in PROMOD3 and can be applied in flexible ways.
-
-Reconstruct Function
---------------------------------------------------------------------------------
+Tools and algorithms to model sidechains given backbone coordinates. The full
+module is heavily based on SCWRL4 [krivov2009]_ . The according paper describes
+the modelling of sidechains using two different rotamer models. A rigid model,
+as well as a flexible model. Both models are implemented in PROMOD3 and can be
+applied in flexible ways.
The simplest usage of the module is provided by the :func:`Reconstruct`
function:
.. literalinclude:: ../../../tests/doc/scripts/sidechain_reconstruct.py
-.. autofunction:: Reconstruct
-
+For use during loop modelling, the :class:`SidechainReconstructor` can be used:
-Sidechain Module Functionality
---------------------------------------------------------------------------------
+.. literalinclude:: ../../../tests/doc/scripts/sidechain_reconstructor.py
The following code fragment shows an example of a basic sidechain reconstruction
-algorithm using the functionality in the module. Note, that this code will
-crash as soon as you have structures containing all the weirdness the PDB throws
-at us. In this case, you should use the :func:`~promod3.sidechain.Reconstruct`
-function above. An overview of the full provided functionality can be found at
-the bottom of this page.
+algorithm using the functionality in the module. Note, that this code will crash
+as soon as you have structures containing all the weirdness the PDB throws at
+us. In this case, you should use the :func:`Reconstruct` function above. An
+overview of the full provided functionality can be found at the bottom of this
+page.
.. literalinclude:: ../../../tests/doc/scripts/sidechain_steps.py
@@ -40,11 +35,12 @@ Contents:
.. toctree::
:maxdepth: 2
- RotamerID <rotamer_id>
- Rotamers <rotamer>
- Frame <frame>
- Rotamer Library <rotamer_lib>
- RotamerGraph <graph>
- The Settings - Control Things... <sidechain_settings>
- Disulfid Bond Evaluation <disulfid>
- Loading Libraries <loading>
+ reconstruct
+ rotamer_id
+ rotamer
+ frame
+ rotamer_lib
+ graph
+ sidechain_settings
+ disulfid
+ loading
diff --git a/sidechain/doc/loading.rst b/sidechain/doc/loading.rst
index 82ad5bf2..8f147190 100644
--- a/sidechain/doc/loading.rst
+++ b/sidechain/doc/loading.rst
@@ -1,4 +1,4 @@
-Load Rotamer Libraries
+Loading Rotamer Libraries
================================================================================
.. currentmodule:: promod3.sidechain
diff --git a/sidechain/doc/reconstruct.rst b/sidechain/doc/reconstruct.rst
new file mode 100644
index 00000000..e461b3cf
--- /dev/null
+++ b/sidechain/doc/reconstruct.rst
@@ -0,0 +1,167 @@
+Sidechain Reconstruction
+================================================================================
+
+.. currentmodule:: promod3.sidechain
+
+Two methods are provided to fully reconstruct sidechains of residues:
+
+- the :func:`Reconstruct` function handles a full OST
+ :class:`~ost.mol.EntityHandle`
+- the :class:`SidechainReconstructor` is linked to an all atom environment
+ and used to reconstruct sidechains of single loops
+
+Reconstruct Function
+--------------------------------------------------------------------------------
+
+.. autofunction:: Reconstruct
+
+
+SidechainReconstructor Class
+--------------------------------------------------------------------------------
+
+.. class:: SidechainReconstructor(keep_sidechains=True, build_disulfids=True, \
+ cutoff=20, graph_max_complexity=100000000, \
+ graph_intial_epsilon=0.02, \
+ disulfid_max_distance=8, \
+ disulfid_score_thresh=45)
+
+ Reconstruct sidechains for single loops. Must be linked to an all atom env.
+ (:meth:`AttachEnvironment`) containing the structural data.
+
+ :param keep_sidechains: Flag, whether complete sidechains in env. (i.e.
+ containing all required atoms) should be kept rigid
+ and directly be added to the result.
+ :type keep_sidechains: :class:`bool`
+
+ :param build_disulfids: Flag, whether possible disulfid bonds should be
+ searched. If a disulfid bond is found, the two
+ participating cysteins are fixed and added to
+ the result.
+ :type build_disulfids: :class:`bool`
+
+ :param cutoff: Cutoff used to search relevant residues surrounding the loop.
+ :type cutoff: :class:`float`
+
+ :param graph_max_complexity: Max. complexity for
+ :meth:`RotamerGraph.TreeSolve`.
+ :type graph_max_complexity: :class:`int`
+ :param graph_intial_epsilon: Initial epsilon for
+ :meth:`RotamerGraph.TreeSolve`.
+ :type graph_intial_epsilon: :class:`float`
+
+ :param disulfid_max_distance: Max. distance for 2 CYS-CA atoms to be
+ considered close enough to check for bridges.
+ :type disulfid_max_distance: :class:`float`
+ :param disulfid_score_thresh: If :meth:`DisulfidScore` between two CYS is
+ below this threshold, we consider them to be
+ disulfid-bonded.
+ :type disulfid_score_thresh: :class:`float`
+
+
+ .. method:: Reconstruct(start_resnum, num_residues, chain_idx=0)
+
+ Reconstruct sidechains for desired loop (extracted from environment). All
+ residues in the loop are expected to contain valid CB positions (or CA for
+ GLY), which are used to look for other potentially relevant residues
+ surrounding the loop. The resulting structural data will contain all
+ residues in the loop and in the surrounding. Sidechains are added for all
+ residues in the loop and for surrounding residues if they are relevant for
+ the loop sidechains.
+
+ Note that the structural data of the loop is expected to be in the linked
+ environment before calling this!
+
+ :param start_resnum: Start of loop.
+ :type start_resnum: :class:`int` / :class:`ost.mol.ResNum`
+ :param num_residues: Length of loop.
+ :type num_residues: :class:`int`
+ :param chain_idx: Chain the loop belongs to.
+ :type chain_idx: :class:`int`
+
+ :raises: :exc:`~exceptions.RuntimeError` if reconstructor was never attached
+ to an environment or if parameters lead to invalid / unset
+ positions in environment.
+
+ .. method:: AttachEnvironment(env, use_frm=True, use_bbdep_lib=True, \
+ consider_hbonds=True)
+ AttachEnvironment(env, use_frm, rotamer_library, \
+ consider_hbonds=True)
+
+ Link reconstructor to given *env*. A helper class is used in the background
+ to provide sidechain-objects for the environment. As this class is reused by
+ every reconstructor linked to *env*, the used parameters must be consistent
+ if multiple reconstructors are used (or you must use a distinct *env*).
+
+ :param env: Link to this environment.
+ :type env: :class:`~promod3.loop.AllAtomEnv`
+ :param use_frm: If True, use flexible rotamer model, else rigid.
+ :type use_frm: :class:`bool`
+ :param use_bbdep_lib: If True, use default backbone dependent rot. library
+ (:meth:`Dunbrack <LoadDunbrackLib>`), else use
+ backbone independent one
+ (:meth:`Penultimate <LoadPenultimateLib>`).
+ :type use_bbdep_lib: :class:`bool`
+ :param rotamer_library: Custom rotamer library to be used.
+ :type rotamer_library: :class:`BBDepRotamerLib` / :class:`RotamerLib`
+ :param consider_hbonds: Flag, whether hbonds should be evaluated in the
+ energy function. If set to False, no hydrogens will
+ be built when building rotamers and frames.
+ :type consider_hbonds: :class:`bool`
+
+ :return: :class:`SidechainReconstructionData`
+
+ :raises: :exc:`~exceptions.RuntimeError` if *env* was already linked to
+ another reconstructor with inconsistent parameters. Acceptable
+ changes:
+
+ - *keep_sidechains* = True, if previously False
+ - *build_disulfids* = False, if previously True
+
+The AllAtomEnvPositions class
+--------------------------------------------------------------------------------
+
+.. class:: SidechainReconstructionData
+
+ Contains the results of a sidechain reconstruction
+ (:meth:`SidechainReconstructor.Reconstruct`). All attributes are read only!
+
+ .. attribute:: env_pos
+
+ Container for structural data and mapping to the internal residue indices
+ of the used :class:`~promod3.loop.AllAtomEnv`. Useful for scoring and env.
+ updates.
+
+ :type: :class:`~promod3.loop.AllAtomEnvPositions`
+
+ .. attribute:: loop_length
+
+ Length of the loop used to generate this result. The first *loop_length*
+ residues in *env_pos* are guaranteed to belong to the loop.
+
+ :type: :class:`int`
+
+ .. attribute:: rotamer_res_indices
+
+ Indices of residues within *env_pos* for which we generated a new sidechain
+ (in [*0, len(env_pos.res_indices)-1*]).
+
+ :type: :class:`list` of :class:`int`
+
+ .. attribute:: disulfid_res_indices
+
+ Indices of residues within *env_pos* for which we generated a disulfid
+ bridge (in [*0, len(env_pos.res_indices)-1*]).
+
+ :type: :class:`list` of :class:`int`
+
+ .. attribute:: n_stem_idx
+
+ Residue index of N stem (= *env_pos.res_indices[0]*).
+
+ :type: :class:`int`
+
+ .. attribute:: c_stem_idx
+
+ Residue index of C stem (= *env_pos.res_indices[loop_length-1]*).
+
+ :type: :class:`int`
diff --git a/sidechain/pymod/_reconstruct_sidechains.py b/sidechain/pymod/_reconstruct_sidechains.py
index 9fcf0c45..2bbbfd4f 100644
--- a/sidechain/pymod/_reconstruct_sidechains.py
+++ b/sidechain/pymod/_reconstruct_sidechains.py
@@ -400,9 +400,7 @@ def Reconstruct(ent, keep_sidechains=False, build_disulfids=True,
:param consider_hbonds: Flag, whether hbonds should be evaluated in the
energy function. If set to False, no hydrogens will
- be built when building rotamers and frame and the
- **add_polar_hydrogens** flag won't have any
- consequences.
+ be built when building rotamers and frame.
:param consider_ligands: Flag, whether to add ligands (anything in chain
'_') as static objects.
--
GitLab