DOC/DEPR: pivot_annual

closes #736

Author: sinhrks <sinhrks@gmail.com>

Closes #13706 from sinhrks/pivot_annual and squashes the following commits:

d097bab [sinhrks] DOC/DEPR: pivot_annual

doc/source/cookbook.rst

@@ -679,6 +679,19 @@ The :ref:`Pivot <reshaping.pivot>` docs.
                        'Employed' : lambda x : sum(x),
                        'Grade' : lambda x : sum(x) / len(x)})
 
+`Plot pandas DataFrame with year over year data
+<http://stackoverflow.com/questions/30379789/plot-pandas-data-frame-with-year-over-year-data>`__
+
+To create year and month crosstabulation:
+
+.. ipython:: python
+
+   df = pd.DataFrame({'value': np.random.randn(36)},
+                     index=pd.date_range('2011-01-01', freq='M', periods=36))
+
+   pd.pivot_table(df, index=df.index.month, columns=df.index.year,
+                  values='value', aggfunc='sum')
+
 Apply
 *****
 

doc/source/whatsnew/v0.19.0.txt

@@ -589,7 +589,7 @@ Deprecations
 - ``as_recarray`` has been deprecated in ``pd.read_csv()`` and will be removed in a future version (:issue:`13373`)
 - top-level ``pd.ordered_merge()`` has been renamed to ``pd.merge_ordered()`` and the original name will be removed in a future version (:issue:`13358`)
 - ``Timestamp.offset`` property (and named arg in the constructor), has been deprecated in favor of ``freq`` (:issue:`12160`)
-
+- ``pivot_annual`` is deprecated. Use ``pivot_table`` as alternative, an example is :ref:`here <cookbook.pivot>` (:issue:`736`)
 
 .. _whatsnew_0190.prior_deprecations:
 

pandas/tseries/tests/test_util.py

@@ -21,7 +21,8 @@ def test_daily(self):
         rng = date_range('1/1/2000', '12/31/2004', freq='D')
         ts = Series(np.random.randn(len(rng)), index=rng)
 
-        annual = pivot_annual(ts, 'D')
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            annual = pivot_annual(ts, 'D')
 
         doy = ts.index.dayofyear
         doy[(~isleapyear(ts.index.year)) & (doy >= 60)] += 1
@@ -53,7 +54,8 @@ def test_hourly(self):
         hoy[~isleapyear(ts_hourly.index.year) & (hoy >= 1416)] += 24
         hoy += 1
 
-        annual = pivot_annual(ts_hourly)
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            annual = pivot_annual(ts_hourly)
 
         ts_hourly = ts_hourly.astype(float)
         for i in [1, 1416, 1417, 1418, 1439, 1440, 1441, 8784]:
@@ -78,7 +80,8 @@ def test_monthly(self):
         rng = date_range('1/1/2000', '12/31/2004', freq='M')
         ts = Series(np.random.randn(len(rng)), index=rng)
 
-        annual = pivot_annual(ts, 'M')
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            annual = pivot_annual(ts, 'M')
 
         month = ts.index.month
         for i in range(1, 13):

pandas/tseries/util.py

@@ -1,3 +1,5 @@
+import warnings
+
 from pandas.compat import lrange
 import numpy as np
 from pandas.types.common import _ensure_platform_int
@@ -7,6 +9,8 @@
 
 def pivot_annual(series, freq=None):
     """
+    Deprecated. Use ``pivot_table`` instead.
+
     Group a series by years, taking leap years into account.
 
     The output has as many rows as distinct years in the original series,
@@ -35,6 +39,10 @@ def pivot_annual(series, freq=None):
     -------
     annual : DataFrame
     """
+
+    msg = "pivot_annual is deprecated. Use pivot_table instead"
+    warnings.warn(msg, FutureWarning)
+
     index = series.index
     year = index.year
     years = nanops.unique1d(year)