SCHWED-1740: doc update for SidechainReconstructor/AllAtomRelaxer

doc/tests/CMakeLists.txt

@@ -49,6 +49,7 @@ set (DOC_TEST_SCRIPTS
   scripts/modelling_loop_scoring.py
   scripts/modelling_reconstruct_sidechains.py
   scripts/modelling_sidechain_reconstructor.py
+  scripts/modelling_allatomrelaxer.py
 
   scripts/sidechain_steps.py
 )

doc/tests/scripts/modelling_allatomrelaxer.py

+from ost import io
+from promod3 import modelling, 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 = modelling.SidechainReconstructor()
+sc_rec.AttachEnvironment(env)
+
+# "reconstruct" subset (res. num. 6..10) -> sidechains kept here
+sc_result = sc_rec.Reconstruct(6, 5)
+# setup sys creator
+ff_lookup = loop.ForcefieldLookup.GetDefault()
+mm_sys = loop.MmSystemCreator(ff_lookup)
+relaxer = modelling.AllAtomRelaxer(sc_result, mm_sys)
+# relax loop
+pot_e = relaxer.Run(sc_result, 300, 0.1)
+print "Potential energy after: %g" % pot_e
+# update environment with solution
+env.SetEnvironment(sc_result.env_pos)
+# store all positions of environment
+io.SavePDB(env.GetAllAtomPositions().ToEntity(), 'aa_relax_test.pdb')

doc/tests/scripts/modelling_sidechain_reconstructor.py

@@ -14,6 +14,10 @@ sc_rec.AttachEnvironment(env)
 
 # reconstruct subset (res. num. 6..10)
 res = sc_rec.Reconstruct(6, 5)
+# reconstruct two loops (6..10 and 20..25)
+res = sc_rec.Reconstruct(start_resnum_list=[6, 20],
+                         num_residues_list=[5, 6],
+                         chain_idx_list=[0, 0])
 # update environment with solution
 env.SetEnvironment(res.env_pos)
 # store all positions of environment

doc/tests/test_doctests.py

@@ -385,6 +385,14 @@ class DocTests(unittest.TestCase):
         # clean up
         os.remove('sc_rec_test.pdb')
 
+    def testModellingAllAtomRelaxer(self):
+        # run it
+        self.checkPMRun('modelling_allatomrelaxer.py', [], 0)
+        # check that result exists and is readable
+        io.LoadPDB('aa_relax_test.pdb')
+        # clean up
+        os.remove('aa_relax_test.pdb')
+
     ################################################################
 
     def testSidechainSteps(self):

modelling/doc/loop_closing.rst

@@ -313,6 +313,10 @@ After the reconstruction of loop sidechains with the
 :class:`~promod3.modelling.SidechainReconstructor`, it may be desired to
 quickly relax the loop. The :class:`AllAtomRelaxer` class takes care of that.
 
+Example usage:
+
+.. literalinclude:: ../../../tests/doc/scripts/modelling_allatomrelaxer.py
+
 .. class:: AllAtomRelaxer(sc_data, mm_system_creator)
 
   Setup relaxer for a given sidechain reconstruction result and a given MM

modelling/doc/sidechain_reconstruction.rst

@@ -61,7 +61,8 @@ SidechainReconstructor Class
                           the result.
   :type build_disulfids: :class:`bool`
 
-  :param optimize_subrotamers: Flag, whether the :func:`SubrotamerOptimizer`
+  :param optimize_subrotamers: Flag, whether the
+                               :func:`~promod3.sidechain.SubrotamerOptimizer`
                                with default parametrization should be called 
                                if we're dealing with FRM rotamers.
   :type optimize_subrotamers:  :class:`bool`
@@ -98,12 +99,13 @@ SidechainReconstructor Class
   .. method:: Reconstruct(start_resnum, num_residues, chain_idx=0)
               Reconstruct(start_resnum_list, num_residues_list, chain_idx_list)
 
-    Reconstruct sidechains for one or several loops (extracted from environment). 
-    All residues in the loop(s) are expected to contain valid CB positions 
-    (or CA for GLY), which are used to look for other potentially relevant 
-    residues in the surrounding. The resulting structural data will contain all
-    residues in the loop(s) and in the surrounding with all backbone and 
-    sidechain heavy atom positions set.
+    Reconstruct sidechains for one or several loops extracted from environment.
+    Overlapping loops are merged and 0-length loops are removed. All residues in
+    the loop(s) are expected to contain valid CB positions (or CA for GLY),
+    which are used to look for other potentially relevant residues in the
+    surrounding. The resulting structural data will contain all residues in the
+    loop(s) and in the surrounding with all backbone and sidechain heavy atom
+    positions set.
 
     Note that the structural data of the loop(s) is expected to be in the linked
     environment before calling this!
@@ -115,9 +117,9 @@ SidechainReconstructor Class
     :param chain_idx: Chain the loop belongs to.
     :type chain_idx:  :class:`int`
     
-    :param start_resnum_list: Start of loops.
+    :param start_resnum_list: Starts of loops.
     :type start_resnum_list:  :class:`list` of :class:`int`
-    :param num_residues_list: Length of loops.
+    :param num_residues_list: Lengths of loops.
     :type num_residues_list:  :class:`list` of :class:`int`
     :param chain_idx_list: Chains the loops belong to.
     :type chain_idx_list:  :class:`list` of :class:`int`
@@ -172,13 +174,22 @@ The SidechainReconstructionData class
 
     :type: :class:`~promod3.loop.AllAtomEnvPositions`
 
-  .. attribute:: length
+  .. attribute:: loop_start_indices
+                 loop_lengths
 
-    Length of the residues used to generate this result. The first *length*
-    residues in *env_pos* are guaranteed to belong to the actual input, all the
-    rest comes from the close environment.
+    The first *sum(loop_lengths)* residues in
+    :attr:`~promod3.loop.AllAtomEnvPositions.res_indices` of *env_pos* are
+    guaranteed to belong to the actual input, all the rest comes from the close
+    environment.
 
-    :type: :class:`int`
+    Each input loop (apart from overlapping and 0-length loops) is defined by an
+    entry in *loop_start_indices* and *loop_lengths*. For loop *i_loop*,
+    *res_indices[loop_start_indices[i_loop]]* is the N-stem and
+    *res_indices[loop_start_indices[i_loop] + loop_lengths[i_loop] - 1]* is the
+    C-stem of the loop. The loop indices are contiguous in *res_indices* between
+    the stems.
+
+    :type: :class:`list` of :class:`int`
 
   .. attribute:: rotamer_res_indices