DOC: Remove makePanel from docs (pandas-dev#25609) (pandas-dev#25612)

jreback · Mar 10, 2019 · df771cc · df771cc
1 parent e28ae70
commit df771cc
Show file tree

Hide file tree

Showing 4 changed files with 220 additions and 97 deletions.
diff --git a/doc/source/getting_started/dsintro.rst b/doc/source/getting_started/dsintro.rst
@@ -1030,47 +1030,3 @@ method:
                     major_axis=pd.date_range('1/1/2000', periods=5),
                     minor_axis=['a', 'b', 'c', 'd'])
    panel.to_frame()
-
-
-.. _dsintro.deprecate_panel:
-
-Deprecate Panel
----------------
-
-Over the last few years, pandas has increased in both breadth and depth, with new features,
-datatype support, and manipulation routines. As a result, supporting efficient indexing and functional
-routines for ``Series``, ``DataFrame`` and ``Panel`` has contributed to an increasingly fragmented and
-difficult-to-understand code base.
-
-The 3-D structure of a ``Panel`` is much less common for many types of data analysis,
-than the 1-D of the ``Series`` or the 2-D of the ``DataFrame``. Going forward it makes sense for
-pandas to focus on these areas exclusively.
-
-Oftentimes, one can simply use a MultiIndex ``DataFrame`` for easily working with higher dimensional data.
-
-In addition, the ``xarray`` package was built from the ground up, specifically in order to
-support the multi-dimensional analysis that is one of ``Panel`` s main use cases.
-`Here is a link to the xarray panel-transition documentation <https://xarray.pydata.org/en/stable/pandas.html#panel-transition>`__.
-
-.. ipython:: python
-   :okwarning:
-
-   import pandas.util.testing as tm
-   p = tm.makePanel()
-   p
-
-Convert to a MultiIndex DataFrame.
-
-.. ipython:: python
-   :okwarning:
-
-   p.to_frame()
-
-Alternatively, one can convert to an xarray ``DataArray``.
-
-.. ipython:: python
-   :okwarning:
-
-   p.to_xarray()
-
-You can see the full-documentation for the `xarray package <https://xarray.pydata.org/en/stable/>`__.
diff --git a/doc/source/whatsnew/v0.13.1.rst b/doc/source/whatsnew/v0.13.1.rst
@@ -222,60 +222,155 @@ Enhancements
 
 - Panel :meth:`~pandas.Panel.apply` will work on non-ufuncs. See :ref:`the docs<basics.apply>`.
 
-  .. ipython:: python
+  .. code-block:: ipython
+
+      In [28]: import pandas.util.testing as tm
+
+      In [29]: panel = tm.makePanel(5)
 
-     import pandas.util.testing as tm
-     panel = tm.makePanel(5)
-     panel
-     panel['ItemA']
+      In [30]: panel
+      Out[30]:
+      <class 'pandas.core.panel.Panel'>
+      Dimensions: 3 (items) x 5 (major_axis) x 4 (minor_axis)
+      Items axis: ItemA to ItemC
+      Major_axis axis: 2000-01-03 00:00:00 to 2000-01-07 00:00:00
+      Minor_axis axis: A to D
+
+      In [31]: panel['ItemA']
+      Out[31]:
+                         A         B         C         D
+      2000-01-03 -0.673690  0.577046 -1.344312 -1.469388
+      2000-01-04  0.113648 -1.715002  0.844885  0.357021
+      2000-01-05 -1.478427 -1.039268  1.075770 -0.674600
+      2000-01-06  0.524988 -0.370647 -0.109050 -1.776904
+      2000-01-07  0.404705 -1.157892  1.643563 -0.968914
+
+      [5 rows x 4 columns]
 
   Specifying an ``apply`` that operates on a Series (to return a single element)
 
-  .. ipython:: python
+  .. code-block:: ipython
+
+      In [32]: panel.apply(lambda x: x.dtype, axis='items')
+      Out[32]:
+                        A        B        C        D
+      2000-01-03  float64  float64  float64  float64
+      2000-01-04  float64  float64  float64  float64
+      2000-01-05  float64  float64  float64  float64
+      2000-01-06  float64  float64  float64  float64
+      2000-01-07  float64  float64  float64  float64
 
