lDDT (deprecated)

Warning

These functions in ost.mol.alg are deprecated. Consider using the newer implementation in ost.mol.alg.lDDTScorer instead.

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.

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.

Parameters:

• model (EntityView) – the model structure

• distance_list (GlobalRDMap) – the list of distances to check for conservation

• tolerance_list – a list of thresholds used to determine distance conservation

• sequence_separation – sequence separation parameter used when computing the score

• 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

LocalDistDiffTest(model, reference_list, distance_list, settings)

Wrapper around LocalDistDiffTest() above.

Parameters:

• model (EntityView) – the model structure

• reference_list (list of EntityView) – the list of reference structures from which distances were derived

• distance_list (GlobalRDMap) – A residue distance map prepared with PreparelDDTGlobalRDMap() with reference_list and settings as parameters.

• settings (lDDTSettings) – lDDT settings

Returns:

the Local Distance Difference Test score (conserved distances divided by all the checked distances)

Return type:

float

LocalDistDiffTest(model, target, cutoff, max_dist, local_lddt_property_string='')

Wrapper around LocalDistDiffTest() above using: distance_list = CreateDistanceList() with target and max_dist as parameters and tolerance_list = [cutoff].

Parameters:

• model (EntityView) – the model structure

• target (EntityView) – the target structure from which distances are derived

• cutoff (float) – single distance threshold to determine distance conservation

• max_dist (float) – the inclusion radius in Angstroms (to determine which distances are checked for conservation)

• 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)

Return type:

float

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.

Note

This function uses the old implementation of the Local Distance Difference Test algorithm and will give slightly different results from the new one.

Parameters:

• alignment (AlignmentHandle) – an alignment containing the sequences of the reference and of the model structures, with the structures themselves attached

• tolerance – a list of thresholds used to determine distance conservation

• radius – the inclusion radius in Angstroms (to determine which distances are checked for conservation)

• ref_index – index of the reference structure in the alignment

• mdl_index – index of the model in the alignment

Returns:

the Local Distance Difference Test score

LDDTHA(model, distance_list, sequence_separation=0)

This function calculates the Local Distance Difference Test, using the same threshold values as the GDT-HA test (the default set of thresholds used for the lDDT score) (See previous functions). The thresholds are 0.5, 1, 2, and 4 Angstroms.

The function only compares the input distance list to the first chain of the model structure.

The local residue-based lDDT score values are stored in the ResidueHandles of the model passed to the function in a float property called “locallddt”.

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.

Parameters:

• model (EntityView) – the model structure

• distance_list (GlobalRDMap) – the list of distances to check for conservation

• sequence_separation – sequence separation parameter

Returns:

the Local Distance Difference Test score

DistanceRMSDTest(model, distance_list, cap_difference, sequence_separation=0, local_drmsd_property_string='')

This function performs a Distance RMSD Test on a provided model, and calculates the two values that are necessary to determine the Distance RMSD Score, namely the sum of squared distance deviations and the number of distances on which the sum was computed.

The Distance RMSD Test (or DRMSD Test) computes the deviation in the length of local contacts between a model and a reference structure and expresses it in the form of a score value. The score has an an RMSD-like form, with the deviations in the RMSD formula computed as contact distance differences. The score is open-ended, with a value of zero meaning complete agreement of local contact distances, and a positive value revealing a disagreement of magnitude proportional to the score value itself. This score does not require any superposition between the model and the reference.

This function processes a list of distances provided by the user, together with their length in the reference structure. For each distance that is found in the model, its difference with the reference length is computed and used as deviation term in the RMSD-like formula.When a distance is not present in the model because one or both the atoms are missing, a default deviation value provided by the user is used.

The function only processes distances between atoms that do not belong to the same residue, and considers only standard residues in the first chain of the model. For residues with symmetric sidechains (GLU, ASP, ARG, VAL, PHE, TYR), the naming of the atoms is ambiguous. For these residues, the function computes the Distance RMSD Test score that each naming convention would generate when considering all non-ambiguous surrounding atoms. The solution that gives the lower score is then picked to compute the final Distance RMSD 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 passed as last parameter to the function, the function computes the Distance RMSD Score for each residue and saves it as a float property in the ResidueHandle, with the passed string as property name. Additionally, the actual sum of squared deviations and the number of distances on which it was computed are stored as properties in the ResidueHandle. The property names are respectively <passed string>_sum (a float property) and <passed string>_count (an integer property).

Parameters:

• model (EntityView) – the model structure

• distance_list (GlobalRDMap) – the list of distances to check (here we only use the first of the two distance values stored, the second is ignored)

• cap_difference – a default deviation value to be used when a distance is not found in the model

• sequence_separation – sequence separation parameter

• local_ldt_property_string – the base name for the ResidueHandle properties that store the local scores

Returns:

a tuple containing the sum of squared distance deviations, and the number of distances on which it was computed.

DRMSD(model, distance_list, cap_difference, sequence_separation=0)

This function calculates the Distance RMSD Test score (see DistanceRMSDTest()).

The function only considers distances between atoms not belonging to the same residue, and only compares the input distance list to the first chain of the model structure. It requires, in addition to the model and the list themselves, a default deviation value to be used in the DRMSD Test when a distance is not found in the model.

The local Local Distance Difference Test score values are stored in the ResidueHandles of the model passed to the function in a float property called “localdrmsd”.

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.

Parameters:

