ENH pandas-dev#3715: add documentation and tests

Author: nchmura4

doc/source/whatsnew/v0.20.0.txt

@@ -49,7 +49,7 @@ Other enhancements
 ^^^^^^^^^^^^^^^^^^
 
 - ``pd.read_excel`` now preserves sheet order when using ``sheetname=None`` (:issue:`9930`)
-- ``DataFrame.asfreq()`` now accepts a fill_value option to fill missing values during resampling (:issue:`3715`).
+- ``DataFrame.asfreq()`` now accepts a ``fill_value`` option to fill missing values during resampling (:issue:`3715`).
 
 .. _whatsnew_0200.api_breaking:
 

pandas/core/generic.py

@@ -4020,6 +4020,45 @@ def asfreq(self, freq, method=None, how=None, normalize=False,
         -------
         converted : type of caller
 
+        Examples
+        --------
+
+        Start by creating a series with 4 one minute timestamps.
+
+        >>> index = pd.date_range('1/1/2000', periods=4, freq='T')
+        >>> series = pd.Series([0.0, None, 2.0, 3.0], index=index)
+        >>> df = pd.DataFrame({'s':series})
+        >>> df
+                               s
+        2000-01-01 00:00:00    0.0
+        2000-01-01 00:01:00    NaN
+        2000-01-01 00:02:00    2.0
+        2000-01-01 00:03:00    3.0
+
+        Upsample the series into 30 second bins.
+
+        >>> df.asfreq(freq='30S')
+                               s
+        2000-01-01 00:00:00    0.0
+        2000-01-01 00:00:30    NaN
+        2000-01-01 00:01:00    NaN
+        2000-01-01 00:01:30    NaN
+        2000-01-01 00:02:00    2.0
+        2000-01-01 00:02:30    NaN
+        2000-01-01 00:03:00    3.0
+
+        Upsample again, providing a ``fill value``.
+
+        >>> df.asfreq(freq='30S', fill_value=9.0)
+                               s
+        2000-01-01 00:00:00    0.0
+        2000-01-01 00:00:30    9.0
+        2000-01-01 00:01:00    NaN
+        2000-01-01 00:01:30    9.0
+        2000-01-01 00:02:00    2.0
+        2000-01-01 00:02:30    9.0
+        2000-01-01 00:03:00    3.0
+
         Notes
         -----
         To learn more about the frequency strings, please see `this link

pandas/tests/frame/test_timeseries.py

@@ -323,6 +323,26 @@ def test_asfreq_datetimeindex(self):
         ts = df['A'].asfreq('B')
         tm.assertIsInstance(ts.index, DatetimeIndex)
 
+    def test_asfreq_fillvalue(self):
+        # test for fill value during upsampling, related to issue 3715
+
+        # setup
+        rng = pd.date_range('1/1/2016', periods=10, freq='2S')
+        ts = pd.Series(np.arange(len(rng)), index=rng)
+        df = pd.DataFrame({'one': ts})
+
+        # insert pre-existing missing value
+        df.loc['2016-01-01 00:00:08', 'one'] = None
+
+        actual_df = df.asfreq(freq='1S', fill_value=9.0)
+        expected_df = df.asfreq(freq='1S').fillna(9.0)
+        expected_df.loc['2016-01-01 00:00:08', 'one'] = None
+        assert_frame_equal(expected_df, actual_df)
+
+        expected_series = ts.asfreq(freq='1S').fillna(9.0)
+        actual_series = ts.asfreq(freq='1S', fill_value=9.0)
+        assert_series_equal(expected_series, actual_series)
+
     def test_first_last_valid(self):
         N = len(self.frame.index)
         mat = randn(N)

pandas/tseries/tests/test_resample.py

@@ -362,6 +362,8 @@ def test_fillna(self):
             r.fillna(0)
 
     def test_fill_value(self):
+        # test for fill value during resampling, issue 3715
+
         # setup
         rng = pd.date_range('1/1/2016', periods=10, freq='2S')
         ts = pd.Series(np.arange(len(rng)), index=rng)
@@ -378,6 +380,10 @@ def test_fill_value(self):
 
         assert_frame_equal(expected_df, actual_df)
 
+        expected_series = ts.asfreq(freq='1S').fillna(9.0)
+        actual_series = ts.asfreq(freq='1S', fill_value=9.0)
+        assert_series_equal(expected_series, actual_series)
+
     def test_apply_without_aggregation(self):
 
         # both resample and groupby should work w/o aggregation