-     panel.apply(lambda x: x.dtype, axis='items')
+      [5 rows x 4 columns]
 
   A similar reduction type operation
 
-  .. ipython:: python
+  .. code-block:: ipython
+
+      In [33]: panel.apply(lambda x: x.sum(), axis='major_axis')
+      Out[33]:
+            ItemA     ItemB     ItemC
+      A -1.108775 -1.090118 -2.984435
+      B -3.705764  0.409204  1.866240
+      C  2.110856  2.960500 -0.974967
+      D -4.532785  0.303202 -3.685193
 
-     panel.apply(lambda x: x.sum(), axis='major_axis')
+      [4 rows x 3 columns]
 
   This is equivalent to
 
-  .. ipython:: python
+  .. code-block:: ipython
+
+      In [34]: panel.sum('major_axis')
+      Out[34]:
+            ItemA     ItemB     ItemC
+      A -1.108775 -1.090118 -2.984435
+      B -3.705764  0.409204  1.866240
+      C  2.110856  2.960500 -0.974967
+      D -4.532785  0.303202 -3.685193
 
-     panel.sum('major_axis')
+      [4 rows x 3 columns]
 
   A transformation operation that returns a Panel, but is computing
   the z-score across the major_axis
 
-  .. ipython:: python
+  .. code-block:: ipython
 
-     result = panel.apply(lambda x: (x - x.mean()) / x.std(),
-                          axis='major_axis')
-     result
-     result['ItemA']
+      In [35]: result = panel.apply(lambda x: (x - x.mean()) / x.std(),
+        ....:                      axis='major_axis')
+        ....:
+
+      In [36]: result
+      Out[36]:
+      <class 'pandas.core.panel.Panel'>
+      Dimensions: 3 (items) x 5 (major_axis) x 4 (minor_axis)
+      Items axis: ItemA to ItemC
+      Major_axis axis: 2000-01-03 00:00:00 to 2000-01-07 00:00:00
+      Minor_axis axis: A to D
+
+      In [37]: result['ItemA']                           # noqa E999
+      Out[37]:
+                        A         B         C         D
+      2000-01-03 -0.535778  1.500802 -1.506416 -0.681456
+      2000-01-04  0.397628 -1.108752  0.360481  1.529895
+      2000-01-05 -1.489811 -0.339412  0.557374  0.280845
+      2000-01-06  0.885279  0.421830 -0.453013 -1.053785
+      2000-01-07  0.742682 -0.474468  1.041575 -0.075499
+
+      [5 rows x 4 columns]
 
 - Panel :meth:`~pandas.Panel.apply` operating on cross-sectional slabs. (:issue:`1148`)
 
-  .. ipython:: python
+  .. code-block:: ipython
 
-     def f(x):
-         return ((x.T - x.mean(1)) / x.std(1)).T
+      In [38]: def f(x):
+         ....:     return ((x.T - x.mean(1)) / x.std(1)).T
+         ....:
 
-     result = panel.apply(f, axis=['items', 'major_axis'])
-     result
-     result.loc[:, :, 'ItemA']
+      In [39]: result = panel.apply(f, axis=['items', 'major_axis'])
 
-  This is equivalent to the following
+      In [40]: result
+      Out[40]:
+      <class 'pandas.core.panel.Panel'>
+      Dimensions: 4 (items) x 5 (major_axis) x 3 (minor_axis)
+      Items axis: A to D
+      Major_axis axis: 2000-01-03 00:00:00 to 2000-01-07 00:00:00
+      Minor_axis axis: ItemA to ItemC
 
-  .. ipython:: python
+      In [41]: result.loc[:, :, 'ItemA']
+      Out[41]:
+                         A         B         C         D
+      2000-01-03  0.012922 -0.030874 -0.629546 -0.757034
+      2000-01-04  0.392053 -1.071665  0.163228  0.548188
+      2000-01-05 -1.093650 -0.640898  0.385734 -1.154310
+      2000-01-06  1.005446 -1.154593 -0.595615 -0.809185
+      2000-01-07  0.783051 -0.198053  0.919339 -1.052721
+
+      [5 rows x 4 columns]
 
