Merge pull request #1843 from MDAnalysis/doc-fixes

Doc fixes

package/MDAnalysis/analysis/align.py

@@ -558,8 +558,6 @@ def __init__(self, mobile, reference, select='all', filename=None,
             exact methods
         force : bool (optional)
             Force overwrite of filename for rmsd-fitting
-        verbose : bool (optional)
-            Set logger to show more information
         start : int (optional)
             First frame of trajectory to analyse, Default: 0
         stop : int (optional)
@@ -572,6 +570,10 @@ def __init__(self, mobile, reference, select='all', filename=None,
             performance substantially in some cases. In this case, no file
             is written out (`filename` and `prefix` are ignored) and only
             the coordinates of `mobile` are *changed in memory*.
+        verbose : bool (optional)
+             Set logger to show more information and show detailed progress of
+             the calculation if set to ``True``; the default is ``False``.
+
 
         Attributes
         ----------

package/MDAnalysis/analysis/contacts.py

@@ -397,7 +397,9 @@ def __init__(self, u, selection, refgroup, method="hard_cut", radius=4.5,
             which means that the trajectory would be read until the end.
         step : int, optional
             Step between frames to analyse, Default: None becomes 1.
-
+        verbose : bool (optional)
+             Show detailed progress of the calculation if set to ``True``; the
+             default is ``False``.
         """
         self.u = u
         super(Contacts, self).__init__(self.u.trajectory, **basekwargs)

package/MDAnalysis/analysis/density.py

@@ -37,16 +37,30 @@
 Generating a density from a MD trajectory
 -----------------------------------------
 
+A common use case is to analyze the solvent density around a protein of
+interest. The density is calculated with :func:`density_from_Universe` in the
+fixed coordinate system of the simulation unit cell. It is therefore necessary
+to orient and fix the protein with respect to the box coordinate system. In
+practice this means centering and superimposing the protein, frame by frame, on
+a reference structure and translating and rotating all other components of the
+simulation with the protein. In this way, the solvent will appear in the
+reference frame of the protein.
+
 An input trajectory must
 
 1. have been centered on the protein of interest;
 2. have all molecules made whole that have been broken across periodic
-   boundaries;
+   boundaries [#pbc]_;
 3. have the solvent molecules remapped so that they are closest to the
-   solute (this is important when using funky unit cells such as
-   a dodecahedron or a truncated octahedron).
+   solute (this is important when using triclinic unit cells such as
+   a dodecahedron or a truncated octahedron) [#pbc]_.
+4. have a fixed frame of reference; for instance, by superimposing a protein
+   on a reference structure so that one can study the solvent density around
+   it [#fit]_.
 
-To generate the density of water molecules around a protein::
+To generate the density of water molecules around a protein (assuming that the
+trajectory is already appropriately treated for periodic boundary artifacts and
+is suitably superimposed to provide a fixed reference frame) [#testraj]_ ::
 
   from MDAnalysis.analysis.density import density_from_Universe
   u = Universe(TPR, XTC)
@@ -98,13 +112,49 @@
 .. autofunction:: notwithin_coordinates_factory
 
 
+.. rubric:: Footnotes
+
+.. [#pbc] Making molecules whole can be accomplished with the
+          :meth:`MDAnalysis.core.groups.AtomGroup.wrap` of
+          :attr:`Universe.atoms` (use ``compound="fragments"``).
+
+          When using, for instance, the Gromacs_ command `gmx trjconv`_
+
+          .. code-block:: bash
+
+             gmx trjconv -pbc mol -center -ur compact
+
+          one can make the molecules whole ``-pbc whole``, center it on a group
+          (``-center``), and also pack all molecules in a compact unitcell
+          representation, which can be useful for density generation.
+
+.. [#fit] Superposition can be performed with
+          :class:`MDAnalysis.analysis.align.AlignTraj`.
+
+          The Gromacs_ command `gmx trjconv`_
+
+          .. code-block:: bash
+
+             gmx trjconv -fit rot+trans
+
+          will also accomplish such a superposition. Note that the fitting has
+          to be done in a *separate* step from the treatment of the periodic
+          boundaries [#pbc]_.
+
+.. [#testraj] Note that the trajectory in the example (`XTC`) is *not* properly
+          made whole and fitted to a reference structure; these steps were
+          omitted to clearly show the steps necessary for the actual density
+          calculation.
+
 .. Links
 .. -----
 
 .. _OpenDX: http://www.opendx.org/
 .. _VMD:   http://www.ks.uiuc.edu/Research/vmd/
 .. _Chimera: https://www.cgl.ucsf.edu/chimera/
 .. _PyMOL: http://www.pymol.org/
+.. _Gromacs: http://www.gromacs.org
+.. _`gmx trjconv`: http://manual.gromacs.org/programs/gmx-trjconv.html
 
 """
 

package/MDAnalysis/analysis/diffusionmap.py

@@ -201,7 +201,8 @@ class DistanceMatrix(AnalysisBase):
         Save the `dist_matrix` to a given filename
     """
     def __init__(self, u, select='all', metric=rmsd, cutoff=1E0-5,
-                 weights=None, start=None, stop=None, step=None):
+                 weights=None, start=None, stop=None, step=None,
+                 **kwargs):
         """
         Parameters
         ----------
@@ -236,16 +237,22 @@ def __init__(self, u, select='all', metric=rmsd, cutoff=1E0-5,
             which means that the trajectory would be read until the end.
         step : int, optional
             Step between frames to analyse, Default: None becomes 1.
+        verbose : bool (optional)
+             Show detailed progress of the calculation if set to ``True``; the
+             default is ``False``.
         """
         self._u = u
         traj = self._u.trajectory
+
+        # remember that this must be called before referencing self.n_frames
+        super(DistanceMatrix, self).__init__(self._u.trajectory,
+                                           start=start, stop=stop, step=step, **kwargs)
+
         self.atoms = self._u.select_atoms(select)
         self._metric = metric
         self._cutoff = cutoff
         self._weights = weights
         self._calculated = False
-        # remember that this must be called before referencing self.n_frames
-        self._setup_frames(traj, start, stop, step)
 
     def _prepare(self):
         self.dist_matrix = np.zeros((self.n_frames, self.n_frames))

package/MDAnalysis/analysis/helanal.py

@@ -215,10 +215,10 @@ def helanal_trajectory(universe, selection="name CA",
           If the specified finish time precedes the specified start time or
           current time stamp of trajectory object.
 
-    .. Note::
-
-       Only a single helix is analyzed. Use the selection to specify the
-       helix, e.g. with "name CA and resid 1:20" or use start=1, stop=20.
+    Notes
+    -----
+    Only a single helix is analyzed. Use the selection to specify the helix,
+    e.g. with "name CA and resid 1:20" or use start=1, stop=20.
 
 
     .. versionchanged:: 0.13.0
@@ -487,9 +487,6 @@ def helanal_main(pdbfile, selection="name CA", ref_axis=None):
     logger *MDAnalysis.analysis.helanal*. A simple way to enable a logger is to
     use :func:`~MDAnalysis.lib.log.start_logging`.
 
-    .. Note:: Only a single helix is analyzed. Use the selection to specify
-              the helix, e.g. with "name CA and resid 1:20".
-
     Parameters
     ----------
     pdbfile : str
@@ -512,6 +509,13 @@ def helanal_main(pdbfile, selection="name CA", ref_axis=None):
         * Best fit tilt
         * Rotation angles: local screw angles (per residue)
 
+
+    Notes
+    -----
+    Only a single helix is analyzed. Use the selection to specify the
+    helix, e.g. with "name CA and resid 1:20".
+
+
     Example
     -------
     Analyze helix 8 in AdK (PDB 4AKE); the standard logger is started and
@@ -528,6 +532,7 @@ def helanal_main(pdbfile, selection="name CA", ref_axis=None):
     .. versionchanged:: 0.16.0
        Removed the `start` and `end` keywords for selecting residues because this can
        be accomplished more transparently with `selection`.
+
     """
 
     universe = MDAnalysis.Universe(pdbfile)

package/MDAnalysis/analysis/lineardensity.py

@@ -56,6 +56,10 @@ class LinearDensity(AnalysisBase):
           The frame to end at [-1]
     step : int
           The step size through the trajectory in frames [0]
+    verbose : bool (optional)
+          Show detailed progress of the calculation if set to ``True``; the
+          default is ``False``.
+
 
     Example
     -------

package/MDAnalysis/analysis/pca.py

@@ -190,6 +190,9 @@ def __init__(self, universe, select='all', align=False, mean=None,
         step : int, optional
             Step between frames of trajectory to use for generation
             of covariance matrix, Default: None
+        verbose : bool (optional)
+             Show detailed progress of the calculation if set to ``True``; the
+             default is ``False``.
         """
         super(PCA, self).__init__(universe.trajectory,
                                   **kwargs)

package/MDAnalysis/analysis/polymer.py

@@ -55,7 +55,8 @@ class PersistenceLength(AnalysisBase):
 
     Notes
     -----
-    This analysis requires that the trajectory supports indexing
+    This analysis requires that the trajectory supports indexing.
+
 
     .. versionadded:: 0.13.0
     """
@@ -75,6 +76,10 @@ def __init__(self, atomgroups, **kwargs):
         step : int, optional
             Frame index to stop analysis. Default: None becomes
             n_frames. Iteration stops *before* this frame number.
+        verbose : bool (optional)
+            Show detailed progress of the calculation if set to ``True``; the
+            default is ``False``.
+
         """
         super(PersistenceLength, self).__init__(
             atomgroups[0].universe.trajectory, **kwargs)

package/MDAnalysis/analysis/rdf.py

@@ -65,6 +65,10 @@ class InterRDF(AnalysisBase):
     step : int (optional)
           The step size through the trajectory in frames (default is
           every frame)
+    verbose : bool (optional)
+          Show detailed progress of the calculation if set to ``True``; the
+          default is ``False``.
+
 
     Example
     -------
@@ -83,6 +87,7 @@ class InterRDF(AnalysisBase):
     within the same molecule.  For example, if there are 7 of each
     atom in each molecule, the exclusion mask `(7, 7)` can be used.
 
+
     .. versionadded:: 0.13.0
 
     """