diff --git a/modules/mol/alg/pymod/__init__.py b/modules/mol/alg/pymod/__init__.py
index 10cb898b984204424b914439d5b84abb61f9b974..126d0196f2d6ff25148a6724df5dd63a1e764d6a 100644
--- a/modules/mol/alg/pymod/__init__.py
+++ b/modules/mol/alg/pymod/__init__.py
@@ -5,28 +5,28 @@ import ost.mol.alg.trajectory_analysis
import ost.mol.alg.structure_analysis
import ost.mol.alg.helix_kinks
-
+# Fills a list of reference clashing distances from a file (requires a path to the file)
def FillClashingDistancesFromFile(filename,default_clashing_distance,default_tolerance):
fh=open(filename,'r')
lines=fh.readlines()
fh.close()
return FillClashingDistances(lines,default_clashing_distance,default_tolerance)
-
+# Fills a list of bond stereo-chemical statistics from a file (requires a path to the file)
def FillBondStereoChemicalParamsFromFile(filename):
fh=open(filename,'r')
lines=fh.readlines()
fh.close()
return FillBondStereoChemicalParams("Bond",lines)
-
+# Fills a list of angle stereo-chemical statistics from a file (requires a path to the file)
def FillAngleStereoChemicalParamsFromFile(filename):
fh=open(filename,'r')
lines=fh.readlines()
fh.close()
return FillAngleStereoChemicalParams("Angle",lines)
-
+# Returns the default list of reference clashing distances (from the default OpenStructure parameter file)
def DefaultClashingDistances():
shared_path=ost.GetSharedDataPath()
filename=os.path.join(shared_path,'stereo_chemical_props.txt')
@@ -35,6 +35,7 @@ def DefaultClashingDistances():
fh.close()
return FillClashingDistances(lines,1.5,0.0)
+# Returns the default list of bond stereo-chemical statistics (from the default OpenStructure parameter file)
def DefaultBondStereoChemicalParams():
shared_path=ost.GetSharedDataPath()
filename=os.path.join(shared_path,'stereo_chemical_props.txt')
@@ -43,6 +44,7 @@ def DefaultBondStereoChemicalParams():
fh.close()
return FillStereoChemicalParams("Bond",lines)
+# Returns the default list of angle stereo-chemical statistics (from the default OpenStructure parameter file)
def DefaultAngleStereoChemicalParams():
shared_path=ost.GetSharedDataPath()
filename=os.path.join(shared_path,'stereo_chemical_props.txt')
diff --git a/modules/mol/alg/src/filter_clashes.cc b/modules/mol/alg/src/filter_clashes.cc
index e4758a86d8baa06157c430880b441cbe27fc51f2..43689bf1607ec41368a497401d31fbf2577e438d 100644
--- a/modules/mol/alg/src/filter_clashes.cc
+++ b/modules/mol/alg/src/filter_clashes.cc
@@ -27,6 +27,7 @@
namespace {
+// helper function
String bond_string(const ost::mol::AtomView& atom1, const ost::mol::AtomHandle& atom2) {
String atom1_str = atom1.GetName();
String atom2_str = atom2.GetName();
@@ -43,6 +44,7 @@ String bond_string(const ost::mol::AtomView& atom1, const ost::mol::AtomHandle&
return stkey.str();
}
+// helper function
String bond_string_elems(String& ele1, String ele2) {
String string1,string2;
if (ele1 < ele2) {
@@ -57,6 +59,7 @@ String bond_string_elems(String& ele1, String ele2) {
return stkey.str();
}
+// helper function
String angle_string(const ost::mol::AtomHandle& atom1, const ost::mol::AtomView& atom, const ost::mol::AtomHandle& atom2 ) {
String atom1_str = atom1.GetName();
String atom2_str = atom2.GetName();
@@ -76,7 +79,6 @@ String angle_string(const ost::mol::AtomHandle& atom1, const ost::mol::AtomView&
}
-
namespace ost { namespace mol { namespace alg {
void ClashingDistances::SetClashingDistance(const String& ele1,const String& ele2, Real min_distance, Real tolerance)
diff --git a/modules/mol/alg/src/filter_clashes.hh b/modules/mol/alg/src/filter_clashes.hh
index 5984a05f57f40153a22139ff1a2b89f7e0c069c9..60a6c97abe9d2417e4bd671c8de6f03cd637bb78 100644
--- a/modules/mol/alg/src/filter_clashes.hh
+++ b/modules/mol/alg/src/filter_clashes.hh
@@ -24,17 +24,29 @@
namespace ost { namespace mol { namespace alg {
+/// \brief List of reference atom-atom distances to detect clashes between non-bonded atoms
class ClashingDistances
{
public:
+ /// \brief Default constructor (creates an empty list)
ClashingDistances(): valid_flag_(true) {}
+
+ /// \brief Adds or replaces an entry
+ ///
+ /// Requires an atom-atom distance and a tolerance threshold
void SetClashingDistance(const String& ele1,const String& ele2, Real min_distance, Real tolerance);
+
+ /// \brief Recovers a reference distance and a tolerance threshold (respectively) from the list
std::pair<Real,Real> GetClashingDistance(const String& ele1,const String& ele2) const;
+
+ /// \brief Recovers the longest distance in the list, corrected by tolerance
Real GetMaxAdjustedDistance() const;
+
+ /// \brief Returns true if the list is empty (i.e. in an invalid, useless state)
bool IsEmpty() const;
- //DEBUG
+ /// \brief Prints all distances in the list to standard output
void PrintAllDistances() const;
private:
@@ -45,17 +57,33 @@ private:
bool valid_flag_;
};
-
+
+/// \brief List of stereo chemical parameters (Bonds and angles)
+///
+/// For each item (bond or angle in a specific residue), stores the mean and standard deviation
class StereoChemicalParams
{
public:
+ /// \brief Adds or replaces an entry
void SetParam(const String& param, const String& residue, Real value, Real st_dev);
+
+ /// \brief Recovers mean and standard deviation (respectively) of a stereoā»chemical item (bond or angle) from the list
+ ///
+ /// Item format: Bond: X-Y, Angle:X-Y-Z
std::pair<Real,Real> GetParam(const String& element,const String& residue) const;
+
+ /// \brief Checks if the list contains an entry for a specific stereo-chemical item (a bond or atom in a specific residue)
+ ///
+ /// Item format: Bond: X-Y, Angle:X-Y-Z
bool ContainsParam(const String& param,const String& residue) const;
+
+ /// \brief Returns true if the list is empty (i.e. in an invalid, useless state)
+ ///
+ /// Item format: Bond: X-Y, Angle:X-Y-Z
bool IsEmpty() const;
- //DEBUG
+ /// \brief Prints all distances in the list to standard output
void PrintAllParameters() const;
private:
@@ -64,15 +92,43 @@ private:
};
+/// \brief Fills a list of reference clashing distances from the content of a parameter file
+///
+/// Requires a list of strings holding the contents of a parameter file, one line per string
ClashingDistances DLLEXPORT_OST_MOL_ALG FillClashingDistances(std::vector<String>& stereo_chemical_props_file);
+
+/// \brief Fills a list of stereo-chemical statistics from the content of a parameter file
+///
+/// Requires a list of strings holding the contents of a parameter file, one line per string
StereoChemicalParams DLLEXPORT_OST_MOL_ALG FillStereoChemicalParams(const String& header, std::vector<String>& stereo_chemical_props_file);
-
+
+/// \brief Filters a structure based on detected clashes between non bonded atoms. Entity version
+///
+/// If a clash between two atoms (distance shorter than reference clashing distance - tolerance threshold)
+/// is detected in a residue's side-chain, all atoms in the side chain are removed from the structure
+/// If a clash is detected in the backbone, all atoms in the residue are removed. This behavior is changed
+/// by the always_remove_bb flag: when the flag is set to true all atoms in the residue are removed even if
+/// a clash is just detected in the side-chain
EntityView DLLEXPORT_OST_MOL_ALG FilterClashes(const EntityView& ent,
const ClashingDistances& min_distances, bool always_remove_bb=false);
+/// \brief Filters a structure based on detected clashes between non bonded atoms. Handle version
+///
+/// If a clash between two atoms (distance shorter than reference clashing distance - tolerance threshold)
+/// is detected in a residue's side-chain, all atoms in the side chain are removed from the structure
+/// If a clash is detected in the backbone, all atoms in the residue are removed. This behavior is changed
+/// by the always_remove_bb flag: when the flag is set to true all atoms in the residue are removed even if
+/// a clash is just detected in the side-chain
EntityView DLLEXPORT_OST_MOL_ALG FilterClashes(const EntityHandle& ent,
const ClashingDistances& min_distances, bool always_remove_bb=false);
+/// \brief Filters a structure based on detected stereo-chemical violations. Entity version
+///
+/// If a stereo-chemical violation (i.e., a bond or an angle with a value outside the range defined by
+/// the mean value, the standard deviation and the tolerance parameter) is detected in a residue's side-chain,
+/// all atoms in the side chain are removed from the structure. If a violation is detected in the backbone, all
+/// atoms in the residue are removed. This behavior is changed by the always_remove_bb flag: when the flag is
+/// set to true all atoms in the residue are removed even if a violation is just detected in the side-chain
EntityView DLLEXPORT_OST_MOL_ALG CheckStereoChemistry(const EntityView& ent,
const StereoChemicalParams& bond_table,
const StereoChemicalParams& angle_table,
@@ -80,6 +136,13 @@ EntityView DLLEXPORT_OST_MOL_ALG CheckStereoChemistry(const EntityView& ent,
Real angle_tolerance,
bool always_remove_bb=false);
+/// \brief Filters a structure based on detected stereo-chemical violations. Handle version
+///
+/// If a stereo-chemical violation (i.e., a bond or an angle with a value outside the range defined by
+/// the mean value, the standard deviation and the tolerance parameter) is detected in a residue's side-chain,
+/// all atoms in the side chain are removed from the structure. If a violation is detected in the backbone, all
+/// atoms in the residue are removed. This behavior is changed by the always_remove_bb flag: when the flag is
+/// set to true all atoms in the residue are removed even if a violation is just detected in the side-chain
EntityView DLLEXPORT_OST_MOL_ALG CheckStereoChemistry(const EntityHandle& ent,
const StereoChemicalParams& bond_table,
const StereoChemicalParams& angle_table,
diff --git a/modules/mol/alg/src/lddt.cc b/modules/mol/alg/src/lddt.cc
index 55574838555c030e07b10758d4794fc14acb72ed..f5f91e3ce36c2a81fc3c2d842af1e551bac8cce0 100644
--- a/modules/mol/alg/src/lddt.cc
+++ b/modules/mol/alg/src/lddt.cc
@@ -42,6 +42,7 @@ using namespace ost::mol;
using namespace ost::mol::alg;
namespace po=boost::program_options;
+// loads a file
EntityHandle load(const String& file, const IOProfile& profile)
{
try {
@@ -62,6 +63,7 @@ EntityHandle load(const String& file, const IOProfile& profile)
}
}
+// prints usage output
void usage()
{
std::cerr << "usage: lddt [options] <mod1> [mod1 [mod2]] <ref>" << std::endl;
@@ -78,6 +80,7 @@ void usage()
std::cerr << " -e print version" << std::endl;
}
+// computes coverage
std::pair<int,int> compute_coverage (const EntityView& v,const GlobalRDMap& glob_dist_list)
{
int second=0;
@@ -99,14 +102,17 @@ std::pair<int,int> compute_coverage (const EntityView& v,const GlobalRDMap& glob
int main (int argc, char **argv)
{
+ // sets some default values for parameters
String version = "Beta - 2012-06-13";
Real bond_tolerance = 8.0;
Real angle_tolerance = 8.0;
Real radius=15.0;
-
+
+ // creates the required loading profile
IOProfile profile;
profile.bond_feasibility_check=false;
- // parse options
+
+ // parses options
String sel;
bool structural_checks=false;
po::options_description desc("Options");
@@ -200,6 +206,8 @@ int main (int argc, char **argv)
if (vm.count("inclusion_radius")) {
radius=vm["inclusion_radius"].as<Real>();
}
+
+ // loads the reference file and creates the list of distances to check in lddt
String ref_file=files.back();
EntityHandle ref=load(ref_file, profile);
if (!ref) {
@@ -208,6 +216,8 @@ int main (int argc, char **argv)
files.pop_back();
EntityView ref_view=ref.Select(sel);
GlobalRDMap glob_dist_list = CreateDistanceList(ref_view,radius);
+
+ // prints out parameters used in the lddt calculation
std::cout << "Verbosity level: " << verbosity_level << std::endl;
if (structural_checks) {
std::cout << "Stereo-chemical and steric clash checks: On " << std::endl;
@@ -225,6 +235,8 @@ int main (int argc, char **argv)
LOG_INFO("CLASH INFO FORMAT: Chain1 Residue1 ResNum1 Atom1 Chain2 Residue2 ResNum2 Atom2 Observed Difference Status");
}
LOG_INFO("LDDT INFO FORMAT: Chain1 Residue1 ResNum1 Atom1 Chain2 Residue2 ResNum2 Atom2 ModelDist TargetDist Difference Tolerance Status");
+
+ // cycles through the models to evaluate
for (size_t i=0; i<files.size(); ++i) {
EntityHandle model=load(files[i], profile);
if (!model) {
@@ -235,18 +247,15 @@ int main (int argc, char **argv)
}
EntityView v=model.CreateFullView();
-
// The code in this following block is only used to make CASP9 models load correctly and normally commented out
EntityView model2=model.Select("aname!=CEN,NV,OT1,OT,CAY,CY,OXT,1OCT,NT,OT2,2OCT,OVL1,OC1,O1,OC2,O2,OVU1");
EntityView v1=model2.Select("not (rname==GLY and aname==CB)");
boost::filesystem::path pathstring(files[i]);
-
#if BOOST_FILESYSTEM_VERSION==3 || BOOST_VERSION<103400
String filestring=pathstring.string();
#else
String filestring=pathstring.file_string();
#endif
-
if (filestring.substr(5,5)=="TS257" || filestring.substr(5,5)=="TS458" ) {
for (AtomHandleIter ait=v1.GetHandle().AtomsBegin();ait!=v1.GetHandle().AtomsEnd();++ait){
AtomHandle aitv = *ait;
@@ -255,13 +264,14 @@ int main (int argc, char **argv)
aitv.SetElement(firstletter);
}
}
- v=v1;
+ v=v1;
std::cout << "File: " << files[i] << std::endl;
std::pair<int,int> cov = compute_coverage(v,glob_dist_list);
std::cout << "Coverage: " << (float(cov.first)/float(cov.second)) << " (" << cov.first << " out of " << cov.second << " residues)" << std::endl;
- if (structural_checks) {
- boost::filesystem::path loc(parameter_filename);
+ if (structural_checks) {
+ // reads in parameter files
+ boost::filesystem::path loc(parameter_filename);
boost::filesystem::ifstream infile(loc);
if (!infile) {
std::cout << "Could not find " << parameter_filename << std::endl;
@@ -290,7 +300,8 @@ int main (int argc, char **argv)
if (nonbonded_table.IsEmpty()) {
std::cout << "Error reading the Clashing section of the stereo-chemical parameter file." << std::endl;
exit(-1);
- }
+ }
+ // performs structural checks and filters the structure
v=alg::CheckStereoChemistry(v,bond_table,angle_table,bond_tolerance,angle_tolerance);
cov = compute_coverage(v,glob_dist_list);
std::cout << "Coverage after stereo-chemical checks: " << (float(cov.first)/float(cov.second)) << " (" << cov.first << " out of " << cov.second << " residues)" << std::endl;
@@ -303,6 +314,7 @@ int main (int argc, char **argv)
return 0;
}
+ // computes the lddt score
std::vector<Real> cutoffs;
cutoffs.push_back(0.5);
cutoffs.push_back(1.0);
@@ -313,7 +325,8 @@ int main (int argc, char **argv)
Real lddt = static_cast<Real>(total_ov.first)/(static_cast<Real>(total_ov.second) ? static_cast<Real>(total_ov.second) : 1);
std::cout << "Global LDDT score: " << lddt << std::endl;
std::cout << "(" << std::fixed << total_ov.first << " conserved distances in the model out of " << total_ov.second << " checked)" << std::endl;
-
+
+ // prints the residue-by-residue statistics
std::cout << "Local LDDT Score:" << std::endl;
std::cout << "Chain\tResName\tResNum\tScore\t(Conserved/Total)" << std::endl;
for (ResidueViewIter rit=v.ResiduesBegin();rit!=v.ResiduesEnd();++rit){
diff --git a/modules/mol/alg/src/local_dist_diff_test.cc b/modules/mol/alg/src/local_dist_diff_test.cc
index 0511e71ef0fb397f135e3f18f86afab6c7653f6d..089b2402637c7462f5e6cb2c1f3155504a4c15e6 100644
--- a/modules/mol/alg/src/local_dist_diff_test.cc
+++ b/modules/mol/alg/src/local_dist_diff_test.cc
@@ -7,6 +7,7 @@ namespace ost { namespace mol { namespace alg {
namespace {
+// helper function
String swapped_name(const String& name)
{
if (name=="OE1") return "OE2";
@@ -30,6 +31,7 @@ String swapped_name(const String& name)
return name;
}
+// helper function
bool swappable(const String& rname, const String& aname)
{
if (rname=="GLU") {
@@ -51,6 +53,7 @@ bool swappable(const String& rname, const String& aname)
return false;
}
+// helper function
std::pair<bool,Real> within_tolerance(Real mdl_dist, std::pair<Real,Real>& values, Real tol)
{
Real min = values.first;
@@ -74,7 +77,7 @@ std::pair<bool,Real> within_tolerance(Real mdl_dist, std::pair<Real,Real>& value
return std::make_pair<bool,Real>(within_tol,difference);
}
-
+// helper function
std::pair<Real, Real> calc_overlap1(const ResidueRDMap& res_distance_list, const ResNum& rnum,
ChainView mdl_chain,
std::vector<Real>& tol_list, bool only_fixed,
@@ -141,7 +144,7 @@ std::pair<Real, Real> calc_overlap1(const ResidueRDMap& res_distance_list, const
return overlap;
}
-
+// helper function used by the alignment-based Local Distance Difference Test
std::pair<Real, Real> calc_overlap2(const seq::ConstSequenceHandle& ref_seq,
const seq::ConstSequenceHandle& mdl_seq,
int pos, Real tol, Real max_dist,
@@ -226,6 +229,9 @@ std::pair<Real, Real> calc_overlap2(const seq::ConstSequenceHandle& ref_seq,
return overlap;
}
+// for each residue with multiple possible nomenclature conventions, checks which choice (switched or not)
+// of atom nomenclature gives the highest lddt score then changes the naming convention of the input
+// entity view accordingly
void check_and_swap(const GlobalRDMap& glob_dist_list, const EntityView& mdl, std::vector<Real> cutoff_list, std::vector<std::pair<long int, long int> > overlap_list)
{
ChainView mdl_chain=mdl.GetChainList()[0];
@@ -262,6 +268,7 @@ void check_and_swap(const GlobalRDMap& glob_dist_list, const EntityView& mdl, st
}
}
+// helper function to update existence map entries for multiple reference input structures
void update_existence_map (ExistenceMap& ex_map, const EntityView& ev, int ref_counter)
{
AtomViewList ev_atom=ev.GetAtomList();
@@ -277,6 +284,7 @@ void update_existence_map (ExistenceMap& ex_map, const EntityView& ev, int ref_c
}
}
+// helper function for super-fast lookup of atom existence in multiple reference input structures
int in_existence_map(const ExistenceMap& ex_map, const UniqueAtomIdentifier& uai)
{
ExistenceMap::const_iterator find_uai_ci = ex_map.find(uai);
@@ -287,6 +295,7 @@ int in_existence_map(const ExistenceMap& ex_map, const UniqueAtomIdentifier& uai
return return_value;
}
+// merges distance lists from multiple reference structures. The login is described in the code
void merge_distance_lists(GlobalRDMap& ref_dist_map, const GlobalRDMap& new_dist_map, ExistenceMap& ex_map, const EntityView& ref,int ref_counter)
{
// iterate over the residues in the ref_dist_map
@@ -354,7 +363,7 @@ void merge_distance_lists(GlobalRDMap& ref_dist_map, const GlobalRDMap& new_dist
}
-
+// helper function
bool IsStandardResidue(String rn)
{
String upper_rn=rn;
@@ -384,7 +393,7 @@ bool IsStandardResidue(String rn)
return false;
}
-
+// required because UniqueAtomIdentifier is used as a key in a std::map
bool UniqueAtomIdentifier::operator==(const UniqueAtomIdentifier& rhs) const
{
if (chain_ == rhs.GetChainName() &&
@@ -396,6 +405,7 @@ bool UniqueAtomIdentifier::operator==(const UniqueAtomIdentifier& rhs) const
return false;
}
+// required because UniqueAtomIdentifier is used as a key in a std::map
bool UniqueAtomIdentifier::operator<(const UniqueAtomIdentifier& rhs) const
{
if (chain_ < rhs.GetChainName()) {
@@ -614,6 +624,7 @@ Real LDDTHA(EntityView& v, const GlobalRDMap& global_dist_list)
return static_cast<Real>(total_ov.first)/(static_cast<Real>(total_ov.second) ? static_cast<Real>(total_ov.second) : 1);
}
+/*
Real OldStyleLDDTHA(EntityView& v, const GlobalRDMap& global_dist_list)
{
Real lddt =0;
@@ -643,5 +654,6 @@ Real OldStyleLDDTHA(EntityView& v, const GlobalRDMap& global_dist_list)
}
return lddt;
}
+*/
}}}
diff --git a/modules/mol/alg/src/local_dist_diff_test.hh b/modules/mol/alg/src/local_dist_diff_test.hh
index 7ed7e46586a6a0becd36c60682176f8a7323f440..3da21cf2195564fcf9e1f8eef96b8cb363f1b3b8 100644
--- a/modules/mol/alg/src/local_dist_diff_test.hh
+++ b/modules/mol/alg/src/local_dist_diff_test.hh
@@ -25,21 +25,35 @@
namespace ost { namespace mol { namespace alg {
-
+/// \brief Contains the infomation needed to uniquely identify an atom in a structure
+///
+/// Used by the the Local Distance Difference Test classes and functions
class UniqueAtomIdentifier
{
public:
+ /// \brief Contstructor with all the relevant information
UniqueAtomIdentifier(const String& chain,const ResNum& residue,const String& residue_name, const String& atom): chain_(chain),residue_(residue),residue_name_(residue_name),atom_(atom) {}
// to make the compiler happy (boost python map suite)
UniqueAtomIdentifier(): chain_(""),residue_(ResNum(1)),residue_name_(""),atom_("") {}
-
+
+ /// \brief Returns the name of the chain to which the atom belongs, as a String
String GetChainName() const { return chain_; }
+
+ /// \brief Returns the ResNum of the residue to which the atom belongs
ResNum GetResNum() const { return residue_; }
+
+ /// \brief Returns the name of the residue to which the atom belongs, as a String
String GetResidueName() const { return residue_name_; }
+
+ /// \brief Returns the name of the atom, as a String
String GetAtomName() const { return atom_; }
+
+ // required because UniqueAtomIdentifier is used as a key for a std::map
bool operator==(const UniqueAtomIdentifier& rhs) const;
+
+ // required because UniqueAtomIdentifier is used as a key for a std::map
bool operator<(const UniqueAtomIdentifier& rhs) const;
private:
@@ -50,35 +64,92 @@ private:
String atom_;
};
+// typedef used to make the code cleaner
typedef std::pair<UniqueAtomIdentifier,UniqueAtomIdentifier> UAtomIdentifiers;
+
+/// \brief Residue distance list.
+///
+/// Container for all the interatomic distances that are checked in a Local Distance Difference Test
+/// and are originating from a single specific residue
typedef std::map<std::pair<UniqueAtomIdentifier,UniqueAtomIdentifier>,std::pair<float,float> > ResidueRDMap;
+
+/// \brief Global distance list.
+///
+/// Container for all the residue-based interatomic distance lists that are checked in a Local Distance Difference Test
+/// and belong to the same structure
typedef std::map<ost::mol::ResNum,ResidueRDMap> GlobalRDMap;
+
+// used by the multi-reference distance-list generator function
typedef std::map<UniqueAtomIdentifier,int> ExistenceMap;
+/// \brief Calculates number of distances conserved in a model, given a list of distances to check and a model
+///
+/// Calculates the two values needed to determine the Local Distance Difference Test for a given model, i.e.
+/// the number of conserved distances in the model and the number of total distances in the reference structure.
+/// 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.
+///
+/// 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
+/// int properties named <string>_conserved and <string>_total.
std::pair<long int,long int> DLLEXPORT_OST_MOL_ALG LocalDistDiffTest(const EntityView& mdl,
const GlobalRDMap& dist_list,
std::vector<Real> cutoff_list,
const String& local_ldt_property_string="");
+/// \brief Calculates the Local Distance Difference Score for a given model with respect to a given target
+///
+/// Calculates the Local Distance Difference Test score for a given model with respect to a given reference structure. Requires
+/// 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.
+///
+/// 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
+/// int properties named <string>_conserved and <string>_total.
Real DLLEXPORT_OST_MOL_ALG LocalDistDiffTest(const EntityView& mdl,
const EntityView& target,
Real cutoff_list,
Real max_dist,
const String& local_ldt_property_string="");
-
+/// \brief Calculates the Local Distance Difference Test score for a given model starting from an alignment between a reference structure and the model.
+///
+/// Calculates the Local Distance Difference Test score given an alignment between a model and a taget structure.
+/// Requires a threshold on which to calculate the score and an inclusion radius to determine the interatiomic
+/// distances to check. BEWARE: This algorithm uses the old version of the Local Distance Difference Test and is
+/// left only for back-compatibility purposes
Real DLLEXPORT_OST_MOL_ALG LocalDistDiffTest(const ost::seq::AlignmentHandle& aln,
Real cutoff, Real max_dist,
int ref_index=0, int mdl_index=1);
-
+/// \brief Computes the Local Distance Difference High-Accuracy Test given a list of distances to check
+///
+/// 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
Real DLLEXPORT_OST_MOL_ALG LDDTHA(EntityView& v, const GlobalRDMap& global_dist_list);
-Real DLLEXPORT_OST_MOL_ALG OldStyleLDDTHA(EntityView& v, const GlobalRDMap& global_dist_list);
-
+/// \brief Creates a list of distances to check during a Local Difference Distance Test
+///
+/// Requires a reference structure and an inclusion radius
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
+/// 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
GlobalRDMap CreateDistanceListFromMultipleReferences(const std::vector<EntityView>& ref_list,std::vector<Real>& cutoff_list, Real max_dist);
+
+/// \brief Prints all distances in a global distance list to standard output
void PrintGlobalRDMap(const GlobalRDMap& glob_dist_list);
+
+/// \brief Prints all distances in a residue distance list to standard output
void PrintResidueRDMap(const ResidueRDMap& res_dist_list);
+
+// required by some helper function. Cannot reuse similar functions in other modules without creating
+// circular dependencies
bool IsStandardResidue(String rn);
}}}