Skip to content
Snippets Groups Projects
Commit acf8850b authored by Valerio Mariani's avatar Valerio Mariani
Browse files

Ldt documentation part 2: sphinx

parent 5213c066
Branches
Tags
No related merge requests found
Hide whitespace changes
Inline Side-by-side
modules/mol/alg/doc/molalg.rst
+ 359
− 74
View file @ acf8850b
......@@ -4,105 +4,342 @@
.. module:: ost.mol.alg
:synopsis: Algorithms operating on molecular structures
.. function:: LocalDistTest(model, reference, tolerance, radius, local_ldt_property_string="")
.. function:: LocalDistDiffTest(model, reference, tolerance, radius, local_ldt_property_string="")
This function calculates the agreement of local contacts between the model and
the reference structure. The overlap is a number between zero and one, where
one indicates complete agreement, zero indicates no agreement at all. This
score is similar to the GDT, but does not require any superposition of the
model and the reference.
This function calculates the agreement of local contacts between a model and
a reference structure (Local Distance Difference Tests). The overlap is a number
between zero and one, where one indicates complete agreement, zero indicates no
agreement at all. This score is similar to the GDT, but does not require any
superposition between the model and the reference.
The distance of atom pairs in the reference structure that are closer than a
certain distance (radius) to each other is compared to the distance found in
The distance of atom pairs in the reference structure, when shorter than a
certain predefined distance (inclusion radius), is compared with the same distance in
the model. If the difference between these two distances is smaller than a
threshold value (tolerance), the model and the reference agree. Missing atoms
in the model are treated disagreement and thus lower the score.
threshold value (tolerance), the distance is considered conserverd in the model. Missing atoms
in the model lead to non-conserved distances and thus lower the score.
For residue with symmetric sidechains (GLU, ASP, ARG, VAL, PHE, TYR), the
naming of the atoms is ambigous. For these residues, the overlap of both
possible solutions to the fixed atoms, that is, everything that is not
ambigous is calculated. The solution that gives higher overlap is then used to
calculate the actual overlap score.
If a string is passed as last parameter, the function computes the overlap score for
each residue and saves it as a float property in the ResidueHandle, with the passed string
as property name
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 passed as last parameter to the function, the function computes the Local Difference Distance
Test score for each residue and saves it as a float property in the ResidueHandle, with the passed string
as property name. Additionally, the actual residue-based counts of the total checked distances and of
the distances conserved in the model are stored as integer properties in the ResidueHandle. The property
names are respectively <passed string>_total and <passed string>_conserved.
:param model: the model structure
:type model: :class:`~ost.mol.EntityView`
:param reference: the reference structure
:type reference: :class:`~ost.mol.EntityView`
:param tolerance: the tolerance threshold used to determine distance conservation
:param radius: the inclusion radius in Angstroms
:param local_ldt_property_string: the base name for the ResidueHandle properties that store the local scores
:returns: the Local Distance Difference Test score
.. function:: SuperposeFrames(frames, sel, from=0, to=-1, ref=-1)
This function superposes the frames of the given coord group and returns them
as a new coord group.
:param frames: The source coord group.
:type frames: :class:`~ost.mol.CoordGroupHandle`
:param sel: An entity view containing the selection of atoms to be used for
superposition. If set to an invalid view, all atoms in the coord group are
used.
:type sel: :class:`ost.mol.EntityView`
:param from: index of the first frame
:param to: index of the last frame plus one. If set to -1, the value is set to
the number of frames in the coord group
:param ref: The index of the reference frame to use for superposition. If set
to -1, the each frame is superposed to the previous frame.
:returns: A newly created coord group containing the superposed frames.
.. function:: LocalDistDiffTest(model, distance_list, tolerance_list, local_ldt_property_string="")
.. function:: SuperposeFrames(frames, sel, ref_view, from=0, to=-1)
Same as SuperposeFrames above, but the superposition is done on a reference
view and not on another frame of the trajectory.
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
the previous function). It shares the same properties as the previous function, with some differences:
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
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.
: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 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
distances
.. function:: LocalDistDiffTest(alignment, tolerance, radius, ref_index=0, mdl_index=1);
Calculates the Local Distance Difference Test score (see previous functions) 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`
: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 ref_index: index of the reference structure in the alignment
:param mdl_index: index of the model in the alignment
:returns: the Local Distance Difference Test score
.. function:: LDTHA(model, distance_list);
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).
: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`
:returns: the Local Distance Difference Test score
.. function: CreateDistanceList(reference, radius);
.. function: CreateDistanceListFromMultipleReferences(reference_list, radius);
Both these functions create lists of distances to be checked during a Local Distance Difference Test
(see description of the functions above).
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.
: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`
:param radius: inclusion radius (in Angstroms) used to determine the distances included in the list
:param frames: The source coord group.
:type frames: :class:`~ost.mol.CoordGroupHandle`
:param sel: An entity view containing the selection of atoms of the frames to be used for
superposition.
:type sel: :class:`ost.mol.EntityView`
:param ref_view: The reference view on which the frames will be superposed. The number
of atoms in this reference view should be equal to the number of atoms in sel.
:type ref_view: :class:`ost.mol.EntityView`
:param from: index of the first frame
:param to: index of the last frame plus one. If set to -1, the value is set to
the number of frames in the coord group
:returns: class `~ost.mol.alg.GlobalRDMap`
:returns: A newly created coord group containing the superposed frames.
.. class:: UniqueAtomIdentifier
.. autofunction:: ParseAtomNames
Object containing enough information to uniquely identify an atom in a structure
.. autofunction:: MatchResidueByNum
.. method:: UniqueAtomIdentifier(chain,residue_number,residue_name,atom_name)
Creates an UniqueAtomIdentifier object starting from relevant atom information
.. autofunction:: MatchResidueByIdx
:param chain: a string containing the name of the chain to which the atom belongs
:param residue_number: the number of the residue to which the atom belongs
:type residue_number: :class:`~ost.mol.ResNum`
:param residue_name: a string containing the name of the residue to which the atom belongs
:param atom_name: a string containing the name of the atom
.. autofunction:: MatchResidueByLocalAln
.. method:: GetChainName()
.. autofunction:: MatchResidueByGlobalAln
Returns the name of the chain to which the atom belongs, as a String
.. autofunction:: Superpose
.. method:: GetResNum()
Returns the number of the residue the atom belongs to, as a :class:`~ost.mol.ResNum` object
.. method:: GetResidueName()
Returns the name of the residue to which the atom belongs, as a String
.. method:: GetAtomName()
Returns the name of the atom, as a String
.. class:: ResidueRDMap
Dictionary-like object containing the a list of distances that originate from the a single residue residue, to
check during a run of the Local Distance Difference Test algorithm
.. class:: GlobalRDMap
Dictionary-like object containing all the :class:`~ost.mol.alg.ResidueRDMap` objects related to residues
of a single structure
.. function: PrintResidueRDMap(residue_distance_list)
Prints to standard output all the distances contained in a :class:`~ost.mol.ResidueRDMap` object
.. function: PrintGlobalRDMap(global_distance_list)
Prints to standard output all the distances contained in each of the :class:`~ost.mol.ResidueRDMap` objects that
make up a :class:`~ost.mol.GlobalRDMap` object
.. _steric-clashes:
Steric Clashes
--------------------------------------------------------------------------------
The following function detects steric clashes in atomic structures. Two atoms are clashing if their euclidian distance is smaller than a threshold value. The threshold values are calculated from high-resolution X-ray structures for each possible element pair. The value is chosen such that 99.99% of observed distances between 0 and 5 Angstroem are above the threshold.
The following function detects steric clashes in atomic structures. Two atoms are clashing if their euclidian distance is smaller than a threshold value (minus a tolerance offset).
.. function:: FilterClashes(entity, clashing_distances, always_remove_bb=False)
.. function:: FilterClashes(ent, tolerance=0.0)
This function filters out residues with non-bonded clashing atoms. If the clashing atom
is a backbone atom, the complete residue is removed from the structure, if the atom is part of
the sidechain, only the sidechain atoms are removed. This behavior is changed
by the always_remove_bb flag: when the flag is set to True the whole residue is removed even if
a clash is just detected in the side-chain.
Two atoms are defined as clashing if their distance is shorter than the reference distance minus a tolerance
threshold. The information about the clashing distances and the tolerance thresholds for all possible pairs of
atoms is passed to the function as a parameter
This function filters out residues with clashing atoms. If the clashing atom
is a backbone atom, the complete residue is removed, if the atom is part of
the sidechain, only the sidechain atoms are removed.
Hydrogen and deuterium atoms are ignored by this function.
Hydrogen and deuterium atoms are ignored.
:param entity: The input entity
:type entity: :class:`~ost.mol.EntityView` or :class:`~ost.mol.EntityHandle`
:param clashing_distances: information about the clashing distances
:type clashing_distances: :class:`~ost.mol.alg.ClashingDistances`
:param always_remove_bb: if set to True, the whole residue is removed even if the clash happens in the side-chain
:returns: The filtered :class:`~ost.mol.EntityView`
.. function:: CheckStereoChemistry(entity,bond_stats,angle_stats,bond_tolerance,angle_tolerance,always_remove_bb=False)
This function filters out residues with severe stereo-chemical violations. If the violation
involves a backbone atom, the complete residue is removed from the structure, if it involves an atom that is
part of the sidechain, only the sidechain is removed. This behavior is changed
by the always_remove_bb flag: when the flag is set to True the whole residue is removed even if
a violation is just detected in the side-chain
:param ent: The input entity
:type ent: :class:`~ost.mol.EntityView` or :class:`~ost.mol.EntityHandle`
:param tolerance: The tolerance in (Angstroem) is substracted from the
thresholds calculated from high resolution X-ray structures to make the
function less pedantic. Negative values are also allowed and make the
function more stringent.
A violation is defined as a bond length that lies outside of the range: [mean_length-std_dev*bond_tolerance <-> meanlength+std_dev*bond_tolerance] or an angle width lying outside of the range [mean_width-std_dev*angle_tolerance <-> mean_width+std_dev*angle_tolerance ]. The information about the mean lengths and widths and the corresponding standard deviations is passed to the function using two parameters.
Hydrogen and deuterium atoms are ignored by this function.
:param entity: The input entity
:type entity: :class:`~ost.mol.EntityView` or :class:`~ost.mol.EntityHandle`
:param bond_stats: statistics about bond lengths
:type bond_stats: :class:`~ost.mol.alg.StereoChemicalParams`
:param angle_stats: statistics about angle widths
:type angle_stats: :class:`~ost.mol.alg.StereoChemicalParams`
:param bond_tolerance: tolerance for bond lengths (in standard deviations)
:param angle_tolerance: tolerance for angle widths (in standard deviations)£
:param always_remove_bb: if set to True, the whole residue is removed even if a violation in just detected in the side-chain
:returns: The filtered :class:`~ost.mol.EntityView`
.. class:: ClashingDistances
Object containing information about clashing distances between non-bonded atoms
.. method:: ClashingDistances()
Creates an empty distance list
.. method:: SetClashingDistance(ele1,ele2, clash_distance, tolerance)
Adds or replaces an entry in the list
:param ele1: string containing the first element's name
:param ele2: string containing the second element's name
:param clash_distance: minimum clashing distance (in Angstroms)
:param tolerance: tolerance threshold (in Angstroms)
.. method GetClashingDistance()
Recovers a reference distance and a tolerance threshold from the list
:param ele1: string containing the first element's name
:param ele2: string containing the second element's name
:returns: a tuple containing the minimum clashing distance and the tolerance threshold
.. method:: GetMaxAdjustedDistance()
Returns the longest clashing distance in the list, after adjustment with tolerance threshold
.. method:: IsEmpty()
Returns True if the list is empty (i.e. in an invalid, useless state)
.. method:: PrintAllDistances()
Prints all distances in the list to standard output
.. class:: StereoChemicalParams
Object containing stereo-chemical information about bonds and angles. For each item (bond or angle
in a specific residue), stores the mean and standard deviation
.. method:: StereoChemicalParams()
Creates an empty parameter list
.. method:: SetParam(item, residue, mean, standard_dev)
Adds or replaces an entry in the list
:param item: string defining a bond (format: X-Y) or an angle (format:X-Y-Z), where X,Y an Z are atom names
:param residue: string containing the residue type the information pertains to
:param mean: mean bond length or angle width
:param standard_dev: standard deviation of the bond length or of the angle width
.. method GetParam(item,residue)
Recovers an entry from the list,
:param item: string defining a bond (format: X-Y) or an angle (format:X-Y-Z), where X,Y an Z are atom names
:param residue: string containing the residue type the item information pertains to
:returns: a tuple containing the mean length or width and the standard deviation
.. method ContainsParam(item,residue)
Checks if a specific entry is present in the list
:param item: string defining a bond (format: X-Y) or an angle (format:X-Y-Z), where X,Y an Z are atom names
:param residue: string containing the residue type the information pertains to
:returns: True if the list contains an entry corresponding to the correct item and residue, False if it does not
.. method:: IsEmpty()
Returns True if the list is empty (i.e. in an invalid, useless state)
.. method:: PrintAllParameters()
Prints all distances in the list to standard output
.. function:: FillClashingDistances(file_content)
.. function:: FillBondStereoChemicalParams(file_content)
.. function:: FillAngleStereoChemicalParams(file_content)
These three functions fill a list of reference clashing distances, a list of stereo-chemical parameters for
bonds and a list of stereo-chemical parameters for angles, respectively, starting from a the content of
parameter file. The content of the file is passed to the function as a list of strings, each containing
a line from the parameter file
:returns: :class:`~ost.mol.alg.ClashingDistances` and :class:`~ost.mol.alg.StereoChemicalParams` respectively
.. function:: FillClashingDistancesFromFile(filename)
.. function:: FillBondStereoChemicalParamsFromFile(filename)
.. function:: FillAngleStereoChemicalParamsFromFile(filename)
These three functions fill a list of reference clashing distances, a list of stereo-chemical parameters for
bonds and a list of stereo-chemical parameters for angles, respectively, starting from a file. The filename
passed to the function can be a full path.
:returns: :class:`~ost.mol.alg.ClashingDistances` and :class:`~ost.mol.alg.StereoChemicalParams` respectively
.. function:: DefaultClashingDistances()
.. function:: DefaultBondStereoChemicalParams()
.. function:: DefaultAngleStereoChemicalParams()
These three functions fill a list of reference clashing distances, a list of stereo-chemical parameters for
bonds and a list of stereo-chemical parameters for angles, respectively, using the default parameter file
distributed with OpenStructure.
:returns: :class:`~ost.mol.alg.ClashingDistances` and :class:`~ost.mol.alg.StereoChemicalParams` respectively
.. _traj-analysis:
......@@ -230,8 +467,6 @@ used to skip frames in the analysis.
:param stride: Size of the increment of the frame's index between two
consecutive frames analyzed.
.. function:: AnalyzeMinDistance(traj, view1, view2, stride=1)
This function extracts the minimal distance between two sets of atoms
......@@ -278,3 +513,53 @@ used to skip frames in the analysis.
:param stride: Size of the increment of the frame's index between two
consecutive frames analyzed.
.. function:: SuperposeFrames(frames, sel, from=0, to=-1, ref=-1)
This function superposes the frames of the given coord group and returns them
as a new coord group.
:param frames: The source coord group.
:type frames: :class:`~ost.mol.CoordGroupHandle`
:param sel: An entity view containing the selection of atoms to be used for
superposition. If set to an invalid view, all atoms in the coord group are
used.
:type sel: :class:`ost.mol.EntityView`
:param from: index of the first frame
:param to: index of the last frame plus one. If set to -1, the value is set to
the number of frames in the coord group
:param ref: The index of the reference frame to use for superposition. If set
to -1, the each frame is superposed to the previous frame.
:returns: A newly created coord group containing the superposed frames.
.. function:: SuperposeFrames(frames, sel, ref_view, from=0, to=-1)
Same as SuperposeFrames above, but the superposition is done on a reference
view and not on another frame of the trajectory.
:param frames: The source coord group.
:type frames: :class:`~ost.mol.CoordGroupHandle`
:param sel: An entity view containing the selection of atoms of the frames to be used for
superposition.
:type sel: :class:`ost.mol.EntityView`
:param ref_view: The reference view on which the frames will be superposed. The number
of atoms in this reference view should be equal to the number of atoms in sel.
:type ref_view: :class:`ost.mol.EntityView`
:param from: index of the first frame
:param to: index of the last frame plus one. If set to -1, the value is set to
the number of frames in the coord group
:returns: A newly created coord group containing the superposed frames.
.. autofunction:: ParseAtomNames
.. autofunction:: MatchResidueByNum
.. autofunction:: MatchResidueByIdx
.. autofunction:: MatchResidueByLocalAln
.. autofunction:: MatchResidueByGlobalAln
.. autofunction:: Superpose
modules/mol/alg/src/filter_clashes.hh
+ 1
− 0
View file @ acf8850b
......@@ -100,6 +100,7 @@ ClashingDistances DLLEXPORT_OST_MOL_ALG FillClashingDistances(std::vector<String
/// \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
/// The header can be 'Bonds' to read bond statistics or 'Angles' to read angle statistics
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
......
modules/mol/alg/src/local_dist_diff_test.hh
+ 8
− 4
View file @ acf8850b
......@@ -32,7 +32,7 @@ class UniqueAtomIdentifier
{
public:
/// \brief Contstructor with all the relevant information
/// \brief Constructor 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)
......@@ -110,15 +110,19 @@ std::pair<long int,long int> DLLEXPORT_OST_MOL_ALG LocalDistDiffTest(const Entit
/// int properties named <string>_conserved and <string>_total.
Real DLLEXPORT_OST_MOL_ALG LocalDistDiffTest(const EntityView& mdl,
const EntityView& target,
Real cutoff_list,
Real cutoff,
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
/// distances to check. Obviously, the strucvtures of the model and the reference must be attached to the alignment.
/// By default the first structure in the alignment is considered the reference and the second is considered the
/// model, but this can be changed by passing to the function the indexes of the two structures in the ref_index
/// and mdl_index parameters.
/// BEWARE: This algorithm uses the old version of the Local Distance Difference Test
/// (multiple cycles, single threshold, etc. ) and will give a slightly different result than the other functions
Real DLLEXPORT_OST_MOL_ALG LocalDistDiffTest(const ost::seq::AlignmentHandle& aln,
Real cutoff, Real max_dist,
int ref_index=0, int mdl_index=1);
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment