added support for nearest upsample + comments on returns for upsampled functions (#17498)

Author: ab320012

doc/source/api.rst

@@ -2025,6 +2025,7 @@ Upsampling
    Resampler.backfill
    Resampler.bfill
    Resampler.pad
+   Resampler.nearest
    Resampler.fillna
    Resampler.asfreq
    Resampler.interpolate

doc/source/whatsnew/v0.21.0.txt

@@ -28,6 +28,7 @@ New features
   and :class:`~pandas.ExcelWriter` to work properly with the file system path protocol (:issue:`13823`)
 - Added ``skipna`` parameter to :func:`~pandas.api.types.infer_dtype` to
   support type inference in the presence of missing values (:issue:`17059`).
+- :class:`~pandas.Resampler.nearest` is added to support nearest-neighbor upsampling (:issue:`17496`).
 
 .. _whatsnew_0210.enhancements.infer_objects:
 

pandas/core/resample.py

@@ -455,6 +455,10 @@ def pad(self, limit=None):
         limit : integer, optional
             limit of how many values to fill
 
+        Returns
+        -------
+        an upsampled Series
+
         See Also
         --------
         Series.fillna
@@ -463,6 +467,28 @@ def pad(self, limit=None):
         return self._upsample('pad', limit=limit)
     ffill = pad
 
+    def nearest(self, limit=None):
+        """
+        Fill values with nearest neighbor starting from center
+
+        Parameters
+        ----------
+        limit : integer, optional
+            limit of how many values to fill
+
+            .. versionadded:: 0.21.0
+
+        Returns
+        -------
+        an upsampled Series
+
+        See Also
+        --------
+        Series.fillna
+        DataFrame.fillna
+        """
+        return self._upsample('nearest', limit=limit)
+
     def backfill(self, limit=None):
         """
         Backward fill the values
@@ -472,6 +498,10 @@ def backfill(self, limit=None):
         limit : integer, optional
             limit of how many values to fill
 
+        Returns
+        -------
+        an upsampled Series
+
         See Also
         --------
         Series.fillna

pandas/tests/test_resample.py

@@ -1329,6 +1329,14 @@ def test_upsample_with_limit(self):
         expected = ts.reindex(result.index, method='ffill', limit=2)
         assert_series_equal(result, expected)
 
+    def test_nearest_upsample_with_limit(self):
+        rng = date_range('1/1/2000', periods=3, freq='5t')
+        ts = Series(np.random.randn(len(rng)), rng)
+
+        result = ts.resample('t').nearest(limit=2)
+        expected = ts.reindex(result.index, method='nearest', limit=2)
+        assert_series_equal(result, expected)
+
     def test_resample_ohlc(self):
         s = self.series
 
@@ -2934,6 +2942,24 @@ def test_getitem_multiple(self):
         result = r['buyer'].count()
         assert_series_equal(result, expected)
 
+    def test_nearest(self):
+
+        # GH 17496
+        # Resample nearest
+        index = pd.date_range('1/1/2000', periods=3, freq='T')
+        result = pd.Series(range(3), index=index).resample('20s').nearest()
+
+        expected = pd.Series(
+            np.array([0, 0, 1, 1, 1, 2, 2]),
+            index=pd.DatetimeIndex(
+                ['2000-01-01 00:00:00', '2000-01-01 00:00:20',
+                 '2000-01-01 00:00:40', '2000-01-01 00:01:00',
+                 '2000-01-01 00:01:20', '2000-01-01 00:01:40',
+                 '2000-01-01 00:02:00'],
+                dtype='datetime64[ns]',
+                freq='20S'))
+        assert_series_equal(result, expected)
+
     def test_methods(self):
         g = self.frame.groupby('A')
         r = g.resample('2s')
@@ -2960,7 +2986,7 @@ def test_methods(self):
             expected = g.B.apply(lambda x: getattr(x.resample('2s'), f)())
             assert_series_equal(result, expected)
 
-        for f in ['backfill', 'ffill', 'asfreq']:
+        for f in ['nearest', 'backfill', 'ffill', 'asfreq']:
             result = getattr(r, f)()
             expected = g.apply(lambda x: getattr(x.resample('2s'), f)())
             assert_frame_equal(result, expected)