add deprecation warnings for API changes

- closes #1383 - included deprecations: - #1373 Timeseries (targeted for 0.17) Note that the deprecation for core.Timeseries will always show up; this is deliberate so that users WILL see it as it will be gone in the next release! - #1377 Quick selectors (target 1.0) - #782 flags (target 1.0) - updated CHANGELOG
MDAnalysis · Jun 15, 2017 · 088d309 · 088d309
1 parent ebe2b84
commit 088d309
Show file tree

Hide file tree

Showing 7 changed files with 231 additions and 67 deletions.
diff --git a/package/CHANGELOG b/package/CHANGELOG
@@ -15,7 +15,7 @@ The rules for this file:
 ------------------------------------------------------------------------------
 
 
-mm/dd/17 richardjgowers, rathann, jbarnoud
+mm/dd/17 richardjgowers, rathann, jbarnoud, orbeckst
 
   * 0.16.2
 
@@ -27,6 +27,9 @@ Fixes
   * Groups are hashable on python 3 (Issue #1397)
 
 Changes
+  * added deprecation warnings for API changes (removal of Timeseries and
+    DCD correl functionality, removal of instant selectors, and removal of
+    the core.flag registry) (Issue #1383)
 
 
 06/03/17 utkbansal, kain88-de, xiki-tempula, kaplajon, wouterboomsma,

diff --git a/package/MDAnalysis/coordinates/memory.py b/package/MDAnalysis/coordinates/memory.py
@@ -106,6 +106,8 @@
     universe2 = mda.Universe(PSF, coordinates, format=MemoryReader, order='afc')
 
 
+.. _create-in-memory-trajectory-with-AnalysisFromFunction:
+
 .. rubric:: Creating an in-memory trajectory with
             :func:`~MDAnalysis.analysis.base.AnalysisFromFunction`
 

diff --git a/package/MDAnalysis/core/Timeseries.py b/package/MDAnalysis/core/Timeseries.py
@@ -21,10 +21,19 @@
 #
 
 
-"""
-Compute observable timeseries from trajectories --- :mod:`MDAnalysis.core.Timeseries`
+"""Compute observable timeseries from trajectories --- :mod:`MDAnalysis.core.Timeseries`
 =======================================================================================
 
+.. deprecated:: 0.16.2
+   The Timeseries functionality (in particular correl) will be removed in the
+   0.17 release. See issue `#1372
+   <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more details.
+   To extract coordinates efficiently one can use
+   :class:`MDAnalysis.analysis.base.AnalysisFromFunction` as shown in
+   :ref:`Creating an in-memory trajectory with AnalysisFromFunction
+   <create-in-memory-trajectory-with-AnalysisFromFunction>`.
+
+
 The collection of timeseries (such as :class:`Atom`, :class:`Bond`,
 :class:`Dihedral`...)  can be computed from a trajectory in one go, foregoing
 the need to iterate through the trajectory frame by frame in python. Inspired
@@ -64,6 +73,14 @@
 from . import groups
 
 
+with warnings.catch_warnings():
+    warnings.simplefilter('always', DeprecationWarning)
+    warnings.warn(('The Timeseries module and TimeseriesCollection will be '
+                   'removed in the 0.17 release. See issue #1372 '
+                   'https://github.com/MDAnalysis/mdanalysis/issues/1373'),
+                  DeprecationWarning)
+
+
 class TimeseriesCollection(object):
     '''A collection of timeseries objects.
 
@@ -81,6 +98,14 @@ class TimeseriesCollection(object):
        collection.clear()                             - clear the collection
        collection[i]                                  - access the i'th timeseries
        len(collection)                                - return the number of Timeseries added to the collection
+
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self):
@@ -186,7 +211,14 @@ def _getAuxData(self):
 
 
 class Timeseries(object):
-    '''Base timeseries class - define subclasses for specific timeseries computations
+    '''Base timeseries class - define subclasses for specific timeseries computations.
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self, code, atoms, dsize):
@@ -253,6 +285,13 @@ class Atom(Timeseries):
           can be a single :class:`~MDAnalysis.core.groups.Atom` object,
           a list of :class:`~MDAnalysis.core.groups.Atom` objects, or an
           :class:`~MDAnalysis.core.groups.AtomGroup`
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self, code, atoms):
@@ -281,8 +320,15 @@ class Bond(Timeseries):
 
            t = Bond(atoms)
 
-        *atoms* must contain 2 :class:`~MDAnalysis.core.groups.Atom` instances, either as a list or an
-        :class:`~MDAnalysis.core.groups.AtomGroup`
+    *atoms* must contain 2 :class:`~MDAnalysis.core.groups.Atom` instances, either as a list or an
+    :class:`~MDAnalysis.core.groups.AtomGroup`
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self, atoms):
@@ -296,8 +342,15 @@ class Angle(Timeseries):
 
            t = Angle(atoms)
 
-        atoms must contain 3 :class:`~MDAnalysis.core.groups.Atom` instances, either as a list or an
-        :class:`~MDAnalysis.core.groups.AtomGroup`
+    atoms must contain 3 :class:`~MDAnalysis.core.groups.Atom` instances,
+    either as a list or an :class:`~MDAnalysis.core.groups.AtomGroup`
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self, atoms):
@@ -311,8 +364,15 @@ class Dihedral(Timeseries):
 
            t = Dihedral(atoms)
 
-        atoms must contain 4 :class:`~MDAnalysis.core.groups.Atom` objects, either as a list or an
-        :class:`~MDAnalysis.core.groups.AtomGroup`
+    atoms must contain 4 :class:`~MDAnalysis.core.groups.Atom` objects, either
+    as a list or an :class:`~MDAnalysis.core.groups.AtomGroup`
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self, atoms):
@@ -326,9 +386,16 @@ class Distance(Timeseries):
 
            t = Distance(code, atoms)
 
-        code is one of 'd' (distance vector), or 'r' (scalar distance)
-        atoms must contain 2 :class:`~MDAnalysis.core.groups.Atom` objects, either as a list or an
-        :class:`~MDAnalysis.core.groups.AtomGroup`
+    code is one of 'd' (distance vector), or 'r' (scalar distance) atoms must
+    contain 2 :class:`~MDAnalysis.core.groups.Atom` objects, either as a list
+    or an :class:`~MDAnalysis.core.groups.AtomGroup`
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self, code, atoms):
@@ -348,8 +415,16 @@ class CenterOfGeometry(Timeseries):
 
            t = CenterOfGeometry(atoms)
 
-        *atoms* can be a list of :class:`~MDAnalysis.core.groups.Atom`
-        objects, or a :class:`~MDAnalysis.core.groups.AtomGroup`
+    *atoms* can be a list of :class:`~MDAnalysis.core.groups.Atom` objects, or
+    a :class:`~MDAnalysis.core.groups.AtomGroup`
+
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self, atoms):
@@ -364,8 +439,15 @@ class CenterOfMass(Timeseries):
 
            t = CenterOfMass(atoms)
 
-        *atoms* can be a list of :class:`~MDAnalysis.core.groups.Atom`
-        objects or a :class:`~MDAnalysis.core.groups.AtomGroup`
+    *atoms* can be a list of :class:`~MDAnalysis.core.groups.Atom` objects or a
+    :class:`~MDAnalysis.core.groups.AtomGroup`
+
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
+
     '''
 
     def __init__(self, atoms):
@@ -380,38 +462,43 @@ class WaterDipole(Timeseries):
 
            d = WaterDipole(atoms)
 
-        *atoms* must contain 3 :class:`~MDAnalysis.core.groups.Atom`
-        objects, either as a list or an
-        :class:`~MDAnalysis.core.groups.AtomGroup`; the first one *must* be
-        the oxygen, the other two are the hydrogens.
+    *atoms* must contain 3 :class:`~MDAnalysis.core.groups.Atom` objects,
+    either as a list or an :class:`~MDAnalysis.core.groups.AtomGroup`; the
+    first one *must* be the oxygen, the other two are the hydrogens.
+
+    The vector ``d``, multiplied by the partial charge on the oxygen atom
+    (e.g. *q* = -0.0.834 for TIP3P water), gives the actual dipole moment.
 
-        The vector ``d``, multiplied by the partial charge on the oxygen atom
-        (e.g. *q* = -0.0.834 for TIP3P water), gives the actual dipole moment.
+    The vector is calculated from the positions of the oxygen atom
+    (:math:`\mathbf{x}_{\text{O}}`) and the two hydrogen atoms
+    (:math:`\mathbf{x}_{\text{H}_1}`, :math:`\mathbf{x}_{\text{H}_2}`) as
 
-        The vector is calculated from the positions of the oxygen atom
-        (:math:`\mathbf{x}_{\text{O}}`) and the two hydrogen atoms
-        (:math:`\mathbf{x}_{\text{H}_1}`, :math:`\mathbf{x}_{\text{H}_2}`) as
+    .. math::
 
-        .. math::
+       \mathbf{d} = \mathbf{x}_{\text{O}} - \frac{1}{2}(\mathbf{x}_{\text{H}_1} + \mathbf{x}_{\text{H}_2})
 
-           \mathbf{d} = \mathbf{x}_{\text{O}} - \frac{1}{2}(\mathbf{x}_{\text{H}_1} + \mathbf{x}_{\text{H}_2})
+    and the dipole moment vector is
 
-        and the dipole moment vector is
+    .. math::
 
-         .. math::
+       \boldsymbol{\mu} = q_{\text{O}} \mathbf{d}
 
-           \boldsymbol{\mu} = q_{\text{O}} \mathbf{d}
+    .. Note::
 
-        .. Note::
+       This will only work for water models that have half of the oxygen charge
+       on each hydrogen. The vector :math:`\mathbf{d}` has the opposite
+       direction of the dipole moment; multiplying with the oxygen charge
+       (:math:`q_{\text{O}}<0`) will flip the direction and produce the correct
+       orientation.
 
-           This will only work for water models that have half of the oxygen
-           charge on each hydrogen. The vector :math:`\mathbf{d}` has the
-           opposite direction of the dipole moment; multiplying with the oxygen
-           charge (:math:`q_{\text{O}}<0`) will flip the direction and produce
-           the correct orientation.
+       There are no sanity checks; *if the first atom in a water
+       molecule is not oxygen then results will be wrong.*
 
-           There are no sanity checks; *if the first atom in a water
-           molecule is not oxygen then results will be wrong.*
+    .. deprecated:: 0.16.2
+       The Timeseries functionality (in particular correl) will be removed in
+       the 0.17 release. See issue `#1372
+       <https://github.com/MDAnalysis/mdanalysis/issues/1373>`_ for more
+       details. Use :class:`MDAnalysis.analysis.base.AnalysisFromFunction` instead.
 
     '''
 

diff --git a/package/MDAnalysis/core/__init__.py b/package/MDAnalysis/core/__init__.py
@@ -30,7 +30,8 @@
 :class:`~MDAnalysis.core.groups.AtomGroup` and return another
 :class:`~MDAnalysis.core.groups.AtomGroup`.
 
-:mod:`~MDAnalysis.Timeseries` are a convenient way to analyse trajectories.
+:mod:`~MDAnalysis.core.Timeseries` are a convenient way to analyse
+trajectories.
 
 To get started, load the Universe::
 
@@ -56,6 +57,12 @@
 Flags
 -----
 
+.. deprecated:: 0.16.2
+   The flags registry will be removed in release 1.0.
+   Use keyword arguments for functions to obtain the desired behavior.
+   See issue `#782 <https://github.com/MDAnalysis/mdanalysis/issues/782>`_
+   for more details.
+
 (This is an advanced topic and can probably be skipped by most people.)
 
 There are a number flags that influence how MDAnalysis behaves. They are accessible
@@ -92,8 +99,9 @@
 __all__ = ['AtomGroup', 'Selection', 'Timeseries']
 
 
-# set up flags for core routines (more convoluted than strictly necessary but should
-# be clean to add more flags if needed)
+# set up flags for core routines (more convoluted than strictly necessary but
+# should be clean to add more flags if needed)
+
 class Flags(dict):
     """Global registry of flags. Acts like a dict for item access.
 
@@ -109,6 +117,13 @@ class Flags(dict):
 
     New flags are added with the :meth:`Flags.register` method which takes a new :class:`Flag`
     instance as an argument.
+
+    .. deprecated:: 0.16.2
+       The flags registry will be removed in release 1.0.
+       Use keyword arguments for functions to obtain the desired behavior.
+       See issue `#782 <https://github.com/MDAnalysis/mdanalysis/issues/782>`_
+       for more details.
+
     """
 
     def __init__(self, *args):
@@ -180,7 +195,14 @@ def __getitem__(self, key):
 
 
 class Flag(object):
-    """A Flag, essentially a variable that knows its default and legal values."""
+    """A Flag, essentially a variable that knows its default and legal values.
+
+    .. deprecated:: 0.16.2
+       The flags registry will be removed in release 1.0.
+       Use keyword arguments for functions to obtain the desired behavior.
+       See issue `#782 <https://github.com/MDAnalysis/mdanalysis/issues/782>`_
+       for more details.
+    """
 
     def __init__(self, name, default, mapping=None, doc=None):
         """Create a new flag which will be registered with Flags.