From bd8607db2f513831241529981c99f6e7c279575c Mon Sep 17 00:00:00 2001
From: Kalyan Gokhale <4734245+KalyanGokhale@users.noreply.github.com>
Date: Fri, 6 Jul 2018 19:26:02 +0530
Subject: [PATCH] DEPR: Series.ptp() (#21614)

---
 doc/source/api.rst                    |  1 -
 doc/source/whatsnew/v0.24.0.txt       |  1 +
 pandas/core/generic.py                | 12 ++++++++++--
 pandas/tests/series/test_analytics.py | 24 +++++++++++++++++-------
 4 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/doc/source/api.rst b/doc/source/api.rst
index f19e5534fc1b34..fff944651588e6 100644
--- a/doc/source/api.rst
+++ b/doc/source/api.rst
@@ -435,7 +435,6 @@ Computations / Descriptive Stats
    Series.value_counts
    Series.compound
    Series.nonzero
-   Series.ptp
 
 
 Reindexing / Selection / Label manipulation
diff --git a/doc/source/whatsnew/v0.24.0.txt b/doc/source/whatsnew/v0.24.0.txt
index 691345ad26e586..b794b2bdf4aafd 100644
--- a/doc/source/whatsnew/v0.24.0.txt
+++ b/doc/source/whatsnew/v0.24.0.txt
@@ -239,6 +239,7 @@ Deprecations
 
 - :meth:`DataFrame.to_stata`, :meth:`read_stata`, :class:`StataReader` and :class:`StataWriter` have deprecated the ``encoding`` argument.  The encoding of a Stata dta file is determined by the file type and cannot be changed (:issue:`21244`).
 - :meth:`MultiIndex.to_hierarchical` is deprecated and will be removed in a future version  (:issue:`21613`)
+- :meth:`Series.ptp` is deprecated. Use ``numpy.ptp`` instead (:issue:`21614`)
 -
 
 .. _whatsnew_0240.prior_deprecations:
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
index 818dd1b408518f..ede4b6ac9fd644 100644
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -8876,13 +8876,21 @@ def _add_series_only_operations(cls):
         def nanptp(values, axis=0, skipna=True):
             nmax = nanops.nanmax(values, axis, skipna)
             nmin = nanops.nanmin(values, axis, skipna)
+            warnings.warn("Method .ptp is deprecated and will be removed "
+                          "in a future version. Use numpy.ptp instead.",
+                          FutureWarning, stacklevel=4)
             return nmax - nmin
 
         cls.ptp = _make_stat_function(
             cls, 'ptp', name, name2, axis_descr,
-            """Returns the difference between the maximum value and the
+            """
+            Returns the difference between the maximum value and the
             minimum value in the object. This is the equivalent of the
-            ``numpy.ndarray`` method ``ptp``.""",
+            ``numpy.ndarray`` method ``ptp``.
+
+            .. deprecated:: 0.24.0
+                Use numpy.ptp instead
+            """,
             nanptp)
 
     @classmethod
diff --git a/pandas/tests/series/test_analytics.py b/pandas/tests/series/test_analytics.py
index fcfaff9b11002d..a783563a04901f 100644
--- a/pandas/tests/series/test_analytics.py
+++ b/pandas/tests/series/test_analytics.py
@@ -1395,6 +1395,7 @@ def test_numpy_argmax_deprecated(self):
                                        s, out=data)
 
     def test_ptp(self):
+        # GH21614
         N = 1000
         arr = np.random.randn(N)
         ser = Series(arr)
@@ -1402,27 +1403,36 @@ def test_ptp(self):
 
         # GH11163
         s = Series([3, 5, np.nan, -3, 10])
-        assert s.ptp() == 13
-        assert pd.isna(s.ptp(skipna=False))
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            assert s.ptp() == 13
+            assert pd.isna(s.ptp(skipna=False))
 
         mi = pd.MultiIndex.from_product([['a', 'b'], [1, 2, 3]])
         s = pd.Series([1, np.nan, 7, 3, 5, np.nan], index=mi)
 
         expected = pd.Series([6, 2], index=['a', 'b'], dtype=np.float64)
-        tm.assert_series_equal(s.ptp(level=0), expected)
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            tm.assert_series_equal(s.ptp(level=0), expected)
 
         expected = pd.Series([np.nan, np.nan], index=['a', 'b'])
-        tm.assert_series_equal(s.ptp(level=0, skipna=False), expected)
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            tm.assert_series_equal(s.ptp(level=0, skipna=False), expected)
 
         with pytest.raises(ValueError):
-            s.ptp(axis=1)
+            with tm.assert_produces_warning(FutureWarning,
+                                            check_stacklevel=False):
+                s.ptp(axis=1)
 
         s = pd.Series(['a', 'b', 'c', 'd', 'e'])
         with pytest.raises(TypeError):
-            s.ptp()
+            with tm.assert_produces_warning(FutureWarning,
+                                            check_stacklevel=False):
+                s.ptp()
 
         with pytest.raises(NotImplementedError):
-            s.ptp(numeric_only=True)
+            with tm.assert_produces_warning(FutureWarning,
+                                            check_stacklevel=False):
+                s.ptp(numeric_only=True)
 
     def test_empty_timeseries_redections_return_nat(self):
         # covers #11245