• model (EntityView) – the model structure

• distance_list (GlobalRDMap) – the list of distances as in DistanceRMSDTest()

• cap_difference – a default deviation value to be used when a distance is not found in the model

• sequence_separation – sequence separation parameter

Returns:

the Distance RMSD Test score

CreateDistanceList(reference, radius)

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).

Note

These 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 prepared before being passed to the function. Corresponding residues in the structures must have the same residue number, the same chain name, etc. Gaps are allowed and automatically dealt with: if information about a distance is present in at least one of the structures, it will be considered.

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 ambiguous symmetric sidechains. To decide which naming convention to use, the function computes a Local Distance Difference Test score foreach reference against the first reference structure in the list, using only non ambiguously-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.

Parameters:

• reference (EntityView) – a reference structure from which distances are derived

• reference_list (list of EntityView) – a list of reference structures from which distances are derived

• tolerance_list – a list of thresholds used to determine distance conservation when computing the lDDT score

• sequence_separation – sequence separation parameter used when computing the lDDT score

• radius – inclusion radius (in Angstroms) used to determine the distances included in the list

Returns:

GlobalRDMap

PreparelDDTGlobalRDMap(reference_list, cutoff_list, sequence_separation, max_dist)

A wrapper around CreateDistanceList() and CreateDistanceListFromMultipleReferences(). Depending on the length of the reference_list it calls one or the other.

Parameters:

• reference_list (list of EntityView) – a list of reference structures from which distances are derived

• max_dist (float) – the inclusion radius in Angstroms (to determine which distances are checked for conservation)

• sequence_separation (int) – sequence separation parameter ie. maximum distance between two sequences.

Returns:

GlobalRDMap

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 the passed reference_list list.

Parameters:

reference_list (list of EntityView) – A list of reference structures from which distances are derived

GetlDDTPerResidueStats(model, distance_list, structural_checks, label)

Get the per-residue statistics from the lDDT calculation.

Parameters:

• model (EntityHandle) – The model structure

• distance_list (GlobalRDMap) – The list of distances to check for conservation

• structural_checks (bool) – Were structural checks performed on the model?

• label (str) – Label used for ResidueHandle properties that store the local scores.

Returns:

Per-residue local lDDT scores

Return type:

list of lDDTLocalScore

PrintlDDTPerResidueStats(scores, structural_checks, cutoffs_length)

Print per-residue statistics from lDDT calculation.

Parameters:

• scores (list of lDDTLocalScore) – Local lDDT scores

• structural_checks (bool) – Where structural checks performed on the model?

• cutoffs_length (int) – Length of the cutoffs list used to calculate lDDT

class lDDTLocalScore(cname, rname, rnum, is_assessed, quality_problems, local_lddt, conserved_dist, total_dist)

Object containing per-residue information about calculated lDDT.

Parameters:

• cname – Sets cname

• rname – Sets rname

• rnum – Sets rnum

• is_assessed – Sets is_assessed

• quality_problems – Sets quality_problems

• local_lddt – Sets local_lddt

• conserved_dist – Sets conserved_dist

• total_dist – Sets total_dist

cname

Chain name.

Type:

str

rname

Residue name.

Type:

str

rnum

Residue number.

Type:

int

is_assessed

Is the residue taken into account? Yes or No.

Type:

str

quality_problems

Does the residue have 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:

str

local_lddt

Local lDDT score for residue.

Type:

float

conserved_dist

Number of conserved distances.

Type:

int

total_dist

Total number of distances.

Type:

int

ToString(structural_checks)

Returns:

String representation of the lDDTLocalScore object.

Return type:

str

Parameters:

structural_checks (bool) – Where structural checks applied during calculations?

GetHeader(structural_checks, cutoffs_length)

Get the names of the fields as printed by ToString method.

Parameters:

• structural_checks (bool) – Where structural checks applied during calculations?

• cutoffs_length (int) – Length of the cutoffs list used for calculations

class UniqueAtomIdentifier(chain, residue_number, residue_name, atom_name)

Object containing enough information to uniquely identify an atom in a structure.

Parameters:

• chain – A string containing the name of the chain to which the atom belongs

• residue_number (ResNum) – The number of the residue to which the atom belongs

• residue_name – A string containing the name of the residue to which the atom belongs

• atom_name – A string containing the name of the atom

GetChainName()

Returns the name of the chain to which the atom belongs, as a String

GetResNum()

Returns the number of the residue the atom belongs to, as a ResNum object

GetResidueName()

Returns the name of the residue to which the atom belongs, as a String

GetAtomName()

Returns the name of the atom, as a String

GetQualifiedAtomName()

Returns the qualified name of the atom (the chain name, followed by a unique residue identifier and the atom name. For example: “A.GLY2.CA”)

class ResidueRDMap

Dictionary-like object containing the list of interatomic distances that originate from a single residue to be checked during a run of the Local Distance Difference Test algorithm (key = pair of UniqueAtomIdentifier, value = pair of floats representing min and max distance observed in the structures used to build the map).

class GlobalRDMap

Dictionary-like object containing all the ResidueRDMap objects related to all the residues (key = ResNum, value = ResidueRDMap).

PrintResidueRDMap(residue_distance_list)

Prints to standard output all the distances contained in a ResidueRDMap object.

PrintGlobalRDMap(global_distance_list)

Prints to standard output all the distances contained in each of the ResidueRDMap objects that make up a GlobalRDMap object.