Updated documentation.

Signed-off-by: Stefan Bienert <stefan.bienert@unibas.ch>

modules/doc/external.rst

@@ -24,22 +24,24 @@ As an example, we would like to obtain the full path of the msms executable (a p
 .. code-block:: python
 
   from ost import settings
-  exe_path=settings.Locate('msms', search_paths=['/opt/app','/home/app'],
+  exe_path = settings.Locate('msms', search_paths=['/opt/app','/home/app'],
               env_name='MSMS', search_system_paths=True)
   print exe_path
   
 The :func:`~ost.settings.Locate` command looks for the program with the name 
 `msms`. If env_name is set, it first looks if an environment variable with the 
-name `MSMS` is set. If not, all paths in search_paths are searched. If the 
-executable could still not be found and search_system_paths is set to True, the 
-binary search paths are searched. If the executable could not be found, a 
+name `MSMS` is set. If not, all paths in *search_paths* are searched. If the 
+executable could still not be found and *search_system_paths* is set to True, 
+the binary search paths are searched. If the executable could not be found, a 
 :exc:`~ost.FileNotFound` exception is raised with a detailed description where 
 Locate was searching for the executable.
     
 Prepare All Files
 --------------------------------------------------------------------------------
 
-The preparation of the necessary files is very dependent on the external program. Often it is useful to generate a temporary directory or file. For this, the python module tempfile is very handy.
+The preparation of the necessary files is very dependent on the external 
+program. Often it is useful to generate a temporary directory or file. For 
+this, the Python module tempfile is very handy.
 
 An example how to generate a temporary directory, open a file in this directory and write the position and radius of all atoms into this file is shown here:
 
@@ -49,17 +51,17 @@ An example how to generate a temporary directory, open a file in this directory
   import os
   
   # generate a temporary directory
-  tmp_dir_name=tempfile.mkdtemp()
+  tmp_dir_name = tempfile.mkdtemp()
   print 'temporary directory:',tmp_dir_name
   
   # generate and open a file in the temp directory
-  tmp_file_name=os.path.join(tmp_dir_name,"entity")
-  tmp_file_handle=open(tmp_file_name, 'w')
+  tmp_file_name = os.path.join(tmp_dir_name,"entity")
+  tmp_file_handle = open(tmp_file_name, 'w')
   print 'temporary file:',tmp_file_handle
   
   # write position and radius of all atoms to file
   for a in entity.GetAtomList():
-    position=a.GetPos()
+    position = a.GetPos()
     tmp_file_handle.write('%8.3f %8.3f %8.3f %4.2f\n' % (position[0],
                           position[1], position[2], a.GetProp().radius))
                           
@@ -78,7 +80,7 @@ To run the external program msms from the above example, with the temporary file
   import subprocess
 
   # set the command to execute
-  command="%s -if %s -of %s" % (exe_path,
+  command = "%s -if %s -of %s" % (exe_path,
             tmp_file_name, tmp_file_name)
   print 'command:',command
 
@@ -86,8 +88,8 @@ To run the external program msms from the above example, with the temporary file
   proc = subprocess.Popen(command, shell=True, stdout=subprocess.PIPE)
   stdout_value, stderr_value = proc.communicate()
 
-  #check for successful completion of msms
-  if proc.returncode!=0:
+  # check for successful completion of msms
+  if proc.returncode != 0:
     print "WARNING: msms error\n", stdout_value
     raise subprocess.CalledProcessError(proc.returncode, command)
 
@@ -107,5 +109,5 @@ Here we first print the command line output and then load the generated msms sur
   print stdout_value
   
   # read msms surface from file
-  surface=io.LoadSurface(tmp_file_name, "msms")
+  surface = io.LoadSurface(tmp_file_name, "msms")
   print 'number of vertices:',len(surface.GetVertexIDList())

modules/doc/intro-01.rst

@@ -30,7 +30,7 @@ To load a PDB file, simply type
 
 .. code-block:: python
 
-   fragment=io.LoadPDB('/path/to/examples/code_fragments/entity/fragment.pdb')
+   fragment = io.LoadPDB('/path/to/examples/code_fragments/entity/fragment.pdb')
 
 This will load the fragment from the specified file 'fragment.pdb' and store the 
 result in fragment.  The :func:`~ost.io.LoadPDB` has many options, which, for
@@ -74,7 +74,7 @@ This will group the atoms by residue. And, for completeness, we will first group
       for atom in residue.atoms:
         print '    ', atom.name, atom.pos
 
-A protein fragment would not be complete without bonds: Let's see 
+A protein fragment would not be complete without bonds. Let's see 
 what bonds we have in there:
 
 .. code-block:: python
@@ -90,7 +90,7 @@ of the entity. The graphical representation is completely separate from the :cla
 
 .. code-block:: python
   
-  go=gfx.Entity("Fragment", fragment)
+  go = gfx.Entity("Fragment", fragment)
   scene.Add(go)
   scene.CenterOn(go)
 
@@ -100,7 +100,7 @@ Now you will see the fragment in the 3D window.
 Use the mouse to rotate, zoom in and shift the camera. Double clicking on an 
 atom will center the camera on that atom. If you want to learn more about the 
 :mod:`~ost.gfx` module, you are encouraged to read :doc:`the gfx 
-intro<intro-03>` and the :mod:`gfx documentation<ost.gfx`.
+intro<intro-03>` and the :mod:`gfx documentation<ost.gfx>`.
 
 Introduction to Views
 --------------------------------------------------------------------------------
@@ -116,11 +116,11 @@ views with handles in Python due to the dynamic nature of the language. An
 algorithm that is written for entities will almost always (with some care) also
 work for 
 :class:`EntityHandles <ost.mol.EntityHandle>`. This is referred to as 
-`duck-typing <http://en.wikipedia.org/wiki/Duck_typing>`_ (I don' t care if it 
-is a duck as long as it looks like a duck), a concept used all over the place
+`duck-typing <http://en.wikipedia.org/wiki/Duck_typing>`_ (I don't care if it 
+isn't a duck as long as it looks like a duck), a concept used all over the place
 in Python. For views, the same rule as for
 :class:`entities <ost.mol.EntityHandle>` applies: No atom can be part of the
-view without it's residue...
+view without it's residue.
 
 To familiarize yourself with the concept of views, we will use the fragment in 
 the 3D window of the last example.
@@ -133,11 +133,11 @@ The Query Language
 --------------------------------------------------------------------------------
 
 The first way to select parts of a structure is with a dedicated mini-language, 
-called :doc:`the query language <mol/base/query>`. In the Python Shell, type
+called :doc:`the query language <mol/base/query>`. In the Python shell, type
 
 .. code-block:: python
 
-  go.selection=fragment.Select('')
+  go.selection = fragment.Select('')
     
 The code performs a selection on the fragment and assigns the resulting view to 
 the selection of the graphical object. A green halo will be displayed around the 
@@ -150,7 +150,7 @@ chains, residues, atoms and bonds. To select lysine residues, type
 
 .. code-block:: python
 
-  go.selection=fragment.Select('rname=LYS')
+  go.selection = fragment.Select('rname=LYS')
     
 
 As you can see (image on the right), the only lysine residue is now 
@@ -161,7 +161,7 @@ number 1 to 3, the following statement will do the job:
 
 .. code-block:: python
 
-  go.selection=fragment.Select('rnum>=1 and rnum<=3')
+  go.selection = fragment.Select('rnum>=1 and rnum<=3')
     
 but this is very cumbersome. That's why there is a shortcut to this statement. 
 You can specify a range of values.
@@ -177,15 +177,15 @@ look at the :doc:`../mol/base/query`.
 Constructing Views Manually
 --------------------------------------------------------------------------------
 
-Sometimes the query language Is Not Enough (TM). For these cases the 
-construction of manual entities becomes neccessary. This is pretty straight 
+Sometimes the query language is not enough. For these cases the 
+construction of manual entities becomes necessary. This is pretty straight 
 forward:
 
 .. code-block:: python
 
-  view=fragment.CreateEmptyView()
-  ca=fragment.FindAtom('A', mol.ResNum(1), 'CA')
-  cb=fragment.FindAtom('A', mol.ResNum(1), 'CB')
+  view = fragment.CreateEmptyView()
+  ca = fragment.FindAtom('A', mol.ResNum(1), 'CA')
+  cb = fragment.FindAtom('A', mol.ResNum(1), 'CB')
   view.AddAtom(ca)
   view.AddAtom(cb)
   go.SetSelection(view)
@@ -197,7 +197,7 @@ to add the bond manually with
 
 .. code-block:: python
 
-  ca_cb=ca.FindBondToAtom(cb)
+  ca_cb = ca.FindBondToAtom(cb)
   view.AddBond(ca_cb)
     
 Or, as a very convenient shortcut 
@@ -207,6 +207,10 @@ add all bonds that have both bonding partners in the view.
 Don't forget to update the selection of the graphics object to see what view you 
 have created.
 
+.. code-block:: python
+
+  go.SetSelection(view)
+
 Saving an Entity
 --------------------------------------------------------------------------------
 

modules/doc/intro-02.rst

@@ -7,21 +7,21 @@ For the course of this tutorial, we assume that you have :ref:`DNG up and runnin
 Loading Images and Density Maps
 --------------------------------------------------------------------------------
 
-OpenStructure features a :mod:`~ost.img` module that is dedicated to the 
+OpenStructure features an :mod:`~ost.img` module that is dedicated to the 
 manipulation of images/density maps. The images or density maps can either be 
-one-, two- or three-dimensional. The most common formats used in X-ray and 
-electron  crystallography and atomic force microscope are supported in addition 
+one-, two- or three-dimensional. The most common formats used in X-ray/ 
+electron crystallography and atomic force microscopy are supported in addition 
 to several general purpose image formats. See
-:doc:`supported file formats <io/formats>` for details. The :mod:`~ost.img`
+:doc:`supported file formats <io/image_formats>` for details. The :mod:`~ost.img`
 module was originally developed as part of the Image Processing Library &
 Toolbox IPLT. More documentation and examples can also be found on the
-`IPLT website <http://www.iplt.org>`_.
+`IPLT website <http://www.iplt.org>`.
 
 To load a density map, type
 
 .. code-block:: python
 
-   map=io.LoadImage('/path/to/examples/code_fragments/map/1ppt.map')
+  map = io.LoadImage('/path/to/examples/code_fragments/map/1ppt.map')
 
 This will load the fragment density map from the specified file 'fragment.map' 
 and store the result in map. 
@@ -32,7 +32,7 @@ Now let's inspect what we just loaded:
 
   print map.GetPixelSampling(), map.GetSize()
     
-We can see that the sampling is set to 1.0 Angstroms in all three dimensions. The loaded map is an instance of :class:`~ost.img.ImageHandle`, a class to represent images in 1, 2 and 3 dimensions.
+We can see that the sampling is set to 1.0 Angstrom in all three dimensions. The loaded map is an instance of :class:`~ost.img.ImageHandle`, a class to represent images in one, two and three dimensions.
 
 Manipulating Images and Density Maps
 --------------------------------------------------------------------------------
@@ -46,13 +46,13 @@ first have to import the :mod:`img.alg <ost.img.alg>` module.
   from ost.img import alg
 
 
-The :mod:`img.alg <ost.img.alg>` module provides a wide range of algorithm to 
+The :mod:`img.alg <ost.img.alg>` module provides a wide range of algorithms to 
 manipulate image data. Here for example we use a LowPassFilter to restrict the 
-resolution of the density map to frequencies lower than a threshold.
+resolution of the density map to frequencies lower than a certain threshold.
 
 .. code-block:: python
 
-   map_filtered=map.Apply(alg.LowPassFilter(3.0))
+   map_filtered = map.Apply(alg.LowPassFilter(3.0))
 
 The filtered map is stored in a new variable called `map_filtered`. A complete list of algorithms is available on the  :doc:`img/alg/alg` page.
 
@@ -68,7 +68,7 @@ Isosurfaces are easy to create in OpenStructure:
 
 .. code-block:: python
 
-   go=gfx.MapIso("filtered", map_filtered,0.5)
+   go = gfx.MapIso("filtered", map_filtered,0.5)
    scene.Add(go)
 
 The other way to visualize a 3-dimensional map is by showing one 2-dimensional 
@@ -81,10 +81,9 @@ A DataViewer showing the filtered map is created using the following command:
   gui.CreateDataViewer(map_filtered)
 
 This command displays a panel showing one slice of the density map lying on a 
-particular (x,y) plane in the coordinate reference system.
-The `z` and `x` keys can be used to move to slices lying at a lower or higher 
-coordinate along the `z` axis, allowing the examination of
-the full 3-dimensional volume.
+particular (x,y) plane in the coordinate reference system. The `z` and `x`
+keys can be used to move to slices lying at a lower or higher coordinate along 
+the `z` axis, allowing the examination of the full 3-dimensional volume.
 
 A more detailed explanation of the :mod:`~ost.img` module can be found in the 
 tutorial section for :mod:`~ost.img`.

modules/doc/intro-03.rst

@@ -15,8 +15,8 @@ of data.
 
 .. code-block:: python
   
-  pdb=io.LoadPDB('/path/to/molecule.pdb')
-  go=gfx.Entity('PROTEIN', pdb)
+  pdb = io.LoadPDB('/path/to/molecule.pdb')
+  go = gfx.Entity('PROTEIN', pdb)
   scene.Add(go)
   scene.CenterOn(go)
 
@@ -49,7 +49,7 @@ manipulated:
 .. code-block:: python
 
   # retrieving the previously added protein
-  obj=scene['PROTEIN']
+  obj = scene['PROTEIN']
   # set color of the protein to red
   obj.SetColor(gfx.RED)
 
@@ -90,7 +90,7 @@ protein. Remember from above, that we stored our molecule in the `pdb` variable.
 
 .. code-block:: python
   
-  not_protein=pdb.Select('peptide=false')
+  not_protein = pdb.Select('peptide=false')
   obj.SetRenderMode(gfx.HSC)
   obj.SetRenderMode(gfx.CUSTOM, not_protein)
 
@@ -154,7 +154,7 @@ Coloring the Entity By Property
 
 The most complex but also most powerful coloring method is 
 :meth:`Entity.ColorBy`, which allows to color atoms by a numeric property. This 
-property can either be built-in a property such as atomic b-factor, charge, 
+property can either be a built-in property such as atomic b-factor, charge, 
 residue number or be :doc:`custom properties <../base/generic>` assigned by the 
 user or an algorithm and be defined at any level (chain, residue, atom). The 
 naming of the built-in properties is identical to the properties available in 

modules/doc/intro.rst

@@ -32,8 +32,8 @@ examples are located at a different location:
 
  * on *MacOS X* the files are located inside the application bundle (DNG.app).
    The file browser will automatically point to the examples.
- * on *Linux* PREFIX/share/openstructure/examples, where PREFIX is 
-   the path to the directory containing OpenStructure.
+ * on *Linux* the files are located at PREFIX/share/openstructure/examples, 
+   where PREFIX is the path to the directory containing OpenStructure.
 
 Starting DNG
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -44,16 +44,16 @@ Generation). To start it,
  * on *MacOS X* double click DNG.app
  * on *Linux* fire up a terminal change into the OpenStructure installation 
    directory and type 'bin/dng'. If you have the binary directory in the PATH, 
-   typing dng is sufficient.
+   typing *dng* is sufficient.
 
 Interactive Python Shell
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. image:: images/100208_OpenStructure_UI_Colored.png
 
-Now we will enter commands in the Python Shell (in the screenshot above, the 
-python shell (shown in green) is located at the right of the main window). If you want to get 
-more information on any object, function or class, the python help command may 
-be useful. For example:
+Now we will enter commands in the Python shell (in the screenshot above, the 
+Python shell (shown in green) is located at the right of the main window). If 
+you want to get more information on any object, function or class, the Python 
+help command may be useful. For example:
 
   .. code-block:: python
 

modules/doc/newmodule.rst

@@ -271,5 +271,5 @@ following content:
 In case one wants to implement Python-only functionality for the new module, any
 number of function definitions can be added to the `__init__.py` file.
 
-That's it!. The next time the OpenStructure project is compiled, the new module 
+That's it! The next time the OpenStructure project is compiled, the new module 
 will be built and made available at both the C++ and the Python level.

modules/mol/alg/pymod/superpose.py

@@ -275,9 +275,9 @@ def MatchResidueByGlobalAln(ent_a, ent_b, atoms='all'):
 def Superpose(ent_a, ent_b, match='number', atoms='all', iterative=False, max_iterations=5, distance_threshold=3.0):
   """
   Superposes the model entity onto the reference. To do so, two views are
-  created, returned with the result. **atoms** describes what goes in to these
+  created, returned with the result. **atoms** describes what goes into these
   views and **match** the selection method. For superposition,
-  :func:`~ost.mol.alg.SuperposeSVD` is called. For matching, following methods
+  :func:`~ost.mol.alg.SuperposeSVD` is called. For matching, the following methods
   are recognised:
 
   * ``number`` - select residues by residue number, includes **atoms**, calls
@@ -292,14 +292,23 @@ def Superpose(ent_a, ent_b, match='number', atoms='all', iterative=False, max_it
   * ``global-aln`` - select residues from a Needleman/Wunsch alignment, includes
     **atoms**, calls :func:`~ost.mol.alg.MatchResidueByGlobalAln`
 
+  There is also an option to use **iterative** matching which allows for an 
+  iterative approach to superposing two structures. **iterative** takes two
+  additional parameters, **max_iteration** and **distance_threshold**.
+
   :param ent_a: The model entity
   :type ent_a: :class:`~ost.mol.EntityView` or :class:`~ost.mol.EntityHandle`
   :param ent_b: The reference entity
   :type ent_b: :class:`~ost.mol.EntityView` or :class:`~ost.mol.EntityHandle`
   :param match: Method to gather residues/ atoms
   :type match: :class:`str`
-  :param atoms: The subset of atoms to be used in the superposition.
+  :param atoms: The subset of atoms to be used in the superposition
   :type atoms: :class:`str`, :class:`list`, :class:`set`
+  :param max_iterations: They number of iterations that will be run during 
+  iterative superposition
+  :type max_iterations: :class:`int`
+  :param distance_threshold: The distance threshold between which two atoms that 
+  will be used in the next superposition iteration
   :returns: An instance of :class:`SuperpositionResult`, containing members
 
             * ``rmsd`` - RMSD of the superposed entities

modules/seq/alg/doc/seqalg.rst

@@ -52,7 +52,7 @@
   :param aln: An alignment handle
   :type aln: :class:`~ost.seq.AlignmentHandle`
   :param assign: If true, the conservation scores are assigned to attached 
-      residues. The name of the property can be changed with the prop_name 
+      residues. The name of the property can be changed with the *prop_name* 
       parameter. Useful when coloring entities based on sequence conservation.
   :param prop_name: The property name for assigning the conservation to 
       attached residues. Defaults to 'cons'.
@@ -71,9 +71,9 @@
   
   .. code-block:: python
   
-    seq_a=seq.CreateSequence('A', 'acdefghiklmn')
-    seq_b=seq.CreateSequence('B', 'acdhiklmn')
-    alns=seq.alg.LocalAlign(seq_a, seq_b, seq.alg.BLOSUM62)
+    seq_a = seq.CreateSequence('A', 'acdefghiklmn')
+    seq_b = seq.CreateSequence('B', 'acdhiklmn')
+    alns = seq.alg.LocalAlign(seq_a, seq_b, seq.alg.BLOSUM62)
     print alns[0].ToString(80)
     # >>> A acdefghiklmn
     # >>> B acd---hiklmn
@@ -82,12 +82,11 @@
   :type seq1: :class:`~ost.seq.ConstSequenceHandle`
   :param seq2: A valid sequence  
   :type seq2: :class:`~ost.seq.ConstSequenceHandle`
-  
   :param subst_weigth: The substitution weights matrix
   :type subst_weight: :class:`SubstWeightMatrix`
   :param gap_open: The gap opening penalty. Must be a negative number
   :param gap_ext: The gap extension penalty. Must be a negative number
-  :returns: list of best-scoring, non-overlapping alignments of *seq1* and 
+  :returns: A list of best-scoring, non-overlapping alignments of *seq1* and 
      *seq2*. Since alignments always start with a replacement, the start is
      stored in the sequence offset of the two sequences.
 
@@ -101,9 +100,9 @@
   
   .. code-block:: python
   
-    seq_a=seq.CreateSequence('A', 'acdefghiklmn')
-    seq_b=seq.CreateSequence('B', 'acdhiklmn')
-    alns=seq.alg.GlobalAlign(seq_a, seq_b, seq.alg.BLOSUM62)
+    seq_a = seq.CreateSequence('A', 'acdefghiklmn')
+    seq_b = seq.CreateSequence('B', 'acdhiklmn')
+    alns = seq.alg.GlobalAlign(seq_a, seq_b, seq.alg.BLOSUM62)
     print alns[0].ToString(80)
     # >>> A acdefghiklmn
     # >>> B acd---hiklmn
@@ -112,24 +111,23 @@
   :type seq1: :class:`~ost.seq.ConstSequenceHandle`
   :param seq2: A valid sequence  
   :type seq2: :class:`~ost.seq.ConstSequenceHandle`
-  
   :param subst_weigth: The substitution weights matrix
   :type subst_weight: :class:`SubstWeightMatrix`
   :param gap_open: The gap opening penalty. Must be a negative number
   :param gap_ext: The gap extension penalty. Must be a negative number
-  :returns: best-scoring alignment of *seq1* and *seq2*.
+  :returns: Best-scoring alignment of *seq1* and *seq2*.
 
 .. function:: ShannonEntropy(aln, ignore_gaps=True)
 
   Returns the per-column Shannon entropies of the alignment. The entropy
-  describes how conserved a certain column in the alignment is . The higher
-  the entropy is, the less conserved the column. For column with no amino 
-  aids, the entropy value is set to NAN
+  describes how conserved a certain column in the alignment is. The higher
+  the entropy is, the less conserved the column. For a column with no amino 
+  aids, the entropy value is set to NAN.
 
-  :param aln: multiple sequence alignment
+  :param aln: Multiple sequence alignment
   :type aln: :class:`~ost.seq.AlignmentHandle`
-  :param ignore_gaps: whether to ignore gaps in the column.
+  :param ignore_gaps: Whether to ignore gaps in the column.
   :type ignore_gaps: bool
 
-  :returns: list of column entropies
+  :returns: List of column entropies
 

modules/seq/alg/pymod/__init__.py

@@ -12,7 +12,7 @@ def ValidateSEQRESAlignment(aln, chain=None):
   :param chain: Source of the sequence
   :type chain: :class:`~ost.mol.ChainHandle`
 
-  :returns: True if all residues (beside gaped ones) are connected, False
+  :returns: True if all residues (beside gapped ones) are connected, False
             otherwise.
   """
   from ost import LogWarning