DEPR: Panel4d and panelND

closes pandas-dev#13564

Author: jreback

doc/source/dsintro.rst

@@ -941,6 +941,10 @@ method:
 Panel4D (Experimental)
 ----------------------
 
+.. warning::
+
+   In 0.19.0 ``Panel4D` is deprecated and will be removed in a future version. The recommended way to represent these types of n-dimensional data are with the `xarray package <http://xarray.pydata.org/en/stable/>`__. Pandas provides a :meth:`~Panel4D.to_xarray` method to automate this conversion.
+
 ``Panel4D`` is a 4-Dimensional named container very much like a ``Panel``, but
 having 4 named dimensions. It is intended as a test bed for more N-Dimensional named
 containers.
@@ -1026,6 +1030,10 @@ copy by default unless the data are heterogeneous):
 PanelND (Experimental)
 ----------------------
 
+.. warning::
+
+   In 0.19.0 ``PanelND` is deprecated and will be removed in a future version. The recommended way to represent these types of n-dimensional data are with the `xarray package <http://xarray.pydata.org/en/stable/>`__.
+
 PanelND is a module with a set of factory functions to enable a user to construct N-dimensional named
 containers like Panel4D, with a custom set of axis labels. Thus a domain-specific container can easily be
 created.

doc/source/whatsnew/v0.19.0.txt

@@ -613,7 +613,7 @@ Deprecations
 - ``Timestamp.offset`` property (and named arg in the constructor), has been deprecated in favor of ``freq`` (:issue:`12160`)
 - ``pd.tseries.util.pivot_annual`` is deprecated. Use ``pivot_table`` as alternative, an example is :ref:`here <cookbook.pivot>` (:issue:`736`)
 - ``pd.tseries.util.isleapyear`` has been deprecated and will be removed in a subsequent release. Datetime-likes now have a ``.is_leap_year`` property. (:issue:`13727`)
-
+- ``Panel4D`` and ``PanelND`` constructors are deprecated and will be removed in a future version. The recommended way to represent these types of n-dimensional data are with the `xarray package <http://xarray.pydata.org/en/stable/>`__. Pandas provides a :meth:`~Panel4D.to_xarray` method to automate this conversion. (:issue:`13564`)
 
 .. _whatsnew_0190.prior_deprecations:
 

pandas/api/tests/test_api.py

@@ -58,11 +58,10 @@ class TestPDApi(Base, tm.TestCase):
 
     # these are already deprecated; awaiting removal
     deprecated_classes = ['SparsePanel', 'TimeSeries', 'WidePanel',
-                          'SparseTimeSeries']
+                          'SparseTimeSeries', 'Panel', 'Panel4D']
 
     # these should be deperecated in the future
-    deprecated_classes_in_future = ['Panel', 'Panel4D',
-                                    'SparseList', 'Term']
+    deprecated_classes_in_future = ['SparseList', 'Term']
 
     # these should be removed from top-level namespace
     remove_classes_from_top_level_namespace = ['Expr']

pandas/core/common.py

@@ -14,7 +14,7 @@
 from pandas.compat import long, zip, iteritems
 from pandas.core.config import get_option
 from pandas.types.generic import ABCSeries
-from pandas.types.common import _NS_DTYPE, is_integer
+from pandas.types.common import _NS_DTYPE
 from pandas.types.inference import _iterable_not_string
 from pandas.types.missing import isnull
 from pandas.api import types
@@ -31,7 +31,7 @@ def wrapper(*args, **kwargs):
             warnings.warn("pandas.core.common.{t} is deprecated. "
                           "import from the public API: "
                           "pandas.api.types.{t} instead".format(t=t),
-                          FutureWarning, stacklevel=2)
+                          FutureWarning, stacklevel=3)
             return getattr(types, t)(*args, **kwargs)
         return wrapper
 
@@ -57,7 +57,7 @@ def wrapper(*args, **kwargs):
                           "These are not longer public API functions, "
                           "but can be imported from "
                           "pandas.types.common.{t} instead".format(t=t),
