Updated Lddt documentation with sequence separation

modules/mol/alg/doc/molalg.rst

@@ -41,7 +41,7 @@
 
   :returns: the Local Distance Difference Test score
   
-.. function:: LocalDistDiffTest(model, distance_list, tolerance_list, local_ldt_property_string="")
+.. function:: LocalDistDiffTest(model, distance_list, tolerance_list, sequence_separation=0,  local_ldt_property_string="")
   
   This function counts the conserved local contacts between the model and the reference structure
   (these are the values needed to compute the Local Distance Difference Test score, see description of 
@@ -49,6 +49,9 @@
   the thresholds can be more than one (the return counts are then the average over all thresholds), and
   the input is not the reference structure, but already a list of distances to be checked for conservation
 
+  A sequence separation parameter can be passed to the function. If this happens, only distances between residues
+  whose separation is higher than the provided parameter are considered when computing the score
+
   If a string is passed as the last parameter, residue-based counts and the value of the residue-based Local
   Distance Difference Test score are saved in each ResidueHandle as int and float properties, as detailed in
   the description of the previous function. 
@@ -58,6 +61,7 @@
   :param distance_list: the list of distances to check for conservation
   :type distance_list: :class:`~ost.mol.alg.GlobalRDMap`
   :param tolerance_list: a list of thresholds used to determine distance conservation
+  :param sequence_separation: sequence separation parameter used when computing the score
   :param local_ldt_property_string: the base name for the ResidueHandle properties that store the local scores
 
   :returns: a tuple containing the counts of the conserved distances in the model and of all the checked 
@@ -85,40 +89,57 @@
 
   :returns: the Local Distance Difference Test score
 
-.. function::  LDTHA(model, distance_list);
+.. function::  LDTHA(model, distance_list, sequence_separation=0);
 
   This function calculates the Local Distance Difference Test - High Accuracy score (see previous functions).
   The High Accuracy name comes from the fact that the tolerance levels used by this function are the same
   as the thresholds used by GDT-HA (0.5, 1, 2, and 4 Angstrom). 
 
+  A sequence separation parameter can be passed to the function. If this happens, only distances between residues
+  whose separation is higher than the provided parameter are considered when computing the score
+
   :param model: the model structure
   :type model: :class:`~ost.mol.EntityView`
   :param distance_list: the list of distances to check for conservation
   :type distance_list: :class:`~ost.mol.alg.GlobalRDMap`
+  :param sequence_separation: sequence separation parameter used when computing the score
 
   :returns: the Local Distance Difference Test score
 
-.. function: CreateDistanceList(reference, radius);
-.. function: CreateDistanceListFromMultipleReferences(reference_list, radius);
+.. function:: CreateDistanceList(reference, radius);
+.. function:: CreateDistanceListFromMultipleReferences(reference_list, tolerance_list, sequence_separation, radius);
 
   Both these functions create lists of distances to be checked during a Local Distance Difference Test
   (see description of the functions above). 
 
+  Both functions process only standard residues present in the first chain of the reference structures.
+
   The only difference between the two functions is that one takes a single reference structure and the other
   a list of reference structures. The structures in the list have to be properly aligned before being passed 
   to the function. Gaps in the alignment are allowed and automatically dealt with, but corresponding residues 
   in the structures must have the same residue number.
 
-  Both functions process only standard residues present in the first chain of the reference structures.
-
   If a distance between two atoms is shorter than the inclusion radius in all structures in which the two atoms are
   present, it is included in the list. However, if the distance is longer than the inclusion radius in at least
   one of the structures, it is not considered to be a local interaction and is excluded from the list.
 
+  The multiple-reference function takes care of residues with ambigous symmetric sidechains. To decide which naming
+  convention to use, the function computes a Local Distance Difference Test score for  each reference against the
+  first reference structure in the list, using only non ambigously-named atoms. It picks then the naming convention
+  that gives the highest score, guaranteeing that all references are processed with the correct atom names.
+
+  The cutoff list that will later be used to compute the Local Distance Difference Test score and the sequence
+  separation parameter must be passed to the multi-reference function. These parameters do not influence the output
+  distance list, which always includes all distances within the provided radius (to make it consistent with the
+  single-reference corresponding function). However, the parameters are used when dealing with the naming convention
+  of residues with ambiguous nomenclature.
+
   :param reference: a reference structure from which distances are derived
   :type reference: :class:`~ost.mol.EntityView`
   :param reference_list: a list of  of reference structures from which distances are derived
-  :type reference: list of :class:`~ost.mol.EntityView`
+  :type reference_list: list of :class:`~ost.mol.EntityView`
+  :param tolerance_list: a list of thresholds used to determine distance conservation when computing the LDDT score
+  :param sequence_separation: sequence separation parameter used when computing the LDDT score
   :param radius: inclusion radius (in Angstroms) used to determine the distances included in the list
   
   :returns: class `~ost.mol.alg.GlobalRDMap`

modules/mol/alg/src/local_dist_diff_test.hh

@@ -89,6 +89,16 @@ typedef std::map<UniqueAtomIdentifier,int> ExistenceMap;
 /// The function requires a list of distances to check, a model on which the distances are checked, and a 
 /// list of tolerance thresholds that are used to determine if the distances are conserved. 
 /// 
+/// The function only processes standard residues in the first chains of the model and of the reference
+/// For residues with symmetric sidechains (GLU, ASP, ARG, VAL, PHE, TYR), the 
+/// naming of the atoms is ambigous. For these residues, the function computes the Local Distance Difference 
+/// Test score that each naming convention would generate when considering all non-ambigous surrounding atoms.
+/// The solution that gives higher score is then picked to compute the final Local Difference
+/// Distance Score for the whole model.
+///
+/// A sequence separation parameter can be passed to the function. If this happens, only distances between residues
+/// whose separation is higher than the provided parameter are considered when computing the score. 
+///
 /// If a string is provided as an argument to the function, residue-per-residue statistics are stored as 
 /// residue properties. Specifically, the local residue-based lddt score is stored in a float property named
 /// as the provided string, while the residue-based number of conserved and total distances are saved in two 
@@ -105,6 +115,13 @@ std::pair<long int,long int> DLLEXPORT_OST_MOL_ALG LocalDistDiffTest(const Entit
 /// a model, a reference structure, a list of thresholds that are used to determine if distances are conserved, and an inclusion
 /// radius value used to determine which distances are checked.
 /// 
+/// The function only processes standard residues in the first chains of the model and of the reference
+/// For residues with symmetric sidechains (GLU, ASP, ARG, VAL, PHE, TYR), the 
+/// naming of the atoms is ambigous. For these residues, the function computes the Local Distance Difference 
+/// Test score that each naming convention would generate when considering all non-ambigous surrounding atoms.
+/// The solution that gives higher score is then picked to compute the final Local Difference
+/// Distance Score for the whole model.
+///
 /// If a string is provided as an argument to the function, residue-per-residue statistics are stored as 
 /// residue properties. Specifically, the local residue-based lddt score is stored in a float property named
 /// as the provided string, while the residue-based number of conserved and total distances are saved in two 
@@ -132,19 +149,31 @@ Real DLLEXPORT_OST_MOL_ALG LocalDistDiffTest(const ost::seq::AlignmentHandle& al
 ///
 /// Computes the Local Distance Difference High-Accuracy Test (with threshold 0.5,1,2 and 4 Angstrom)
 /// Requires a list of distances to check and a model for which the score is computed
+///
+/// A sequence separation parameter can be passed to the function. If this happens, only distances between residues
+/// whose separation is higher than the provided parameter are considered when computing the score. 
 Real DLLEXPORT_OST_MOL_ALG LDDTHA(EntityView& v, const GlobalRDMap& global_dist_list, int sequence_separation=0);
 
 /// \brief Creates a list of distances to check during a Local Difference Distance Test
 ///
-/// Requires a reference structure and an inclusion radius
+/// Requires a reference structure and an inclusion radius (max_dist)
 GlobalRDMap CreateDistanceList(const EntityView& ref,Real max_dist);
 
 /// \brief Creates a list of distances to check during a Local Difference Distance Test starting from multiple reference structures
 ///
-/// Requires a list of reference structure and an inclusion radius. If a distance between two atoms is shorter
-/// than the inclusion radius in all structures in which the two atoms are present, it will be included in the list
+/// Requires a list of reference structure and an inclusion radius (max_dist). If a distance between two atoms is shorter
+/// than the inclusion radius in all structures in which the two atoms are present, it is included in the list
 /// However, if the distance is longer than the inclusion radius in at least one of the structures, it
-/// will not be considered a local interaction and will be exluded from the list
+/// is not be considered a local interaction and is exluded from the list
+///
+/// The function takes care of residues with ambigous symmetric sidechains. To decide which naming convention to use, the functions
+/// computes a local distance score of each reference structure with the first reference structure in the list, using only non ambigously-named atoms. 
+/// It picks then the naming convention that gives the highest score, guaranteeing that all references are processed with the correct atom names.
+///
+/// The cutoff list that will later be used to compute the Local Distance Difference Test score and the  sequence separation parameter 
+/// must be passed to the function. These parameters do not influence the output distance list, which always includes all distances
+/// within the provided max_dist (to make it consistent with the single-reference corresponding function). However, the parameters are used when
+/// dealing with the naming convention of residues with ambiguous nomenclature. 
 GlobalRDMap CreateDistanceListFromMultipleReferences(const std::vector<EntityView>& ref_list,std::vector<Real>& cutoff_list, int sequence_separation, Real max_dist);
 
 /// \brief Prints all distances in a global distance list to standard output