SCHWED-679: Optimized loop closing strategy in default pipeline.

doc/tests/scripts/modelling_steps.py

@@ -19,6 +19,14 @@ modelling.CloseSmallDeletions(mhandle, scorer)
 modelling.RemoveTerminalGaps(mhandle)
 for distance in range(merge_distance):
     modelling.MergeGapsByDistance(mhandle, distance)
+    modelling.FillLoopsByDatabase(mhandle, scorer, fragment_db,
+                                  structure_db, torsion_sampler,
+                                  min_loops_required=-1,
+                                  max_res_extension=6)
+# if above fails, try DB-fill with less restrictions
+modelling.FillLoopsByDatabase(mhandle, scorer, fragment_db,
+                              structure_db, torsion_sampler,
+                              min_loops_required=-1)
 modelling.FillLoopsByDatabase(mhandle, scorer, fragment_db,
                               structure_db, torsion_sampler)
 # if above fails on some gaps, use Monte Carlo

modelling/doc/index.rst

@@ -29,8 +29,18 @@ a full protein homology modelling pipeline as follows:
 If you want to run and tweak the internal steps, you can start with the 
 following code which is equivalent to the example above:
 
+.. _modelling_steps_example:
+
 .. literalinclude:: ../../../tests/doc/scripts/modelling_steps.py
 
+In the default pipeline above, we call :func:`FillLoopsByDatabase` multiple
+times. First, we try to close "easy" gaps which require few extensions (we wish
+to limit the damage we do on the template) and for which we have plenty of loop
+candidates. If some gaps cannot be closed like this, we try less restrictive
+options. This approach is helpful if neighboring gaps are close together and the
+one closer to the C-terminus is easier to close. Several variants of the
+pipeline were evaluated on 1752 target-template-pairs and this one worked best.
+
 
 Modelling Pipeline
 --------------------------------------------------------------------------------

modelling/pymod/_pipeline.py

@@ -108,30 +108,11 @@ def BuildFromRawModel(mhandle):
     '''Build a model starting with a raw model (see :func:`BuildRawModel`).
 
     This function implements a recommended pipeline to generate complete models
-    from a raw model. If you wish to use your own pipeline, you can use the code
-    example above as a starting point for your own custom modelling pipeline.
-    For reproducibility, we recommend that you keep copies of custom pipelines.
-
-    This function will:
-
-    #. close small deletions and remove terminal gaps
-       (see :func:`CloseSmallDeletions` and :func:`RemoveTerminalGaps`)
-    #. iteratively: merge gaps of distance i and fill loops by database
-       (i from 0 to 3)
-       (see :func:`MergeGapsByDistance` and :func:`FillLoopsByDatabase`)
-    #. close remaining gaps by Monte Carlo or by closing large deletions
-       (see :func:`FillLoopsByMonteCarlo` and :func:`CloseLargeDeletions`)
-    #. build sidechains
-       (see :func:`BuildSidechains`)
-    #. minimize energy for the final model, which is then returned
-       (see :func:`MinimizeModelEnergy`)
-
-    The functions above are called with default parameters and:
-
-    - the scorer from :func:`SetupBackboneScorer`
-    - the fragment database from :func:`promod3.loop.LoadFragDB`
-    - the structural database from :func:`promod3.loop.LoadStructureDB`
-    - the torsion sampler from :func:`promod3.loop.LoadTorsionSamplerCoil`
+    from a raw model. The steps are shown in detail in the code example
+    :ref:`above <modelling_steps_example>`. If you wish to use your own
+    pipeline, you can use that code as a starting point for your own custom
+    modelling pipeline. For reproducibility, we recommend that you keep copies
+    of custom pipelines. 
 
     If the function fails to close all gaps, it will produce a warning and
     return an incomplete model.