-                          FutureWarning, stacklevel=2)
+                          FutureWarning, stacklevel=3)
             return getattr(common, t)(*args, **kwargs)
         return wrapper
 
@@ -578,7 +578,7 @@ def _random_state(state=None):
     np.random.RandomState
     """
 
-    if is_integer(state):
+    if types.is_integer(state):
         return np.random.RandomState(state)
     elif isinstance(state, np.random.RandomState):
         return state

pandas/core/panel4d.py

@@ -1,5 +1,6 @@
 """ Panel4D: a 4-d dict like collection of panels """
 
+import warnings
 from pandas.core.panelnd import create_nd_panel_factory
 from pandas.core.panel import Panel
 
@@ -18,6 +19,11 @@
     having 4 named dimensions. It is intended as a test bed for more
     N-Dimensional named containers.
 
+    DEPRECATED. Panel4D is deprecated and will be removed in a future version.
+    The recommended way to represent these types of n-dimensional data are with
+    the `xarray package <http://xarray.pydata.org/en/stable/>`__.
+    Pandas provides a `.to_xarray()` method to automate this conversion.
+
     Parameters
     ----------
     data : ndarray (labels x items x major x minor), or dict of Panels
@@ -37,6 +43,15 @@
 def panel4d_init(self, data=None, labels=None, items=None, major_axis=None,
                  minor_axis=None, copy=False, dtype=None):
 
+    # deprecation GH13564
+    warnings.warn("\nPanel4D is deprecated and will be removed in a "
+                  "future version.\nThe recommended way to represent "
+                  "these types of n-dimensional data are with\n"
+                  "the `xarray package "
+                  "<http://xarray.pydata.org/en/stable/>`__.\n"
+                  "Pandas provides a `.to_xarray()` method to help "
+                  "automate this conversion.\n",
+                  FutureWarning, stacklevel=2)
     self._init_data(data=data, labels=labels, items=items,
                     major_axis=major_axis, minor_axis=minor_axis, copy=copy,
                     dtype=dtype)

pandas/core/panelnd.py

@@ -1,5 +1,6 @@
 """ Factory methods to create N-D panels """
 
+import warnings
 from pandas.compat import zip
 import pandas.compat as compat
 
@@ -8,6 +9,11 @@ def create_nd_panel_factory(klass_name, orders, slices, slicer, aliases=None,
                             stat_axis=2, info_axis=0, ns=None):
     """ manufacture a n-d class:
 
+    DEPRECATED. Panelnd is deprecated and will be removed in a future version.
+    The recommended way to represent these types of n-dimensional data are with
+    the `xarray package <http://xarray.pydata.org/en/stable/>`__.
+    Pandas provides a `.to_xarray()` method to automate this conversion.
+
     Parameters
     ----------
     klass_name : the klass name
@@ -44,6 +50,18 @@ def create_nd_panel_factory(klass_name, orders, slices, slicer, aliases=None,
 
     # define the methods ####
     def __init__(self, *args, **kwargs):
+
+        # deprecation GH13564
+        warnings.warn("\n{klass} is deprecated and will be removed in a "
+                      "future version.\nThe recommended way to represent "
+                      "these types of n-dimensional data are with the\n"
+                      "`xarray package "
+                      "<http://xarray.pydata.org/en/stable/>`__.\n"
+                      "Pandas provides a `.to_xarray()` method to help "
+                      "automate this conversion.\n".format(
+                          klass=self.__class__.__name__),
+                      FutureWarning, stacklevel=2)
+
         if not (kwargs.get('data') or len(args)):
             raise Exception("must supply at least a data argument to [%s]" %
                             klass_name)

pandas/io/tests/test_packers.py

@@ -1,6 +1,5 @@
 import nose
 
-import warnings
 import os
 import datetime
 import numpy as np
@@ -545,7 +544,8 @@ def test_sparse_frame(self):
 
     def test_sparse_panel(self):
 
-        with warnings.catch_warnings(record=True):
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
 
             items = ['x', 'y', 'z']
             p = Panel(dict((i, tm.makeDataFrame().ix[:2, :2]) for i in items))