diff --git a/modules/index.rst b/modules/index.rst
index 4521313c8592ca3d57a7a91dcac7813c7a524316..deb197ceef31a736794beeeb78a4567cd79c809a 100644
--- a/modules/index.rst
+++ b/modules/index.rst
@@ -101,7 +101,7 @@ Varia
**Users**: :doc:`Reporting a problem <users>`
-**lDDT**: :doc:`lDDT command line executable<mol/alg/lddt>`
+**lDDT**: :doc:`lDDT command line executable and Python API<mol/alg/lddt>`
Extending OpenStructure
--------------------------------------------------------------------------------
diff --git a/modules/io/doc/io.rst b/modules/io/doc/io.rst
index f8f5302e060d360d13b2851d42dce12d3e9d2c66..5a61926725e82107c5b71e217209ed3f1de81b5b 100644
--- a/modules/io/doc/io.rst
+++ b/modules/io/doc/io.rst
@@ -343,3 +343,52 @@ Saving Density Maps
12
+Stereochemical Parameters
+--------------------------------------------------------------------------------
+
+In order to check the structure for some stereo-chemical and steric clashes
+before computing the lDDT scores it is required to pass parameter file based on
+Engh and Huber parameters, and on the atomic radii as defined in the Cambridge
+Structural Database. lDDT ships with default file called `stereo_chemical_props.txt`
+located in `$OST_ROOT/share/openstructure` directory. A class
+:class:`~ost.io.StereoChemicalParamsReader` is used to read this file.
+
+.. class:: StereoChemicalParamsReader
+
+ Object that holds and reads stereochemical parameters.
+
+ .. attribute:: bond_table
+
+ The table containing bond information of type :class:`~ost.mol.alg.StereoChemicalParams`.
+
+ .. attribute:: angle_table
+
+ The table containing angle information of type :class:`~ost.mol.alg.StereoChemicalParams`.
+
+ .. attribute:: nonbonded_table
+
+ The table containing clashes of type :class:`~ost.mol.alg.ClashingDistances`.
+
+ .. attribute:: filename
+
+ The path to the parameter file that will be used.
+
+ .. method:: StereoChemicalParamsReader(filename="")
+
+ Initializes StereoChemicalParamsReader.
+
+ :param filename: Path to the stereochemical parameter file - defaults to "".
+ :type filename: str
+
+ .. method:: Read(check=False)
+
+ Read the file.
+
+ :param check: Raise an error when any of the resulting tables are empty -
+ defaults to False
+ :type check: bool
+
+
+
+
+
diff --git a/modules/mol/alg/doc/lddt.rst b/modules/mol/alg/doc/lddt.rst
index 3d3e862c3fbc61682eb880fe3e738365b8cb1501..6529c47758e29d8fa292c475d7a212ce25cc9e56 100644
--- a/modules/mol/alg/doc/lddt.rst
+++ b/modules/mol/alg/doc/lddt.rst
@@ -1,6 +1,6 @@
-======
+====
lDDT
-======
+====
-------------------------------------
Where can I find the lDDT executable?
@@ -180,3 +180,69 @@ For example:
WARNING: Verbosity levels 1 and 2 can generate a large amount of output text,
especially with large structures and multiple models being evaluated.
+
+===============
+lDDT Python API
+===============
+
+One can replicate the binary using simple python script:
+
+.. code-block:: python
+
+ #! /bin/env python
+ """Run lDDT from within script."""
+ from ost.io import LoadPDB
+ from ost.mol.alg import (CleanlDDTReferences,
+ PreparelDDTGlobalRDMap,
+ lDDTSettings,
+ CheckStructure,
+ LocalDistDiffTest,
+ GetlDDTPerResidueStats,
+ PrintlDDTPerResidueStats)
+ from ost.io import StereoChemicalParamsReader
+
+ model_path = "Path to your model pdb file"
+ reference_path = "Path to your reference pdb file"
+ #
+ # Load model and prepare its view
+ model = LoadPDB(model_path)
+ model_view = model.GetChainList()[0].Select("peptide=true")
+ #
+ # Prepare references - it should be alist of EntityView(s)
+ references = [LoadPDB(reference_path).CreateFullView()]
+ #
+ # Initialize settings with default parameters and print them
+ settings = lDDTSettings()
+ settings.PrintParameters()
+
+ #
+ # Clean up references
+ CleanlDDTReferences(references)
+ #
+ # Prepare residue map from references
+ rdmap = PreparelDDTGlobalRDMap(references, settings)
+ #
+ # This part is optional and it depends on our settings parameter
+ if settings.structural_checks:
+ stereochemical_parameters = StereoChemicalParamsReader(
+ settings.parameter_file_path)
+ stereochemical_parameters.Read()
+ CheckStructure(ent=model_view,
+ bond_table=stereochemical_parameters.bond_table,
+ angle_table=stereochemical_parameters.angle_table,
+ nonbonded_table=stereochemical_parameters.nonbonded_table,
+ bond_tolerance=settings.bond_tolerance,
+ angle_tolerance=settings.angle_tolerance)
+ #
+ # Calculate lDDT
+ LocalDistDiffTest(model_view, references, rdmap, settings)
+ #
+ # Get the local scores
+ local_scores = GetlDDTPerResidueStats(model, rdmap, settings)
+ #
+ # Pring local scores
+ PrintlDDTPerResidueStats(local_scores, settings)
+
+This can be useful when we already have an models and references already read
+in the memory and we do not want run the binary.
+Please refere to specific function documentation for more details.
diff --git a/modules/mol/alg/doc/molalg.rst b/modules/mol/alg/doc/molalg.rst
index 1641b6b495143c263417018e8d86224bfadca955..028e9dc2147a5a7555b91fe9586b775369547483 100644
--- a/modules/mol/alg/doc/molalg.rst
+++ b/modules/mol/alg/doc/molalg.rst
@@ -59,6 +59,24 @@ Local Distance Test scores (lDDT, DRMSD)
:returns: a tuple containing the counts of the conserved distances in the
model and of all the checked distances
+.. function:: LocalDistDiffTest(model, reference_list, distance_list, settings)
+
+ Wrapper around :func:`LocalDistDiffTest` above.
+
+ :param model: the model structure
+ :type model: :class:`~ost.mol.EntityView`
+ :param reference_list: the list of reference structures from which distances were derived
+ :type reference_list: :class:`list` of :class:`~ost.mol.EntityView`
+ :param distance_list: A residue distance map prepared with :func:`PreparelDDTGlobalRDMap`
+ with *reference_list* and *settings* as parameters.
+ :type distance_list: :class:`~ost.mol.alg.GlobalRDMap`
+ :param settings: lDDT settings
+ :type settings: :class:`~ost.mol.alg.lDDTSettings`
+
+ :returns: the Local Distance Difference Test score (conserved distances
+ divided by all the checked distances)
+ :rtype: :class:`float`
+
.. function:: LocalDistDiffTest(model, target, cutoff, max_dist, \
local_lddt_property_string="")
@@ -287,7 +305,269 @@ Local Distance Test scores (lDDT, DRMSD)
:returns: :class:`~ost.mol.alg.GlobalRDMap`
-
+
+.. function:: PreparelDDTGlobalRDMap(reference_list, settings)
+
+ A wrapper around :func:`CreateDistanceList` and
+ :func:`CreateDistanceListFromMultipleReferences`. Depending on the length of
+ the ``reference_list`` it calls one or the other.
+
+ :param reference_list: a list of reference structures from which distances are
+ derived
+ :type reference_list: list of :class:`~ost.mol.EntityView`
+ :param settings: lDDT settings
+ :type settings: :class:`~ost.mol.alg.lDDTSettings`
+
+ :returns: :class:`~ost.mol.alg.GlobalRDMap`
+
+
+.. function:: CleanlDDTReferences(reference_list)
+
+ Prepares references to be used in lDDT calculation. It checks if all references
+ has the same chain name and selects this chain for for further calculations.
+
+ .. warning::
+
+ This function modifies original list.
+
+ :param reference_list: a list of reference structures from which distances are
+ derived
+ :type reference_list: list of :class:`~ost.mol.EntityView`
+
+
+.. function:: CheckStructure(ent, \
+ bond_table, \
+ angle_table, \
+ nonbonded_table, \
+ bond_tolerance, \
+ angle_tolerance)
+
+ Perform structural checks and filters the structure.
+
+ :param ent: Structure to check
+ :type ent: :class:`~ost.mol.EntityView`
+ :param bond_table: List of bond stereo chemical parameters obtained from
+ :class:`~ost.io.StereoChemicalParamsReader` or :func:`FillStereoChemicalParams`
+ :type bond_table: :class:`~ost.mol.alg.StereoChemicalParams`
+ :param angle_table: List of angle stereo chemical parameters obtained from
+ :class:`~ost.io.StereoChemicalParamsReader` or :func:`FillStereoChemicalParams`
+ :type angle_table: :class:`~ost.mol.alg.StereoChemicalParams`
+ :param nonbonded_table: Information about the clashing distances obtained from
+ :class:`~ost.io.StereoChemicalParamsReader` or :func:`FillClashingDistances`
+ :type nonbonded_table: :class:`~ost.mol.alg.ClashingDistances`
+ :param bond_tolerance: Tolerance in stddev for bonds
+ :type bond_tolerance: float
+ :param angle_tolerance: Tolerance in stddev for angles
+ :type angle_tolerance: float
+
+
+.. function:: GetlDDTPerResidueStats(model, distance_list, settings)
+
+ Get the per-residue statistics from the lDDT calculation.
+
+ :param model: The model structure
+ :type model: :class:`~ost.mol.EntityHandle`
+ :param distance_list: The list of distances to check for conservation
+ :type distance_list: :class:`~ost.mol.alg.GlobalRDMap`
+ :param settings: lDDT settings
+ :type settings: :class:`~ost.mol.alg.lDDTSettings`
+ :returns: Per-residue local lDDT scores
+ :rtype: :class:`list` of :class:`~ost.mol.alg.lDDTLocalScore`
+
+
+.. function:: PrintlDDTPerResidueStats(scores, settings)
+
+ Print per-residue statistics from lDDT calculation.
+
+ :param scores: Local lDDT scores
+ :type scores: :class:`list` of :class:`~ost.mol.alg.lDDTLocalScore`
+ :param settings: lDDT settings
+ :type settings: :class:`~ost.mol.alg.lDDTSettings`
+
+
+.. class:: lDDTLocalScore
+
+ Object containing per-residue information about calculated lDDT.
+
+ .. attribute:: cname
+
+ Chain name
+
+ .. attribute:: rname
+
+ Residue name
+
+ .. attribute:: rnum
+
+ Residue number
+
+ .. attribute:: is_assessed
+
+ Is the residue taken into account?
+
+ .. attribute:: quality_problems
+
+ Does the residue has quality problems?
+
+ .. attribute:: local_lddt
+
+ Local lDDT score
+
+ .. attribute:: conserved_dist
+
+ Number of conserved distances
+
+ .. attribute:: total_dist
+
+ Total number of conserved distances
+
+
+ .. method:: lDDTLocalScore(cname, \
+ rname, \
+ rnum, \
+ is_assessed, \
+ quality_problems, \
+ local_lddt, \
+ conserved_dist, \
+ total_dist)
+
+ Initialize lDDTLocalScore object.
+
+ :param cname: Chain name
+ :type cname: str
+ :param rname: Residue name
+ :type rname: str
+ :param rnum: Residue number
+ :type rnum: int
+ :param is_assessed: Is the residue taken into account? Yes or No
+ :type is_assessed: str
+ :param quality_problems: Does the residue has quality problems?
+ No if there are no problems, NA if the problems were not assessed, Yes if
+ there are sidechain problems and Yes+ if there are backbone problems
+ :type quality_problems: str
+ :param local_lddt: lDDT score for residue
+ :type local_lddt: float
+ :param conserved_dist: Number of conserved distances
+ :type conserved_dist: int
+ :param total_dist: Total number of distances
+ :type total_dist: int
+
+ .. method:: ToString(structural_checks)
+
+ String representation of the lDDTLocalScore object.
+
+ :param structural_checks: Where structural checks applied during calculations?
+ :type structural_checks: bool
+ :returns: String representation of the lDDTLocalScore.
+
+ .. method:: GetHeader(structural_checks, cutoffs_length)
+
+ Get the names of the fields as printed by ToString method.
+
+ :param structural_checks: Where structural checks applied during calculations?
+ :type structural_checks: bool
+ :param cutoffs_length: Length of the cutoffs list used for calculations
+ :type cutoffs_length: int
+
+
+.. class:: lDDTSettings
+
+ Object containing the settings used for lDDT calculations.
+
+ .. attribute:: bond_tolerance
+
+ Tolerance in stddevs for bonds
+
+ .. attribute:: angle_tolerance
+
+ Tolerance in stddevs for angles
+
+ .. attribute:: radius
+
+ Distance inclusion radius
+
+ .. attribute:: sequence_separation
+
+ Sequence separation
+
+ .. attribute:: sel
+
+ Selection performed on reference(s)
+
+ .. attribute:: parameter_file_path
+
+ Path to the stereochemical parameter file
+
+ .. attribute:: structural_checks
+
+ Are structural checks and filter input data on?
+
+ .. attribute:: consistency_checks
+
+ Are consistency checks on?
+
+ .. attribute:: cutoffs
+
+ List of thresholds used to determine distance
+
+ .. attribute:: label
+
+ the base name for the ResidueHandle properties that store the local scores
+
+ .. method:: lDDTSettings(bond_tolerance=12, \
+ angle_tolerance=12, \
+ radius=15, \
+ sequence_separation=0, \
+ sel=="", \
+ parameter_file_path="", \
+ structural_checks=True, \
+ consistency_checks=True, \
+ cutoffs=(0.5, 1.0, 2.0, 4.0), \
+ label="locallddt")
+
+ Initializes lDDTSettings object.
+
+ :param bond_tolerance: tolerance in stddevs for bonds - default 12.0
+ :type bond_tolerance: float
+ :param angle_tolerance: tolerance in stddevs for angles - default 12.0
+ :type angle_tolerance: float
+ :param radius: distance inclusion radius - default 15.0
+ :type radius: float
+ :param sequence_separation: sequence separation - default 0
+ :type sequence_separation: int
+ :param sel: selection performed on reference(s) - default ""
+ :type sel: str
+ :param parameter_file_path: use specified parmeter file - default ""
+ :type parameter_file_path: str
+ :param structural_checks: perform structural checks and filter input data - default True
+ :type structural_checks: bool
+ :param consistency_checks: perform consistency checks - default True
+ :type consistency_checks: bool
+ :param cutoffs: a list of thresholds used to determine distance
+ conservation - default [0.5, 1.0, 2.0, 4.0]
+ :type cutoffs: list of floats
+ :param label: the base name for the ResidueHandle properties that store
+ the local scores- default "locallddt"
+ :type label: str
+
+ .. method:: SetStereoChemicalParamsPath(path)
+
+ Set the path to the stereochemical parameter file.
+
+ :param path: Path to stereochemical parameter file
+ :type path: str
+
+ .. method:: PrintParameters()
+
+ Print settings.
+
+ .. method:: ToString()
+
+ String representation of the lDDTSettings object.
+
+ :returns: str
+
+
.. class:: UniqueAtomIdentifier
Object containing enough information to uniquely identify an atom in a structure