-     result = pd.Panel({ax: f(panel.loc[:, :, ax]) for ax in panel.minor_axis})
+  This is equivalent to the following
+
+  .. code-block:: ipython
 
-     result
-     result.loc[:, :, 'ItemA']
+      In [42]: result = pd.Panel({ax: f(panel.loc[:, :, ax]) for ax in panel.minor_axis})
+
+      In [43]: result
+      Out[43]:
+      <class 'pandas.core.panel.Panel'>
+      Dimensions: 4 (items) x 5 (major_axis) x 3 (minor_axis)
+      Items axis: A to D
+      Major_axis axis: 2000-01-03 00:00:00 to 2000-01-07 00:00:00
+      Minor_axis axis: ItemA to ItemC
+
+      In [44]: result.loc[:, :, 'ItemA']
+      Out[44]:
+                         A         B         C         D
+      2000-01-03  0.012922 -0.030874 -0.629546 -0.757034
+      2000-01-04  0.392053 -1.071665  0.163228  0.548188
+      2000-01-05 -1.093650 -0.640898  0.385734 -1.154310
+      2000-01-06  1.005446 -1.154593 -0.595615 -0.809185
+      2000-01-07  0.783051 -0.198053  0.919339 -1.052721
+
+      [5 rows x 4 columns]
 
 Performance
 ~~~~~~~~~~~

