docu updates

loop/doc/structure_db.rst

@@ -4,8 +4,11 @@ Structural Data
 .. currentmodule:: promod3.loop
 
 The structural database serves as a container for structural backbone and 
-sequence data. 
-Several other features derived from sequence / structure can 
+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
+features (see: :class:`Fragger`). 
+Besides backbone and sequence data, derived features can  
 optionally be stored. E.g. sequence profiles or secondary structure information.
 Optional data includes:
 
@@ -54,7 +57,8 @@ Defining Chains and Fragments
   .. attribute:: offset
 
     All residues of the added stretch are stored in a linear memory layout.
-    The offset parameter tells us where it exactly starts. (:class:`int`)
+    The offset parameter tells us where it exactly starts in the global data 
+    structure. (:class:`int`)
 
   .. attribute:: size
 
@@ -74,7 +78,8 @@ Defining Chains and Fragments
 
 .. class:: FragmentInfo(chain_index, offset, length)
 
-  The FragmentInfo defines any fragment in the structural database.
+  The FragmentInfo defines any fragment in the structural database. If you 
+  implement your own accessor object, thats the information you want to store.
 
   :param chain_index:   Fills :attr:`chain_index`
 
@@ -84,11 +89,12 @@ 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 structure db 
+    this particle belongs to. (:class:`int`)
 
   .. attribute:: offset
 
-    Index of residue in **chain** the fragment starts. (:class:`int`)
+    Index of residue in **chain** the fragment starts. (0-based, :class:`int`)
 
   .. attribute:: length
 
@@ -117,7 +123,8 @@ database, you might want to consider two things:
 .. class:: StructureDBDataType
 
   The StructureDBDataType enum has to be passed at initialization of a 
-  StructureDB in order to define what data you want to store in there.
+  StructureDB in order to define what data you want to store additionally
+  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:
@@ -127,13 +134,13 @@ database, you might want to consider two things:
 
   All, Dihedrals, SolventAccessibilities, ResidueDepths, DSSP, AAFrequencies,
   AAFrequenciesStruct
-
+  
 
 .. class:: StructureDB(data_to_store)
 
-  Only the coordinates, the sequence and the requested
-  data is extracted in :meth:`AddCoordinates` and later available in the
-  data extraction functions. Have a look at the :class:`StructureDBDataType` 
+  Generates an empty 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...
 
   :param data_to_store: Specifies what data to store in the database, several
@@ -158,6 +165,7 @@ database, you might want to consider two things:
     :raises:  :exc:`~exceptions.RuntimeError` if file cannot be opened or if
               file cannot be parsed (see :ref:`here <portableIO>` for details).
 
+
   .. method:: Save(filename)
               SavePortable(filename)
 
@@ -192,17 +200,15 @@ database, you might want to consider two things:
     calculating solvent accessibilities etc.).
     The only exception is AAFrequencies, where a valid sequence profile 
     is expected in *prof* that has matching sequence with *seqres*
-    All residues in chain with name 
-    *chain_name* must have residue numbers that directly relate them to
-    the *seqres* with an indexing scheme starting from one.
+    All residues in chain with name *chain_name* must have residue numbers 
+    that directly relate them to the *seqres* with an indexing scheme 
+    starting from one.
     If this is not the case, an error gets thrown. You might want to
     consider to use :meth:`ost.seq.Renumber` for proper numbering.
-    Based on consecutive numbering, connected stretches are identified
+    Based on consecutive numbering and additionally checking for valid
+    peptide bonds, connected stretches are identified
     and every added connected stretch gets its own entry with 
     :class:`CoordInfo` as a descriptor. 
-    But: There is a check that the peptide bonds in these "connected" 
-    stretches are of valid length! If an invalid peptide bond length is
-    detected, that stretch is discarded.
     To avoid cluttering the database with many small fragments, the flag:
     *only_longest_stretch* can be used. Set it to False if all
     connected stretches of chain with name *chain_name* should be added.
@@ -210,7 +216,9 @@ database, you might want to consider two things:
     lossy data compression for the positions, the extent in x, y and
     z - direction for every connected stretch is limited to 655A. This should
     be sufficient for most structures, but stretches exceeding this maximum
-    are discarded.
+    are discarded. For storing the structural data given these restraints,
+    a translation is applied that gets stored as the *shift* attribute
+    in the according :class:`CoordInfo` object.
 
     :param id:          identifier of the added structure (e.g. pdb id)
     :param chain_name:  Name of the chain in *ent* you want to add
@@ -239,6 +247,7 @@ database, you might want to consider two things:
               the sequence in *prof* does not match the *seqres* or *prof* is 
               invalid. 
 
+
   .. method:: GetCoordIdx(id, chain_name)
 
     :returns: The StructureDB indices (in [0, :meth:`GetNumCoords`-1]) of 
@@ -252,6 +261,7 @@ database, you might want to consider two things:
     :type pdb_id:       :class:`str`
     :type chain_name:   :class:`str`
 
+
   .. method:: GetCoordInfo(idx)
 
     :returns: Object describing the stretch of connected residues with 
@@ -262,7 +272,6 @@ database, you might want to consider two things:
     :type idx:  :class:`int`
 
 
-
   .. method:: GetNumCoords()
 
     :returns: Number of connected stretches of residues that have been added to 
@@ -369,6 +378,7 @@ database, you might want to consider two things:
               the case when the fragment does not fully fit into one of the
               connected stretches of residues in the database.
 
+
   .. method:: GetSequenceProfile(fragment)
 
     :returns: The sequence profile for the residues defined by *fragment* with
@@ -384,7 +394,8 @@ database, you might want to consider two things:
               aa frequency data or if fragment is invalid. This is
               the case when the fragment does not fully fit into one of the
               connected stretches of residues in the database.
-                        
+                    
+
   .. method:: GetStructureProfile(fragment)
 
     :returns: The structure profile for the residues defined by *fragment* with
@@ -401,6 +412,7 @@ database, you might want to consider two things:
               the case when the fragment does not fully fit into one of the
               connected stretches of residues in the database.
 
+
   .. method:: GenerateStructureProfile(bb_list, residue_depths)
 
     Calculates a structure profile for *bb_list* with given *residue_depths*
@@ -421,6 +433,7 @@ database, you might want to consider two things:
               *residue_depths* differ in size, when their size is 0
               or when database does not contain aa frequencies struct data.
 
+
   .. method:: SetStructureProfile(coord_idx, prof)
 
     Takes the *prof* and sets the corresponding StructureProfile
@@ -438,6 +451,7 @@ database, you might want to consider two things:
              exactly match the size of entry at *coord_idx* or when database
              does not contain aa frequency struct data.
 
+
   .. method:: GetSubDB(indices)
 
     :return: A new database containing only the structural infos specified by