documentation for the RigidBlocks algorithm

modelling/doc/algorithms.rst

@@ -32,8 +32,7 @@ modelling problem. This typically massively reduces the problem size by solving
 small subproblems and allows to tackle larger problems in a feasible amount
 of computing time.
 
-.. method:: ElEnumerador(mhandle, loop_candidates, start_resnums,
-                         chain_indices, weights)
+.. method:: ElEnumerador(mhandle, loop_candidates, start_resnums, chain_indices, weights)
 
   Searches the the loops in **loop_candidates** that optimize the
   score using the scorer that is set in **mhandle** and the given **weights**.
@@ -57,7 +56,131 @@ of computing time.
   :type chain_indices:  :class:`list`
   :type weights:        :class:`dict`            
 
+Rigid Blocks
+--------------------------------------------------------------------------------
 
-
-
+RMSD is a typical measure for similarity of two structures. Given an atom atom
+mapping between two structures, the minimum RMSD and the according superposition
+can efficiently be calculated using an approach based on singular value 
+decomposition. This approach is problematic if there are very dissimilar regions
+or when domain movement events occur. We can therefore implement an iterative
+superposition. The two structures undergo an initial superposition. For every
+iteration we then select a subset of atoms that are within a certain distance
+threshold that serve as input for the next superposition. This iterative
+superpostion typically converges to the largest common subpart but is
+non-deterministic since it depends on the initial superposition.
+The RigidBlocks algorithm is based on only the CA positions and performs this 
+iterative superposition multiple times by using a sliding window to select the 
+initial subset and gathers all unique results. These results can be very 
+similar and only differ by single positions. The algorithm therefore reduces
+the amount of solutions by merging them based on a threshold of similarity.
+If the sum of matching positions within the distance threshold divided by
+the maximum length of the two solutions is above a cluster thresh, the two
+solutions get merged by producing a common solution containing the shared
+positions. As a final result, the algorithm therefore detects common rigid
+subsets of positions.
+
+.. method:: RigidBlocks(bb_list_one, bb_list_two, [window_length = 12, max_iterations=20, distance_thresh=3.0, cluster_thresh=0.9])
+
+  Performs the RigidBlock algorithm on given input
+
+  :param bb_list_one:   First piece structural information from which CA
+                        positions will be extracted
+  :param bb_list_two:   Second piece of structural information from which CA
+                        positions will be extracted
+  :param window_length: Length of sliding window to generate initial subsets
+  :param max_iterations: Maximal numbers of iterations for every single
+                         iterative superposition
+  :param distance_thresh: Maximal distance two CA positions can have to be
+                          considered in the same rigid block and to select
+                          the common subset for the next iteration of the 
+                          iterative superposition
+  :param cluster_thresh: Threshold of similarity to perform the final merging
+                         of the solutions
+
+  :type bb_list_one:    :class:`promod3.loop.BackboneList`
+  :type bb_list_two:    :class:`promod3.loop.BackboneList`
+  :type window_length:  :class:`int`
+  :type max_iterations: :class:`int`
+  :type distance_thresh: :class:`float`
+  :type cluster_thresh: :class:`float`
+
+  :returns:             :class:`tuple` with the first element being a 
+                        :class:`list` of :class:`list` defining the
+                        indices of the common subsets (rigid blocks) relative
+                        to the input :class:`promod3.loop.BackboneList` objects 
+                        and the second element being a :class:`list` of 
+                        :class:`ost.geom.Mat4` defining the transformations to 
+                        superpose the according positions in **bb_list_one** 
+                        onto **bb_list_two**
+
+
+.. method:: RigidBlocks(aln, [seq_one_idx=0, seq_two_idx=1,window_length = 12, max_iterations=20, distance_thresh=3.0, cluster_thresh=0.9])
+
+  Performs the RigidBlock algorithm on given input
+
+  :param aln:           An alignment with attached :class:`ost.mol.EntityView`
+                        objects from which the positions are extracted
+  :param seq_idx_one:   The idx of the first sequence from which the CA 
+                        positions will be extracted
+  :param seq_idx_two:   The idx of the second sequence from which the CA
+                        positions will be extracted
+  :param window_length: Length of sliding window to generate initial subsets
+  :param max_iterations: Maximal numbers of iterations for every single
+                         iterative superposition
+  :param distance_thresh: Maximal distance two CA positions can have to be
+                          considered in the same rigid block and to select
+                          the common subset for the next iteration of the 
+                          iterative superposition
+  :param cluster_thresh: Threshold of similarity to perform the final merging
+                         of the solutions
+
+  :type aln:            :class:`ost.seq.AlignmentHandle`
+  :type seq_idx_one:    :class:`int`
+  :type seq_idx_two:    :class:`int`
+  :type window_length:  :class:`int`
+  :type max_iterations: :class:`int`
+  :type distance_thresh: :class:`float`
+  :type cluster_thresh: :class:`float`
+
+  :returns:             :class:`tuple` with the first element being a 
+                        :class:`list` of :class:`list` defining the
+                        column indices of the common subsets (rigid blocks) 
+                        relative to the input :class:`ost.seq.AlignmentHandle` 
+                        and the second element being a :class:`list` of 
+                        :class:`ost.geom.Mat4` defining the transformations to 
+                        superpose the according positions from the first
+                        sequence onto the second sequence.
+
+.. method:: RigidBlocks(pos_one, pos_two, [window_length = 12, max_iterations=20, distance_thresh=3.0, cluster_thresh=0.9])
+
+  Performs the RigidBlock algorithm on given input
+
+  :param pos_one:       First piece position information 
+  :param pos_two:       Second piece of position information
+  :param window_length: Length of sliding window to generate initial subsets
+  :param max_iterations: Maximal numbers of iterations for every single
+                         iterative superposition
+  :param distance_thresh: Maximal distance two CA positions can have to be
+                          considered in the same rigid block and to select
+                          the common subset for the next iteration of the 
+                          iterative superposition
+  :param cluster_thresh: Threshold of similarity to perform the final merging
+                         of the solutions
+
+  :type pos_one:        :class:`ost.geom.Vec3List`
+  :type pos_two:        :class:`ost.geom.Vec3List`
+  :type window_length:  :class:`int`
+  :type max_iterations: :class:`int`
+  :type distance_thresh: :class:`float`
+  :type cluster_thresh: :class:`float`
+
+  :returns:             :class:`tuple` with the first element being a 
+                        :class:`list` of :class:`list` defining the
+                        indices of the common subsets (rigid blocks) relative
+                        to the input :class:`ost.geom.Vec3List` objects 
+                        and the second element being a :class:`list` of 
+                        :class:`ost.geom.Mat4` defining the transformations to 
+                        superpose the according positions in **pos_one** 
+                        onto **pos_two**