From 7960631ebcda0c740950a5121f2674d06b4fe85d Mon Sep 17 00:00:00 2001
From: Gabriel Studer <gabriel.studer@unibas.ch>
Date: Sat, 24 Nov 2018 09:41:22 +0100
Subject: [PATCH] docu updates
---
core/doc/geometry.rst | 2 +-
doc/references.rst | 18 +++++++++++----
loop/doc/backbone.rst | 7 +++---
loop/doc/load_loop_objects.rst | 14 ++++--------
loop/doc/structure_db.rst | 33 ++++++++++++++-------------
modelling/doc/loop_closing.rst | 2 +-
scoring/doc/backbone_score_env.rst | 3 ---
sidechain/doc/graph.rst | 2 +-
sidechain/doc/index.rst | 2 +-
sidechain/doc/loading.rst | 5 ++--
sidechain/doc/rotamer.rst | 4 ++--
sidechain/doc/rotamer_constructor.rst | 2 +-
sidechain/doc/rotamer_lib.rst | 2 +-
13 files changed, 50 insertions(+), 46 deletions(-)
diff --git a/core/doc/geometry.rst b/core/doc/geometry.rst
index 3d36b1bd..a17ed803 100644
--- a/core/doc/geometry.rst
+++ b/core/doc/geometry.rst
@@ -53,7 +53,7 @@ Geometry functions
.. function:: ConstructCBetaPos(n_pos, ca_pos, c_pos)
Constructs position of C-beta atom given the positions of the backbone nitrogen,
- C-alpha and c atoms.
+ C-alpha and C atoms.
:param n_pos: Position of nitrogen atom
:type n_pos: :class:`~ost.geom.Vec3`
diff --git a/doc/references.rst b/doc/references.rst
index b5583344..60baa19c 100644
--- a/doc/references.rst
+++ b/doc/references.rst
@@ -14,10 +14,19 @@ References
A graph-theory algorithm for rapid protein side-chain
prediction. Protein Sci.
+.. [coutsias2005] Coutsias EA, Seok C, Wester MJ, Dill KA (2005).
+ Resultants and loop closure. International Journal of Quantum
+ Chemistry.
+
+
.. [chakravarty1999] Chakravarty S, Varadarajan R (1999).
Residue depth: a novel parameter for the analysis of
protein structure and stability. Structure.
+.. [davis2006] Davis IW, Arendall WB, Richardson DC, Richardson JS (2006).
+ The backrub motion: how protein backbone shrugs when a sidechain
+ dances. Structure.
+
.. [goldstein1994] Goldstein RF (1994).
Efficient rotamer elimination applied to protein side-chains
and related spin glasses. Biophys J.
@@ -41,10 +50,6 @@ References
.. [lovell2000] Lovell SC, Word JM, Richardson JS, Richardson DC (2000).
The penultimate rotamer library. Proteins.
-.. [mandell2009] Mandell DJ, Coutsias EA and Kortemme T (2009).
- Sub-angstrom accuracy in protein loop reconstruction by
- robotics-inspired conformational sampling. Nat Methods.
-
.. [shapovalov2011] Shapovalov MV and Dunbrack RL Jr. (2011).
A smoothed backbone-dependent rotamer library for proteins
derived from adaptive kernel density estimates and
@@ -54,6 +59,11 @@ References
Protein homology detection by HMM-HMM comparison.
Bioinformatics.
+
+.. [solis2006] Solis AD, Rackovsky S (2006). Improvement of statistical
+ potentials and threading score functions using information
+ maximization. Proteins.
+
.. [zhou2005] Zhou H, Zhou Y (2005).
Fold Recognition by Combining Sequence Profiles Derived From
Evolution and From Depth-Dependent Structural Alignment of
diff --git a/loop/doc/backbone.rst b/loop/doc/backbone.rst
index 15288fb3..90209e98 100644
--- a/loop/doc/backbone.rst
+++ b/loop/doc/backbone.rst
@@ -143,7 +143,8 @@ The BackboneList class
:type sequence: :class:`str`
:raises: :exc:`~exceptions.RuntimeError` if *sequence* contains a one letter
- code which is not one of the 20 default amino acids.
+ code which is not one of the 20 default amino acids or size of
+ *sequence* does not match.
.. method:: Extract(from, to)
@@ -450,8 +451,8 @@ The BackboneList class
.. method:: SetBackrub(index, primary_rot_angle, flanking_rot_angle_one, flanking_rot_angle_two)
- Applies a backrub motion at residue defined by **index**. The first
- rotation axis is defined by the CA positions from residues at
+ Applies a backrub motion [davis2006]_ at residue defined by **index**.
+ The first rotation axis is defined by the CA positions from residues at
**index** -1 and **index** +1. All atoms in between get rotated around this
axis by **primary_rot_angle**. To restore the the hydrogen bond network
of the two transformed oxygens, the backrub motion gets completed by
diff --git a/loop/doc/load_loop_objects.rst b/loop/doc/load_loop_objects.rst
index 81d016b8..07596175 100644
--- a/loop/doc/load_loop_objects.rst
+++ b/loop/doc/load_loop_objects.rst
@@ -10,7 +10,7 @@ Several data objects are used throughout the loop module.
.. method:: LoadTorsionSampler(seed=0)
Loads and returns a torsion sampler with an amino acid grouping
- as defined by Solis & Rachovsky [1] that has been trained on
+ as defined by [solis2006]_ that has been trained on
non-redundant protein structures.
:param seed: Seed for internal random number generator
@@ -24,7 +24,7 @@ Several data objects are used throughout the loop module.
.. method:: LoadTorsionSamplerCoil(seed=0)
Loads and returns a torsion sampler with an amino acid grouping
- as defined by Solis & Rachovsky [1] that has been trained on coil
+ as defined by [solis2006]_ that has been trained on coil
residues of non-redundant protein structures.
:param seed: Seed for internal random number generator
@@ -38,7 +38,7 @@ Several data objects are used throughout the loop module.
.. method:: LoadTorsionSamplerHelical(seed=0)
Loads and returns a torsion sampler with an amino acid grouping
- as defined by Solis & Rachovsky [1] that has been trained on helical
+ as defined by [solis2006]_ that has been trained on helical
residues of non-redundant protein structures.
:param seed: Seed for internal random number generator
@@ -52,7 +52,7 @@ Several data objects are used throughout the loop module.
.. method:: LoadTorsionSamplerExtended(seed=0)
Loads and returns a torsion sampler with an amino acid grouping
- as defined by Solis & Rachovsky [1] that has been trained on extended
+ as defined by [solis2006]_ that has been trained on extended
residues of non-redundant protein structures.
:param seed: Seed for internal random number generator
@@ -81,8 +81,4 @@ Several data objects are used throughout the loop module.
:returns: The Fragment database
:rtype: :class:`FragDB`
-
-
-[1] A. D. Solis and S. Rackovsky. Improvement of statistical potentials and
- threading score functions using information maximization.
- Proteins, 62(4):892–908, Mar 2006.
+
\ No newline at end of file
diff --git a/loop/doc/structure_db.rst b/loop/doc/structure_db.rst
index 6728fccf..a5152b7b 100644
--- a/loop/doc/structure_db.rst
+++ b/loop/doc/structure_db.rst
@@ -3,7 +3,7 @@ Structural Data
.. currentmodule:: promod3.loop
-The structural database serves as a container for structural backbone and
+The :class:`StructureDB` serves as a container for structural backbone and
sequence data. Custom accessor objects can be implemented that relate
arbitrary features to structural data. Examples provided by ProMod3 include
accession using matching stem geometry (see: :class:`FragDB`) or sequence
@@ -41,7 +41,7 @@ Defining Chains and Fragments
.. class:: CoordInfo()
The CoordInfo gets automatically generated when new chains are added to
- the structural database. It contains internal information of how a
+ a :class:`StructureDB`. It contains internal information of how a
connected stretch of residues is stored in the database.
.. attribute:: id
@@ -78,7 +78,7 @@ Defining Chains and Fragments
.. class:: FragmentInfo(chain_index, offset, length)
- The FragmentInfo defines any fragment in the structural database. If you
+ The FragmentInfo defines any fragment in the :class:`StructureDB`. If you
implement your own accessor object, thats the information you want to store.
:param chain_index: Fills :attr:`chain_index`
@@ -89,8 +89,8 @@ Defining Chains and Fragments
.. attribute:: chain_index
- The index of the chain (defined by :class:`CoordInfo`) in the structure db
- this particle belongs to. (:class:`int`)
+ The index of the chain (defined by :class:`CoordInfo`) in the
+ :class:`StructureDB` this particle belongs to. (:class:`int`)
.. attribute:: offset
@@ -127,7 +127,7 @@ database, you might want to consider two things:
to backbone coordinates and sequence.
If you want to store all data possible, use All. If you only want a subset,
you can combine some of the datatypes with a bitwise or operation
- (see example script for StructureDB). One important note:
+ (see example script for :class:`StructureDB`). One important note:
If you enable AAFrequenciesStruct, the actual information is not automatically
assigned. Only the according memory is allocated and set to zero, the actual
information must be assigned manually (see example script again...).
@@ -138,8 +138,8 @@ database, you might want to consider two things:
.. class:: StructureDB(data_to_store)
- Generates an empty StructureDB that can be filled with content through
- :func:`AddCoordinates`. The information extracted there is defined by
+ Generates an empty :class:`StructureDB` that can be filled with content
+ through :func:`AddCoordinates`. The information extracted there is defined by
*data_to_store*. Have a look at the :class:`StructureDBDataType`
documentation and at the example script...
@@ -263,7 +263,7 @@ database, you might want to consider two things:
.. method:: GetCoordIdx(id, chain_name)
- :returns: The StructureDB indices (in [0, :meth:`GetNumCoords`-1]) of
+ :returns: The :class:`StructureDB` indices (in [0, :meth:`GetNumCoords`-1])
of all coords (connected stretches) with matching
*id* / *chain_name*.
:rtype: :class:`list` of :class:`int`
@@ -281,7 +281,7 @@ database, you might want to consider two things:
index *idx*.
:rtype: :class:`CoordInfo`
- :param idx: The StructureDB index (in [0, :meth:`GetNumCoords`-1])
+ :param idx: The :class:`StructureDB` index (in [0, :meth:`GetNumCoords`-1])
:type idx: :class:`int`
@@ -379,7 +379,8 @@ database, you might want to consider two things:
.. method:: GetSolventAccessibilitites(fragment)
:returns: Solvent accessibility for each residue of *fragment* in square A
- as calculated by dssp.
+ as calculated by :meth:`~ost.mol.alg.Accessibility` when adding
+ the structure to the database.
:rtype: :class:`list` of :class:`float`
:param fragment: Fragment definition from which to extract the solvent
@@ -472,7 +473,7 @@ database, you might want to consider two things:
to make sure that you have no close homologue in the database.
:rtype: :class:`StructureDB`
- :param indices: StructureDB indices to be added to the sub database (in [0,
+ :param indices: Indices of chains to be added to the sub database (in [0,
:meth:`GetNumCoords`-1])
:type indices: :class:`list`
@@ -605,12 +606,12 @@ This example illustrates how to create a custom FragDB based on a StructureDB:
:param loop_length: The length of the fragments
:type loop_length: :class:`int`
- :returns: True if fragments of given length exist. This function is quick.
+ :returns: True if fragments of given length exist.
:rtype: :class:`bool`
.. method:: MaxFragLength()
- :returns: Maximal fragment length contained in db. This function is quick.
+ :returns: Maximal fragment length contained in db.
:rtype: :class:`int`
.. method:: SearchDB(n_stem, c_stem, frag_size, extra_bins=0)
@@ -642,7 +643,7 @@ In some cases you might want to use the :class:`StructureDB` to search
for fragments that possibly represent the structural conformation of interest.
The :class:`Fragger` searches a :class:`StructureDB` for n fragments,
that maximize a certain score and gathers a set of fragments with a guaranteed
-structural diversity based on an rmsd_threshold. You can use the :class:`Fragger`
+structural diversity based on an rmsd threshold. You can use the :class:`Fragger`
wrapped in a full fletched pipeline implemented in
:class:`~promod3.modelling.FraggerHandle` or search for fragments from scratch
using an arbitrary linear combination of scores:
@@ -889,7 +890,7 @@ The PsipredPrediction class
.. class:: PsipredPrediction
- A container for the secondary structure prediction by Psipred.
+ A container for the secondary structure prediction by PSIPRED [Jones1999]_.
.. method:: PsipredPrediction()
diff --git a/modelling/doc/loop_closing.rst b/modelling/doc/loop_closing.rst
index cc1b1edf..5290137a 100644
--- a/modelling/doc/loop_closing.rst
+++ b/modelling/doc/loop_closing.rst
@@ -7,7 +7,7 @@ Loops often need to undergo conformational changes to fit into gaps defined by
stem residues. |project| implements two algorithms performing this task:
* Cyclic coordinate descent (CCD) [canutescu2003]_
- * Kinematic closure (KIC) [mandell2009]_
+ * Kinematic closure (KIC) [coutsias2005]_
In case of small gaps or small issues in the loop you might also consider the
:class:`BackboneRelaxer`.
diff --git a/scoring/doc/backbone_score_env.rst b/scoring/doc/backbone_score_env.rst
index 2d7b47ef..fa9eb8f4 100644
--- a/scoring/doc/backbone_score_env.rst
+++ b/scoring/doc/backbone_score_env.rst
@@ -200,9 +200,6 @@ Pairwise function classes
:type max_dist: :class:`float`
:type values: :class:`list` of :class:`float`
-
- :returns: Index of added constraint definition
-
:raises: :exc:`~exceptions.RuntimeError` if *min_dist* >= *max_dist* or when
*min_dist* or *max_dist* are negative or when *values* contains no
elements
diff --git a/sidechain/doc/graph.rst b/sidechain/doc/graph.rst
index 118c72ea..76c50cfc 100644
--- a/sidechain/doc/graph.rst
+++ b/sidechain/doc/graph.rst
@@ -6,7 +6,7 @@ Rotamer Graph
Once having a frame representing the rigid parts, the internal energies in
rotamer groups can be calculated. To come to a final solution of the sidechain
modelling problem, the pairwise energies also have to be evaluated and an
-overall solution has to be found. PROMOD3 implements a
+overall solution has to be found. ProMod3 implements a
:class:`promod3.core.GraphMinimizer` that allows to find solutions using
tree decomposition, A* and Monte Carlo algorithms.
diff --git a/sidechain/doc/index.rst b/sidechain/doc/index.rst
index b6425e79..3dab62b7 100644
--- a/sidechain/doc/index.rst
+++ b/sidechain/doc/index.rst
@@ -9,7 +9,7 @@
Tools and algorithms to model sidechains given backbone coordinates. The full
module is heavily based on SCWRL4 [krivov2009]_ . The according paper describes
the modelling of sidechains using two different rotamer models. A rigid model,
-as well as a flexible model. Both models are implemented in PROMOD3 and can be
+as well as a flexible model. Both models are implemented in ProMod3 and can be
applied in flexible ways.
The following code fragment shows an example of a basic sidechain reconstruction
diff --git a/sidechain/doc/loading.rst b/sidechain/doc/loading.rst
index a321ad95..c903f4f6 100644
--- a/sidechain/doc/loading.rst
+++ b/sidechain/doc/loading.rst
@@ -9,9 +9,8 @@ as the 2010 library provided by the Dunbrack lab [shapovalov2011]_.
You can request a licence `here <http://dunbrack.fccc.edu/bbdep2010/>`_
and generate such a library as described in
extras/data_generation/rotamer_library/README. Alternatively, ProMod3
-provides its own backbone dependent library that can be loaded with
-:meth:`LoadBBDepLib`. Also a backbone independent library is available:
-:meth:`LoadLib`.
+provides its own backbone dependent or backbone independent libraries
+that can be loaded with :meth:`LoadBBDepLib` / :meth:`LoadLib`.
.. method:: LoadBBDepLib()
diff --git a/sidechain/doc/rotamer.rst b/sidechain/doc/rotamer.rst
index 40f88232..d0b7604f 100644
--- a/sidechain/doc/rotamer.rst
+++ b/sidechain/doc/rotamer.rst
@@ -7,7 +7,7 @@ A rotamer represents an amino acid sidechain and is basically a set of
:class:`Particle` objects. There exist two types. The :class:`RRMRotamer` and
:class:`FRMRotamer`.
To gather all possible rotamers for one particular sidechain position,
-PROMOD3 offers the :class:`RRMRotamerGroup` and :class:`FRMRotamerGroup`.
+ProMod3 offers the :class:`RRMRotamerGroup` and :class:`FRMRotamerGroup`.
Pairwise interactions between particles give raise to pairwise energies between
rotamers. Nevertheless, the energy calculation itself happens on the level
of RotamerGroups and is mostly hidden away in the construction of the
@@ -264,7 +264,7 @@ Rotamers
The FRMRotamer represents a rotamer of the so called flexible rotamer model,
where one rotamer gets represented by several subrotamers.
- The idea is, that all particles of all subrotamers are given at
+ The idea is that all particles of all subrotamers are given at
initialization. Subrotamers are then defined by providing lists of indices.
One particle can be part of several subrotamers.
diff --git a/sidechain/doc/rotamer_constructor.rst b/sidechain/doc/rotamer_constructor.rst
index 36c76a2c..548da6b1 100644
--- a/sidechain/doc/rotamer_constructor.rst
+++ b/sidechain/doc/rotamer_constructor.rst
@@ -4,7 +4,7 @@ Rotamer Constructor
.. currentmodule:: promod3.sidechain
Instead of creating rotamers by yourself, you can simply use the convenient
-functionality provided by PROMOD3
+functionality provided by ProMod3
Constructing Rotamers and Frame Residues
diff --git a/sidechain/doc/rotamer_lib.rst b/sidechain/doc/rotamer_lib.rst
index 007a26b5..89d70ac2 100644
--- a/sidechain/doc/rotamer_lib.rst
+++ b/sidechain/doc/rotamer_lib.rst
@@ -9,7 +9,7 @@ sidechain can completely be described in terms of dihedral angles. Preferred
combinations of such dihedral angles are a result of steric properties and
can be gathered in rotamer libraries. Different libraries exist in the field
and their main difference is, whether the provided sidechain conformations
-are dependent on their backbone or not. PROMOD3 provides you with a
+are dependent on their backbone or not. ProMod3 provides you with a
:class:`BBDepRotamerLib` organizing rotamers for the different aminoacids
in equidistant phi/psi bins, as well as a simple :class:`RotamerLib`.
Both libraries are containers for :class:`RotamerLibEntry` and are optimized
--
GitLab