Analysis progmeter (#892)

* PEP8 Changes

* Add progressmeter to AnalysisBase

This also adds an initialization function to AnalysisBase. This is done
now because we need to do more then just to setup the iteration.

* Adopt Contacts

* Follow best practices for matplotlib

Returning an axis object is considered to be better since the user is
able to adjust the plot by himself if he wishes to do so.

* Addopt Persistencelength

* Adopt InterRDF

* Adopt LinearDensity

* Adopt AlignTrj

* update changelog

* Ensure old API still works

Since user code might already exist we keep make sure the old API still
works as well.

package/CHANGELOG

@@ -18,6 +18,13 @@ The rules for this file:
 
   * 0.15.1
 
+Enhancements
+
+  * All classes derived from 'AnalysisBase' now display a ProgressMeter
+  with 'quiet=False'
+  * The 'run' method from all 'AnalysisBase' derived classes return the
+  class itself.
+
 Fixes
   * GROWriter resids now truncated properly (Issue #886)
   * reading/writing lambda value in trr files (Issue #859)

package/MDAnalysis/analysis/align.py

@@ -2,8 +2,8 @@
 # vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
 #
 # MDAnalysis --- http://www.MDAnalysis.org
-# Copyright (c) 2006-2015 Naveen Michaud-Agrawal, Elizabeth J. Denning, Oliver Beckstein
-# and contributors (see AUTHORS for the full list)
+# Copyright (c) 2006-2015 Naveen Michaud-Agrawal, Elizabeth J. Denning, Oliver
+# Beckstein and contributors (see AUTHORS for the full list)
 #
 # Released under the GNU Public Licence, v2 or any higher version
 #
@@ -472,8 +472,7 @@ class AlignTraj(AnalysisBase):
 
     def __init__(self, mobile, reference, select='all', filename=None,
                  prefix='rmsfit_', mass_weighted=False, tol_mass=0.1,
-                 strict=False, force=True, quiet=False, start=None, stop=None,
-                 step=None, **kwargs):
+                 strict=False, force=True, **kwargs):
         """Initialization
 
         Parameters
@@ -516,18 +515,16 @@ def __init__(self, mobile, reference, select='all', filename=None,
         exception
 
         """
-        self._quiet = quiet
+        super(AlignTraj, self).__init__(mobile.trajectory, **kwargs)
         if self._quiet:
             logging.disable(logging.WARN)
 
-        traj = mobile.trajectory
         select = rms.process_selection(select)
         self.ref_atoms = reference.select_atoms(*select['reference'])
         self.mobile_atoms = mobile.select_atoms(*select['mobile'])
-        kwargs.setdefault('remarks', 'RMS fitted trajectory to reference')
 
         if filename is None:
-            path, fn = os.path.split(traj.filename)
+            path, fn = os.path.split(self._trajectory.filename)
             filename = os.path.join(path, prefix + fn)
             logger.info('filename of rms_align with no filename given'
                         ': {0}'.format(filename))
@@ -540,7 +537,8 @@ def __init__(self, mobile, reference, select='all', filename=None,
 
         natoms = self.mobile_atoms.n_atoms
         self.ref_atoms, self.mobile_atoms = get_matching_atoms(
-            self.ref_atoms, self.mobile_atoms, tol_mass=tol_mass, strict=strict)
+            self.ref_atoms, self.mobile_atoms, tol_mass=tol_mass,
+            strict=strict)
 
         self._writer = mda.Writer(self.filename, natoms)
 
@@ -551,7 +549,6 @@ def __init__(self, mobile, reference, select='all', filename=None,
             self._weights = None
 
         logger.info("RMS-fitting on {0:d} atoms.".format(len(self.ref_atoms)))
-        self._setup_frames(traj, start, stop, step)
 
     def _prepare(self):
         # reference centre of mass system

package/MDAnalysis/analysis/base.py

@@ -2,8 +2,8 @@
 # vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4
 #
 # MDAnalysis --- http://www.MDAnalysis.org
-# Copyright (c) 2006-2015 Naveen Michaud-Agrawal, Elizabeth J. Denning, Oliver Beckstein
-# and contributors (see AUTHORS for the full list)
+# Copyright (c) 2006-2015 Naveen Michaud-Agrawal, Elizabeth J. Denning, Oliver
+# Beckstein and contributors (see AUTHORS for the full list)
 #
 # Released under the GNU Public Licence, v2 or any higher version
 #
@@ -24,61 +24,116 @@
 """
 from six.moves import range
 
-import numpy as np
 import logging
 from MDAnalysis.lib.log import ProgressMeter
 
 logger = logging.getLogger(__name__)
 
 
 class AnalysisBase(object):
-    """Base class for defining multi frame analysis
-
-    The analysis base class is designed as a template for creating
-    multiframe analysis.
-
-    The class implements the following methods:
-
-    _setup_frames(trajectory, start=None, stop=None, step=None)
-      Pass a Reader object and define the desired iteration pattern
-      through the trajectory
-
-    run
-      The user facing run method.  Calls the analysis methods
-      defined below
-
-    Your analysis can implement the following methods, which are
-    called from run:
-
-    _prepare
-      Called before iteration on the trajectory has begun.
-      Data structures can be set up at this time, however most
-      error checking should be done in the __init__
-
-    _single_frame
-      Called after the trajectory is moved onto each new frame.
-
-    _conclude
-      Called once iteration on the trajectory is finished.
-      Apply normalisation and averaging to results here.
+    """Base class for defining multi frame analysis, it is designed as a
+    template for creating multiframe analysis. This class will automatically
+    take care of setting up the trajectory reader for iterating and offers to
+    show a progress meter.
+
+    To define a new Analysis, `AnalysisBase` needs to be subclassed
+    `_single_frame` must be defined. It is also possible to define
+    `_prepare` and `_conclude` for pre and post processing. See the example
+    below.
+
+    .. code-block:: python
+       class NewAnalysis(AnalysisBase):
+           def __init__(self, atomgroup, parameter, **kwargs):
+               super(NewAnalysis, self).__init__(atomgroup.universe.trajectory,
+                                                 **kwargs)
+               self._parameter = parameter
+               self._ag = atomgroup
+
+           def _prepare(self):
+               # OPTIONAL
+               # Called before iteration on the trajectory has begun.
+               # Data structures can be set up at this time
+               self.result = []
+
+           def _single_frame(self):
+               # REQUIRED
+               # Called after the trajectory is moved onto each new frame.
+               # store result of `some_function` for a single frame
+               self.result.append(some_function(self._ag, self._parameter))
+
+           def _conclude(self):
+               # OPTIONAL
+               # Called once iteration on the trajectory is finished.
+               # Apply normalisation and averaging to results here.
+               self.result = np.asarray(self.result) / np.sum(self.result)
+
+    Afterwards the new analysis can be run like this.
+
+    .. code-block:: python
+       na = NewAnalysis(u.select_atoms('name CA'), 35).run()
+       print(na.result)
 
     """
+    def __init__(self, trajectory, start=None,
+                 stop=None, step=None, quiet=True):
+        """
+        Parameters
+        ----------
+        trajectory : mda.Reader
+            A trajectory Reader
+        start : int, optional
+            start frame of analysis
+        stop : int, optional
+            stop frame of analysis
+        step : int, optional
+            number of frames to skip between each analysed frame
+        quiet : bool, optional
+            Turn off verbosity
+        """
+        self._quiet = quiet
+        self._setup_frames(trajectory, start, stop, step)
+
     def _setup_frames(self, trajectory, start=None,
                       stop=None, step=None):
+        """
+        Pass a Reader object and define the desired iteration pattern
+        through the trajectory
+
+        Parameters
+        ----------
+        trajectory : mda.Reader
+            A trajectory Reader
+        start : int, optional
+            start frame of analysis
+        stop : int, optional
+            stop frame of analysis
+        step : int, optional
+            number of frames to skip between each analysed frame
+        """
         self._trajectory = trajectory
         start, stop, step = trajectory.check_slice_indices(
             start, stop, step)
         self.start = start
         self.stop = stop
         self.step = step
         self.n_frames = len(range(start, stop, step))
+        interval = int(self.n_frames // 100)
+        if interval == 0:
+            interval = 1
+
+        # ensure _quiet is set when __init__ wasn't called, this is to not
+        # break pre 0.16.0 API usage of AnalysisBase
+        if not hasattr(self, '_quiet'):
+            self._quiet = True
+        self._pm = ProgressMeter(self.n_frames if self.n_frames else 1,
+                                 interval=interval, quiet=self._quiet)
 
     def _single_frame(self):
         """Calculate data from a single frame of trajectory
 
         Don't worry about normalising, just deal with a single frame.
         """
-        pass
+        raise NotImplementedError("Only implemented in child classes")
 
     def _prepare(self):
         """Set things up before the analysis loop begins"""
@@ -91,7 +146,7 @@ def _conclude(self):
         """
         pass
 
-    def run(self, **kwargs):
+    def run(self):
         """Perform the calculation"""
         logger.info("Starting preparation")
         self._prepare()
@@ -101,5 +156,7 @@ def run(self, **kwargs):
             self._ts = ts
             # logger.info("--> Doing frame {} of {}".format(i+1, self.n_frames))
             self._single_frame()
+            self._pm.echo(self._frame_index)
         logger.info("Finishing up")
         self._conclude()
+        return self

package/MDAnalysis/analysis/contacts.py

@@ -376,7 +376,7 @@ class Contacts(AnalysisBase):
 
     """
     def __init__(self, u, selection, refgroup, method="hard_cut", radius=4.5,
-                 kwargs=None, start=None, stop=None, step=None,):
+                 kwargs=None, **basekwargs):
         """Initialization
 
         Parameters
@@ -404,6 +404,9 @@ def __init__(self, u, selection, refgroup, method="hard_cut", radius=4.5,
             Step between frames to analyse, Default: 1
 
         """
+        self.u = u
+        super(Contacts, self).__init__(self.u.trajectory, **basekwargs)
+
         if method == 'hard_cut':
             self.fraction_contacts = hard_cut_q
         elif method == 'soft_cut':
@@ -413,10 +416,6 @@ def __init__(self, u, selection, refgroup, method="hard_cut", radius=4.5,
                 raise ValueError("method has to be callable")
             self.fraction_contacts = method
 
-        # setup boilerplate
-        self.u = u
-        self._setup_frames(self.u.trajectory, start, stop, step)
-
         self.selection = selection
         self.grA = u.select_atoms(selection[0])
         self.grB = u.select_atoms(selection[1])