Documented latest LoopCandidates extensions.

loop/doc/structure_db.rst

@@ -142,7 +142,7 @@ database, you might want to consider two things:
     :param pdb_id:      4-letter code of the structure the chain belongs to
     :param chain_name:  Name of the chain consisting of one letter
     :param chain:       The actual chain 
-    :param surf:        A surface describint the solvent accessible surface
+    :param surf:        A surface describing the solvent accessible surface
     :param prof:        Profile information for this structure.
 
     :type pdb_id:       :class:`str`

modelling/doc/loop_candidates.rst

@@ -29,7 +29,11 @@ The LoopCandidates class
   .. staticmethod:: FillFromDatabase(n_stem, c_stem, seq, frag_db, \
                                      structural_db, extended_search=False)
     
-    Searches for loop candidates matching the length (number of residues in *seq*) and geometry (of *n_stem* and *c_stem*) of the loop to be modelled in a fragment database.
+    Searches for loop candidates matching the length (number of residues in
+    *seq*) and geometry (of *n_stem* and *c_stem*) of the loop to be modelled in
+    a fragment database.
+
+    This call also adds fragment infos (:meth:`HasFragmentInfos` will be True).
 
     :param n_stem:         The residue at the N-terminal end of the loop 
     :param c_stem:         The residue at the C-terminal end of the loop 
@@ -51,6 +55,9 @@ The LoopCandidates class
     :returns:              A list of loop candidates
     :rtype:                :class:`LoopCandidates`
 
+    :raises: :exc:`~exceptions.RuntimeError` if stems do no contain N, CA and C
+             atoms.
+
   .. staticmethod:: FillFromMonteCarloSampler(seq, num_loops, steps, \
                                               sampler, closer, scorer, cooler, \
                                               random_seed=0)
@@ -88,30 +95,12 @@ The LoopCandidates class
     :returns:          The resulting candidates
     :rtype:            :class:`LoopCandidates`
 
