From b92f44ba27845754bc4a7868e0a587d6acb38313 Mon Sep 17 00:00:00 2001 From: Marco Biasini <marco.biasini@unibas.ch> Date: Mon, 5 Nov 2012 12:59:42 +0100 Subject: [PATCH] documentation for lddt executable Mainly written by Valerio, with a few tweaks by me --- modules/index.rst | 3 + modules/mol/alg/doc/lddt.rst | 158 +++++++++++++++++++++++++++++++++++ 2 files changed, 161 insertions(+) create mode 100644 modules/mol/alg/doc/lddt.rst diff --git a/modules/index.rst b/modules/index.rst index cb92f375d..5f043a238 100644 --- a/modules/index.rst +++ b/modules/index.rst @@ -28,6 +28,7 @@ OpenStructure documentation external contributing table + mol/alg/lddt For Starters -------------------------------------------------------------------------------- @@ -99,6 +100,8 @@ Varia **Users** :doc:`Reporting a problem <users>` +**lDDT** :doc:`lDDT command line executable<mol/alg/lddt>` + Extending OpenStructure -------------------------------------------------------------------------------- diff --git a/modules/mol/alg/doc/lddt.rst b/modules/mol/alg/doc/lddt.rst new file mode 100644 index 000000000..4e36560f4 --- /dev/null +++ b/modules/mol/alg/doc/lddt.rst @@ -0,0 +1,158 @@ + +=========================== +How to use the lDDT program +=========================== + +----------- +Basic Usage +----------- + +To calculate the lDDT for two PDB files (mdl1.pdb and mdl2.pdb) against the reference structure stored in ref.pdb, use the following command: + +.. code-block:: bash + + lddt mdl1.pdb mdl2.pdb ref.pdb + +The local and global lDDT scores for each model are printed to the terminal. + +-------------------- +Model Quality Checks +-------------------- + +When the lddt executable is called with the -f option, the program performs some +stereo-chemical and steric clashing checks before computing the lDDT scores. When +using this option, the user must also provide a text file containing average bond +lengths,angle widths and minimum clashing distances. lddt ships with a default +parameter file based on Engh and Huber parameters, and on the atomic radii as +defined in the Cambridge Structural Database. This file is human readable and can +be modified with a text editor. The location of the file must be passed to the +lddt executable using the -p parameter. + +For example: + +.. code-block:: bash + + lddt -f -p stereo_chemical_params.txt mdl1.pdb mdl2.pdb ref.pdb + +When the model quality checks are performed, the global and local lDDT scores are +preceded in the output text by some information on the outcome of the tests. The +number of serious stereo-chemical violations and steric-clashes in the structure +is reported, along with some statistics on the global model quality. The local and +global lDDT scores are also adjusted according to the outcome of the tests. When +stereochemical violations or steric clashes happen in the side-chain of a residue, +all distances involving atoms of that side-chain are automatically considered +non-conserved. When the violations involve backbone atoms of a residue, all +distances containing atoms of the residue are considered non-conserved. + + +----------------------- +Custom Inclusion Radius +----------------------- + +The lDDT score evaluates distances between atoms lying closer than a predermined +inclusion radius. By default the radius is set to 15 Angstroms, but the user can +override this value by passing a new one to the lddt executable through the -r +parameter (in Angstroms): + +For example: + +.. code-block:: bash + + lddt -r 10.0 mdl1.pdb mdl2.pdb ref.pdb + +------------------ +Consistency Checks +------------------ + +When comparing structures, the lddt executable does not perform any chain name +checks. It only processes the first chain in each structure, irrespective of the +name. It does, however, perform a check on residue names, to make sure that the +structures are correctly aligned. The lddt executable will stop with an error if +the names of the residues being compared do not match. If the user needs for +specific reasons to override this behavior and skip the check, the lddt executable +can be called using the -x option. For example: + +For example: + +.. code-block:: bash + + lddt -x mdl1.pdb mdl2.pdb ref.pdb + +------------------------- +Custom Quality Parameters +------------------------- + +The lddt executable uses several thresholds to determine how serious stereo- +chemical violations and steric clashes are. For Bonds and Angles, the parameter +file contains typical average lengths and widths, together with expected standard +deviations for their measurements in protein structures. A violation is flagged as +serious by lDDT when the measured value deviates from the expected one by more +than a predefined number of standard deviations. By default this value is 12, but +the user can override the default tolerance thresholds using the -b and -a flags, +for bonds and angles respectively. + +For steric clashes, the lddt executable recovers atomic radii and clashing +tolerance distances from the parameter file, depending on the atomic element under +investigation. When an atomic element cannot be determined, the lddt executable +uses a default atomic radius of 1.5 Angstrom. This value can be overriden using +the -m value, passing a new radius (in Ansgstroms) to the program. + +For example: + +.. code-block:: bash + + lddt -f -p stereo_chemical_params.txt -b 8 -a 8 -m 1.0 mdl1.pdb ref.pdb + + + +----------------------------- +Multiple Reference Structures +----------------------------- + +lDDT allows the use of multiple reference structures at the same time (please see +the manuscript referenced above for details). In order to use multiple references, +simply add them to the first ref.pdb file, separated by a comma. + +For example: + +.. code-block:: bash + + lddt mdl1.pdb mdl2.pdb ref1.pdb,ref2.pdb,ref3.pdb + +---------------- +Output Verbosity +---------------- + +By default the lddt executable only outputs the values of the global and local +scores. However, users can tweak the verbosity of the output using the -v +parameters. The devault verbosity level is 0 (scores only). Other available +levels are: 1 (print information about non conserved distances and failed +quality checks, if performed) and 2 (print information on all distances and +all quality checks if performed) + +For example: + +.. code-block:: bash + + lddt -v 1 -f -p stereo_chemical_params.txt mdl1.pdb mdl2.pdb ref.pdb + +WARNING: Verbosity levels 1 and 2 can generate a large amount of output text, +especially with large structures and multiple models being evaluated. + + + + +------------- +Other Options +------------- + +The lddt executable supports several other command line options. Some can be used +to select subsets of atoms in the input structures, others to exclude from the +calculation distances between residues that are too close in the amino-acid chain, +and many more. In order to see a complete list, just call the program without any +input parameters. + +.. code-block:: bash + + lddt + -- GitLab