diff --git a/doc/source/whatsnew/v0.20.0.rst b/doc/source/whatsnew/v0.20.0.rst
@@ -45,11 +45,6 @@ Check the :ref:`API Changes <whatsnew_0200.api_breaking>` and :ref:`deprecations
 New features
 ~~~~~~~~~~~~
 
-.. ipython:: python
-   :suppress:
-
-   import pandas.util.testing as tm
-
 .. _whatsnew_0200.enhancements.agg:
 
 ``agg`` API for DataFrame/Series
@@ -1363,24 +1358,65 @@ Deprecate Panel
 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. For more details see :ref:`Deprecate Panel <dsintro.deprecate_panel>` documentation. (:issue:`13563`).
 
-.. ipython:: python
-   :okwarning:
+.. code-block:: ipython
 
-   p = tm.makePanel()
-   p
+    In [133]: import pandas.util.testing as tm
+
+    In [134]: p = tm.makePanel()
+
+    In [135]: p
+    Out[135]:
+    <class 'pandas.core.panel.Panel'>
+    Dimensions: 3 (items) x 3 (major_axis) x 4 (minor_axis)
+    Items axis: ItemA to ItemC
+    Major_axis axis: 2000-01-03 00:00:00 to 2000-01-05 00:00:00
+    Minor_axis axis: A to D
 
 Convert to a MultiIndex DataFrame
 
-.. ipython:: python
+.. code-block:: ipython
 
-   p.to_frame()
+    In [136]: p.to_frame()
+    Out[136]:
+                         ItemA     ItemB     ItemC
+    major      minor
+    2000-01-03 A      0.628776 -1.409432  0.209395
+               B      0.988138 -1.347533 -0.896581
+               C     -0.938153  1.272395 -0.161137
+               D     -0.223019 -0.591863 -1.051539
+    2000-01-04 A      0.186494  1.422986 -0.592886
+               B     -0.072608  0.363565  1.104352
+               C     -1.239072 -1.449567  0.889157
+               D      2.123692 -0.414505 -0.319561
+    2000-01-05 A      0.952478 -2.147855 -1.473116
+               B     -0.550603 -0.014752 -0.431550
+               C      0.139683 -1.195524  0.288377
+               D      0.122273 -1.425795 -0.619993
+
+    [12 rows x 3 columns]
 
 Convert to an xarray DataArray
 
-.. ipython:: python
-   :okwarning:
+.. code-block:: ipython
 
-   p.to_xarray()
+    In [137]: p.to_xarray()
+    Out[137]:
+    <xarray.DataArray (items: 3, major_axis: 3, minor_axis: 4)>
+    array([[[ 0.628776,  0.988138, -0.938153, -0.223019],
+            [ 0.186494, -0.072608, -1.239072,  2.123692],
+            [ 0.952478, -0.550603,  0.139683,  0.122273]],
+
+           [[-1.409432, -1.347533,  1.272395, -0.591863],
+            [ 1.422986,  0.363565, -1.449567, -0.414505],
+            [-2.147855, -0.014752, -1.195524, -1.425795]],
+
+           [[ 0.209395, -0.896581, -0.161137, -1.051539],
+            [-0.592886,  1.104352,  0.889157, -0.319561],
+            [-1.473116, -0.43155 ,  0.288377, -0.619993]]])
+    Coordinates:
+      * items       (items) object 'ItemA' 'ItemB' 'ItemC'
+      * major_axis  (major_axis) datetime64[ns] 2000-01-03 2000-01-04 2000-01-05
+      * minor_axis  (minor_axis) object 'A' 'B' 'C' 'D'
 
 .. _whatsnew_0200.api_breaking.deprecate_group_agg_dict:
 

diff --git a/doc/source/whatsnew/v0.23.0.rst b/doc/source/whatsnew/v0.23.0.rst
@@ -646,29 +646,65 @@ Deprecate Panel
 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. For more details see :ref:`Deprecate Panel <dsintro.deprecate_panel>` documentation. (:issue:`13563`, :issue:`18324`).
 
-.. ipython:: python
-   :suppress:
+.. code-block:: ipython
 
-   import pandas.util.testing as tm
+    In [75]: import pandas.util.testing as tm
 
-.. ipython:: python
-   :okwarning:
+    In [76]: p = tm.makePanel()
 
-   p = tm.makePanel()
-   p
+    In [77]: p
+    Out[77]:
+    <class 'pandas.core.panel.Panel'>
+    Dimensions: 3 (items) x 3 (major_axis) x 4 (minor_axis)
+    Items axis: ItemA to ItemC
+    Major_axis axis: 2000-01-03 00:00:00 to 2000-01-05 00:00:00
+    Minor_axis axis: A to D
 
 Convert to a MultiIndex DataFrame
 
-.. ipython:: python
+.. code-block:: ipython
 
-   p.to_frame()
+    In [78]: p.to_frame()
+    Out[78]:
+                         ItemA     ItemB     ItemC
+    major      minor
+    2000-01-03 A      0.469112  0.721555  0.404705
+               B     -1.135632  0.271860 -1.039268
+               C      0.119209  0.276232 -1.344312
+               D     -2.104569  0.113648 -0.109050
+    2000-01-04 A     -0.282863 -0.706771  0.577046
+               B      1.212112 -0.424972 -0.370647
+               C     -1.044236 -1.087401  0.844885
+               D     -0.494929 -1.478427  1.643563
+    2000-01-05 A     -1.509059 -1.039575 -1.715002
+               B     -0.173215  0.567020 -1.157892
+               C     -0.861849 -0.673690  1.075770
+               D      1.071804  0.524988 -1.469388
+
+    [12 rows x 3 columns]
 
 Convert to an xarray DataArray
 
-.. ipython:: python
-   :okwarning:
+.. code-block:: ipython
 
-   p.to_xarray()
+    In [79]: p.to_xarray()
+    Out[79]:
+    <xarray.DataArray (items: 3, major_axis: 3, minor_axis: 4)>
+    array([[[ 0.469112, -1.135632,  0.119209, -2.104569],
+            [-0.282863,  1.212112, -1.044236, -0.494929],
+            [-1.509059, -0.173215, -0.861849,  1.071804]],
+
+           [[ 0.721555,  0.27186 ,  0.276232,  0.113648],
+            [-0.706771, -0.424972, -1.087401, -1.478427],
+            [-1.039575,  0.56702 , -0.67369 ,  0.524988]],
+
+           [[ 0.404705, -1.039268, -1.344312, -0.10905 ],
+            [ 0.577046, -0.370647,  0.844885,  1.643563],
+            [-1.715002, -1.157892,  1.07577 , -1.469388]]])
+    Coordinates:
+      * items       (items) object 'ItemA' 'ItemB' 'ItemC'
+      * major_axis  (major_axis) datetime64[ns] 2000-01-03 2000-01-04 2000-01-05
+      * minor_axis  (minor_axis) object 'A' 'B' 'C' 'D'
 
 
 .. _whatsnew_0230.api_breaking.core_common: