From 60dbce3a377312f203286c8a5ab6a823993bea27 Mon Sep 17 00:00:00 2001
From: Gerardo Tauriello <gerardo.tauriello@unibas.ch>
Date: Tue, 11 Apr 2017 20:38:40 +0200
Subject: [PATCH] Doc - wrong default for editor and updated LocalDistDiffTest.
---
modules/mol/alg/doc/molalg.rst | 127 +++++++++++++++++++++-----------
modules/mol/base/doc/entity.rst | 4 +-
2 files changed, 87 insertions(+), 44 deletions(-)
diff --git a/modules/mol/alg/doc/molalg.rst b/modules/mol/alg/doc/molalg.rst
index e702b49ac..4f81c318c 100644
--- a/modules/mol/alg/doc/molalg.rst
+++ b/modules/mol/alg/doc/molalg.rst
@@ -5,62 +5,105 @@
:synopsis: Algorithms operating on molecular structures
-.. function:: LocalDistDiffTest(model, distance_list, tolerance_list, sequence_separation=0, local_ldt_property_string="")
+.. function:: LocalDistDiffTest(model, distance_list, tolerance_list, \
+ sequence_separation=0, \
+ local_lddt_property_string="")
- This function counts the number of conserved local contacts between a model and a reference structure
- which is needed to compute the Local Distance Difference Test score.
-
- The Local Distance Difference Test score is a number between zero and one, which measures the agreement of
- local contacts between a model and a reference structure. One means complete agreement, and zero means no agreement at
- all. The calculation of this score does not require any superposition between the model
- and the reference structures.
+ This function counts the number of conserved local contacts between a model
+ and a reference structure which is needed to compute the Local Distance
+ Difference Test score.
+
+ The Local Distance Difference Test score is a number between zero and one,
+ which measures the agreement of local contacts between a model and a
+ reference structure. One means complete agreement, and zero means no agreement
+ at all. The calculation of this score does not require any superposition
+ between the model and the reference structures.
- All distances between atoms in the reference structure that are shorter than a certain predefined length (inclusion
- radius) are compared with the corresponding distances in the model structure. If the difference between a reference
- distance and the corresponding model distance is smaller than a threshold value (tolerance), that distance is
- considered conserved. The final lDDT score is the fraction of conserved distances. Missing atoms in the model structure
- lead to non-conserved distances (and thus lower the final lDDT score).
+ All distances between atoms in the reference structure that are shorter than a
+ certain predefined length (inclusion radius) are compared with the
+ corresponding distances in the model structure. If the difference between a
+ reference distance and the corresponding model distance is smaller than a
+ threshold value (tolerance), that distance is considered conserved. The final
+ lDDT score is the fraction of conserved distances. Missing atoms in the model
+ structure lead to non-conserved distances (and thus lower the final lDDT
+ score).
- This function takes as an input a list of distances to be checked for conservation. Any number of threshold values
- can be specified when the function is called. All thresholds are then applied in sequence and the return counts are
- averaged over all threshold values. A sequence separation parameter can be passed to the function. If this happens,
- only distances between residues whose separation in sequence is higher than the provided parameter are considered
- when the score is computed.
-
- 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. 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 int properties named <string>_conserved and <string>_total.
+ This function takes as an input a list of distances to be checked for
+ conservation. Any number of threshold values can be specified when the
+ function is called. All thresholds are then applied in sequence and the return
+ counts are averaged over all threshold values. A sequence separation parameter
+ can be passed to the function. If this happens, only distances between
+ residues whose separation in sequence is higher than the provided parameter
+ are considered when the score is computed.
+
+ 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. 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 int properties named <string>_conserved and <string>_total.
: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 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
+ :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_lddt_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
- distances
+ :returns: a tuple containing the counts of the conserved distances in the
+ model and of all the checked distances
+.. function:: LocalDistDiffTest(model, target, cutoff, max_dist, \
+ local_lddt_property_string="")
-.. function:: LocalDistDiffTest(alignment, tolerance, radius, ref_index=0, mdl_index=1)
+ Wrapper around :func:`LocalDistDiffTest` above using:
+ *distance_list* = :func:`CreateDistanceList` with *target* and *max_dist* as
+ parameters and *tolerance_list* = [*cutoff*].
- Calculates the Local Distance Difference Test score (see previous function) starting from an
- alignment between a reference structure and a model. The AlignmentHandle parameter used to provide the
- alignment to the function needs to have the two structures attached to it. By default the first structure in the
- alignment is considered to be the reference structure, and the second structure is taken as the model. This
- can however be changed by passing the indexes of the two structures in the AlignmentHandle as parameters to the
- function.
-
- BEWARE: This function uses the old implementation of the Local Distance Difference Test algorithm and
- will give slightly different results from the new one.
-
- :param alignment: an alignment containing the sequences of the reference and of the model structures, with the structures themselves
+ :param model: the model structure
+ :type model: :class:`~ost.mol.EntityView`
+ :param target: the target structure from which distances are derived
+ :type target: :class:`~ost.mol.EntityView`
+ :param cutoff: single distance threshold to determine distance conservation
+ :type cutoff: :class:`float`
+ :param max_dist: the inclusion radius in Angstroms (to determine which
+ distances are checked for conservation)
+ :type max_dist: :class:`float`
+ :param local_lddt_property_string: the base name for the ResidueHandle
+ properties that store the local scores
+
+ :returns: the Local Distance Difference Test score (conserved distances
+ divided by all the checked distances)
+ :rtype: :class:`float`
+
+
+.. function:: LocalDistDiffTest(alignment, tolerance, radius, ref_index=0, \
+ mdl_index=1)
+
+ Calculates the Local Distance Difference Test score (see previous function)
+ starting from an alignment between a reference structure and a model. The
+ AlignmentHandle parameter used to provide the alignment to the function needs
+ to have the two structures attached to it. By default the first structure in
+ the alignment is considered to be the reference structure, and the second
+ structure is taken as the model. This can however be changed by passing the
+ indexes of the two structures in the AlignmentHandle as parameters to the
+ function.
+
+ BEWARE: This function uses the old implementation of the Local Distance
+ Difference Test algorithm and will give slightly different results from the
+ new one.
+
+ :param alignment: an alignment containing the sequences of the reference and
+ of the model structures, with the structures themselves
attached
- :type alignment: :class:`~ost.seq.AlignmentHandle`
+ :type alignment: :class:`~ost.seq.AlignmentHandle`
:param tolerance: a list of thresholds used to determine distance conservation
- :param radius: the inclusion radius in Angstroms (to determine which distances are checked for conservation)
+ :param radius: the inclusion radius in Angstroms (to determine which distances
+ are checked for conservation)
:param ref_index: index of the reference structure in the alignment
:param mdl_index: index of the model in the alignment
diff --git a/modules/mol/base/doc/entity.rst b/modules/mol/base/doc/entity.rst
index f823e4943..f55380bb1 100644
--- a/modules/mol/base/doc/entity.rst
+++ b/modules/mol/base/doc/entity.rst
@@ -143,7 +143,7 @@ The Handle Classes
See :attr:`atoms`
- .. method:: EditXCS([edit_mode=mol.EditMode.BUFFERED_EDIT])
+ .. method:: EditXCS([edit_mode=mol.EditMode.UNBUFFERED_EDIT])
Request :class:`XCSEditor` for editing the external coordinate system. This
call will fail when there are pending changes of the internal coordinate
@@ -156,7 +156,7 @@ The Handle Classes
:returns: :class:`XCSEditor`
- .. method:: EditICS([edit_mode=mol.EditMode.BUFFERED_EDIT])
+ .. method:: EditICS([edit_mode=mol.EditMode.UNBUFFERED_EDIT])
Request :class:`ICSEditor` for editing the internal coordinate system, such
as torsions, bond lengths and angle between two bonds. This call will fail
--
GitLab