DEPR: Panel deprecated

closes pandas-dev#13563

doc/source/whatsnew/v0.20.0.txt

@@ -11,6 +11,7 @@ Highlights include:
 
 - Building pandas for development now requires ``cython >= 0.23`` (:issue:`14831`)
 - The ``.ix`` indexer has been deprecated, see :ref:`here <whatsnew_0200.api_breaking.deprecate_ix>`
+- ``Panel`` has been deprecated, see :ref:`here <whatsnew_0200.api_breaking.deprecate_panel>`
 - Switched the test framework to `pytest`_ (:issue:`13097`)
 - A new orient for JSON serialization, ``orient='table'``, that uses the Table Schema spec, see :ref: `here <whatsnew_0200.enhancements.table_schema>`
 
@@ -284,6 +285,33 @@ Using ``.iloc``. Here we will get the location of the 'A' column, then use *posi
   df.iloc[[0, 2], df.columns.get_loc('A')]
 
 
+.. _whatsnew_0200.api_breaking.deprecate_panel:
+
+Deprecate Panel
+^^^^^^^^^^^^^^^
+
+- The ``Panel`` constructor is deprecated and will be removed in a future version. The recommended way to represent 3-D data are
+with a ``MultiIndex``on a ``DataFrame`` via the :meth:`~Panel.to_frame` or with the `xarray package <http://xarray.pydata.org/en/stable/>`__. Pandas
+provides a :meth:`~Panel.to_xarray` method to automate this conversion (:issue:`13563`).
+
+.. ipython:: python
+   :okwarning:
+
+   p = tm.makePanel()
+   p
+
+Convert to a MultiIndex DataFrame
+
+.. ipython:: python
+
+   p.frame()
+
+Convert to an xarray DataArray
+
+.. ipython:: python
+
+   p.to_xarray()
+
 .. _whatsnew.api_breaking.io_compat
 
 Possible incompat for HDF5 formats for pandas < 0.13.0

pandas/core/categorical.py

@@ -563,8 +563,8 @@ def _validate_categories(cls, categories, fastpath=False):
             # we don't allow NaNs in the categories themselves
 
             if categories.hasnans:
-                # NaNs in cats deprecated in 0.17,
-                # remove in 0.18 or 0.19 GH 10748
+                # NaNs in cats deprecated in 0.17
+                # GH 10748
                 msg = ('\nSetting NaNs in `categories` is deprecated and '
                        'will be removed in a future version of pandas.')
                 warn(msg, FutureWarning, stacklevel=3)

pandas/core/panel.py

@@ -132,6 +132,18 @@ def _constructor(self):
 
     def __init__(self, data=None, items=None, major_axis=None, minor_axis=None,
                  copy=False, dtype=None):
+        # deprecation GH13563
+        warnings.warn("\nPanel is deprecated and will be removed in a "
+                      "future version.\nThe recommended way to represent "
+                      "these types of 3-dimensional data are with a "
+                      "MultiIndex on a DataFrame, via the "
+                      "Panel.to_frame() method\n"
+                      "alternatively, you can use the `xarray package "
+                      "<http://xarray.pydata.org/en/stable/>`__.\n"
+                      "Pandas provides a `.to_xarray()` method to help "
+                      "automate this conversion.\n",
+                      DeprecationWarning, stacklevel=3)
+
         self._init_data(data=data, items=items, major_axis=major_axis,
                         minor_axis=minor_axis, copy=copy, dtype=dtype)
 

pandas/io/pytables.py

@@ -2094,7 +2094,17 @@ def convert(self, values, nan_rep, encoding):
 
                 # we have a categorical
                 categories = self.metadata
-                self.data = Categorical.from_codes(self.data.ravel(),
+                codes = self.data.ravel()
+
+                # if we have stored a NaN in the categories
+                # then strip it; in theory we could have BOTH
+                # -1s in the codes and nulls :<
+                mask = isnull(categories)
+                if mask.any():
+                    categories = categories[~mask]
+                    codes[codes != -1] -= mask.astype(int).cumsum().values
+
+                self.data = Categorical.from_codes(codes,
                                                    categories=categories,
                                                    ordered=self.ordered)
 
@@ -3404,10 +3414,12 @@ def create_axes(self, axes, obj, validate=True, nan_rep=None,
                 if existing_table is not None:
                     indexer = len(self.non_index_axes)
                     exist_axis = existing_table.non_index_axes[indexer][1]
-                    if append_axis != exist_axis:
+                    if not array_equivalent(np.array(append_axis),
+                                            np.array(exist_axis)):
 
                         # ahah! -> reindex
-                        if sorted(append_axis) == sorted(exist_axis):
+                        if array_equivalent(np.array(sorted(append_axis)),
+                                            np.array(sorted(exist_axis))):
                             append_axis = exist_axis
 
                 # the non_index_axes info