diff --git a/modelling/doc/algorithms.rst b/modelling/doc/algorithms.rst index 39838d9f99cfef1aa98118e02f92aebd33f3f658..da9e0b925367faf68d6cabc648106800c41a50f0 100644 --- a/modelling/doc/algorithms.rst +++ b/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**