-    :raises: A :exc:`RuntimeError`, if *initial_bb* is not given and the Monte
-             Carlo sampler failed to initialize (i.e. stems are too far apart)
-    :raises: A :exc:`RuntimeError`, if *initial_bb* is given and it is
-             inconsistent with *seq*
-
-  .. method:: GetClusteredCandidates(max_dist, neglect_size_one=True)
-
-    Clusters the loop candidates according to their pairwise CARMSD using a
-    greedy hierarchical clustering algorithm. Every candidate gets assigned a
-    unique cluster. At every clustering step, the two clusters with shortest
-    distance get merged, with the distance definition being the maximal CARMSD
-    between any of the members of the two clusters.
-
-    :param max_dist:    Maximal distance two clusters can have to be merged
-    :param neglect_size_one: Whether clusters should be added to the returned
-                             list if they only contain one loop candidate
-
-    :type max_dist:     :class:`float`
-    :type neglect_size_one: :class:`bool`
+    :raises: :exc:`~exceptions.RuntimeError`, if *initial_bb* is not given and
+             the Monte Carlo sampler failed to initialize (i.e. stems are too
+             far apart) or if *initial_bb* is given and it is inconsistent with
+             *seq*.
 
 
-    :returns:   A list of :class:`LoopCandidates`. Each element in the list
-                corresponds to the candidates in one cluster.
-
   .. method:: ApplyCCD(n_stem, c_stem, max_iterations=1000, \
                        rmsd_cutoff=0.1, keep_non_converged=false, random_seed=0)
               ApplyCCD(n_stem, c_stem, torsion_sampler, max_iterations=1000, \
@@ -151,6 +140,11 @@ The LoopCandidates class
     :type keep_non_converged: :class:`bool`
     :type random_seed:        :class:`int`
 
+    :return: An index for each kept candidate corresponding to the candidate
+             index before this function was called. This is useful to keep track
+             of scores and other data extracted before.
+    :rtype:  :class:`list` of :class:`int`
+
 
   .. method:: ApplyKIC(n_stem, c_stem, pivot_one, pivot_two, pivot_three)
 
@@ -176,21 +170,11 @@ The LoopCandidates class
     :type pivot_two:    :class:`int`
     :type pivot_three:  :class:`int`
 
-
-  .. method:: Add(bb_list)
-
-    :param bb_list: The loop candidate to be added.
-    :type bb_list:  :class:`~promod3.loop.BackboneList`
-
-    :raises: :exc:`~exceptions.RuntimeError` If sequence of *bb_list* is not
-             consistent with internal sequence
- 
-  .. method:: Remove(index)
-
-    Remove a loop candidate from the list of candidates.
-
-    :param index: The index of the candidate that will be removed
-    :type index:  :class:`int`
+    :return: An index for each added candidate corresponding to the original
+             candidate index before this function was called (each candidate can
+             lead to multiple or no candidates after KIC is applied). This is
+             useful to keep track of scores and other data extracted before.
+    :rtype:  :class:`list` of :class:`int`
     
 
   .. method:: CalculateScores(scorer, key, start_resnum, chain_idx=0)
@@ -199,7 +183,7 @@ The LoopCandidates class
     See :meth:`~promod3.scoring.BackboneOverallScorer.Calculate` for a
     detailed description of the arguments and possible exceptions.
 
-    :param scorer: Scorer Object with set environment for the particular loop
+    :param scorer: Scorer object with set environment for the particular loop
                    modelling problem.
     :type scorer:  :class:`~promod3.scoring.BackboneOverallScorer`
     :param key: Key for desired scorer.
@@ -213,7 +197,6 @@ The LoopCandidates class
              The returned scores are in the same order as this container.
     :rtype:  :class:`list` of :class:`float`
 
-
   .. method:: CalculateLinearScores(scorer, linear_weights, start_resnum, \
                                     chain_idx=0)
 
@@ -222,7 +205,7 @@ The LoopCandidates class
     :meth:`~promod3.scoring.BackboneOverallScorer.CalculateLinearCombination`
     for a detailed description of the arguments and possible exceptions.
 
-    :param scorer: Scorer Object with set environment for the particular loop
+    :param scorer: Scorer object with set environment for the particular loop
                    modelling problem.
     :type scorer:  :class:`~promod3.scoring.BackboneOverallScorer`
     :param linear_weights: Weights for each desired scorer.
@@ -237,3 +220,133 @@ The LoopCandidates class
              scorers for all loops. The returned scores are in the same order
              as this container.
     :rtype:  :class:`list` of :class:`float`
+
+
+  .. method:: CalculateSequenceProfileScores(structure_db, prof, offset=0)
+              CalculateStructureProfileScores(structure_db, prof, offset=0)
+
+    Calculates a score comparing the given profile *prof* starting at *offset*
+    with the sequence / structure profile of each candidate as extracted from
+    *structure_db* (see :meth:`ost.seq.ProfileHandle.GetAverageScore` for
+    details, *prof.null_model* is used for weighting).
+
+    This requires that each candidate has a connected fragment info into the
+    given *structure_db* (e.g. :meth:`FillFromDatabase` must have been called
+    with this DB).
+
+    :param structural_db: Structural database used in :meth:`FillFromDatabase`
+    :type structural_db:  :class:`~promod3.loop.StructureDB`
+    :param prof: Profile information for target.
+    :type prof:  :class:`ost.seq.ProfileHandle`
+    :param offset: Loop starts at index *offset* in *prof*.
+    :type offset:  :class:`int`
+
+    :return: Profile score for each candidate. The returned scores are in the
+             same order as this container.
+    :rtype:  :class:`list` of :class:`float`
+
+    :raises: :exc:`~exceptions.RuntimeError` if :meth:`HasFragmentInfos` is
+             False, if *structure_db* is incompatible with the stored fragment
+             infos or if *prof* has less than *offset+len* elements (len =
+             length of loops stored in here).
+
+
+  .. method:: CalculateStemRMSDs(n_stem, c_stem)
+
+    Calculates RMSD between the given stems and the first and last residue of
+    the loop candidates. This first superposes the first loop residue with
+    *n_stem* and then computes the RMSD between the last residue's N, CA, C
+    positions and the corresponding atoms in *c_stem*.
+
+    Note that this score is only useful before calling :meth:`ApplyCCD` or
+    :meth:`ApplyKIC`.
+
+    :param n_stem: The residue at the N-terminal end of the loop.
+    :type n_stem:  :class:`ost.mol.ResidueHandle`
+    :param c_stem: The residue at the C-terminal end of the loop.
+    :type c_stem:  :class:`ost.mol.ResidueHandle`
+
+    :return: Stem RMSD for each candidate. The returned scores are in the same
+             order as this container.
+    :rtype:  :class:`list` of :class:`float`
+
+    :raises: :exc:`~exceptions.RuntimeError` if stems do no contain N, CA and C
+             atoms.
+
+
+  .. method:: Add(bb_list)
+
+    :param bb_list: The loop candidate to be added.
+    :type bb_list:  :class:`~promod3.loop.BackboneList`
+
+    :raises: :exc:`~exceptions.RuntimeError` if sequence of *bb_list* is not
+             consistent with internal sequence
+ 
+  .. method:: AddFragmentInfo(fragment)
+
+    Adds a fragment info for the last candidate added with :meth:`Add`. Note
+    that these infos are added automatically with :meth:`FillFromDatabase` and
+    updated whenever the candidates are copied, removed, clustered etc.. So you
+    will probably never need this function.
+
+    :param fragment: The fragment info to add.
+    :type fragment:  :class:`~promod3.loop.FragmentInfo`
+ 
+  .. method:: Remove(index)
+
+    Remove a loop candidate from the list of candidates.
+
+    :param index: The index of the candidate that will be removed
+    :type index:  :class:`int`
+
+    :raises: :exc:`~exceptions.RuntimeError` if *index* is out of bounds.
+  
+  .. method:: HasFragmentInfos()
+
+    :return: True, if each loop candidate has a connected fragment info.
+    :rtype:  :class:`bool`
+
+  .. method:: GetFragmentInfo(index)
+
+    :return: Fragment info connected to loop candidate at given *index*.
+    :rtype:  :class:`~promod3.loop.FragmentInfo`
+    :param index: The index of the candidate.
+    :type index:  :class:`int`
+
+    :raises: :exc:`~exceptions.RuntimeError` if :meth:`HasFragmentInfos` is
+             False or if *index* is out of bounds.
+
+  .. method:: Extract(indices)
+
+    :return: Container with candidates with given *indices*.
+    :rtype:  :class:`LoopCandidates`
+    :param indices: Candidate indices to extract.
+    :type indices:  :class:`list` of :class:`int`
+
+    :raises: :exc:`~exceptions.RuntimeError` if any index is out of bounds.
+  
+
+  .. method:: GetClusters(max_dist)
+
+    Clusters the loop candidates according to their pairwise CA RMSD using a
+    greedy hierarchical clustering algorithm. Every candidate gets assigned a
+    unique cluster. At every clustering step, the two clusters with shortest
+    distance get merged, with the distance definition being the maximal CA RMSD
+    between any of the members of the two clusters.
+
+    :param max_dist: Maximal distance two clusters can have to be merged
+    :type max_dist:  :class:`float`
+
+    :returns: Lists of loop candidate indices into this container
+    :rtype:   :class:`list` of :class:`list` of :class:`int`
+
+  .. method:: GetClusteredCandidates(max_dist, neglect_size_one=True)
+
+    :returns: List of loop candidates clustered as in :meth:`GetClusters`.
+    :rtype:   :class:`list` of :class:`LoopCandidates`
+
+    :param max_dist: Maximal distance two clusters can have to be merged
+    :type max_dist:  :class:`float`
+    :param neglect_size_one: Whether clusters should be added to the returned
+                             list if they only contain one loop candidate
+    :type neglect_size_one:  :class:`bool`

modelling/pymod/export_loop_candidate.cc

@@ -222,9 +222,6 @@ void export_loop_candidate() {
          (arg("seq"), arg("num_loops"), arg("steps"), arg("sampler"),
           arg("closer"), arg("scorer"), arg("cooler"), arg("random_seed")=0))
     .staticmethod("FillFromMonteCarloSampler")
-    .def("GetClusters", &WrapGetClusters, (arg("max_rmsd")))
-    .def("GetClusteredCandidates", &WrapGetClusteredCandidates,
-         (arg("max_rmsd"), arg("neglect_size_one")=true))
     .def("ApplyCCD", &ApplyCCDWithSampler,
          (arg("n_stem"), arg("c_stem"), arg("torsion_sampler"),
           arg("max_iterations")=1000, arg("rmsd_cutoff")=0.1,
@@ -261,6 +258,9 @@ void export_loop_candidate() {
     .def("GetFragmentInfo", &LoopCandidates::GetFragmentInfo, (arg("index")),
          return_value_policy<copy_const_reference>())
     .def("Extract", &WrapExtractList, (arg("indices")))
+    .def("GetClusters", &WrapGetClusters, (arg("max_dist")))
+    .def("GetClusteredCandidates", &WrapGetClusteredCandidates,
+         (arg("max_dist"), arg("neglect_size_one")=true))
   ;
 
 }