DOC: update the pandas.core.resample.Resampler.fillna docstring
State: closed

- [x] PR title is "DOC: update the pandas.core.resample.Resampler.fillna docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py pandas.core.resample.Resampler.fillna`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single pandas.core.resample.Resampler.fillna`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```

################################################################################
############## Docstring (pandas.core.resample.Resampler.fillna)  ##############
################################################################################

Fill the new missing values in the resampled data using different
methods.

In statistics, imputation is the process of replacing missing data with
substituted values [1]_. When resampling data, missing values may
appear (e.g., when the resampling frequency is higher than the original
frequency).

The backward fill ('bfill') will replace NaN values that appeared in
the resampled data with the next value in the original sequence. The
forward fill ('ffill'), on the other hand, will replace NaN values
that appeared in the resampled data with the previous value in the
original sequence. Missing values that existed in the orginal data will
not be modified.

Parameters
----------
method : str, method of resampling ('ffill', 'bfill')
    Method to use for filling holes in resampled data
        * ffill: use previous valid observation to fill gap (forward
          fill).
        * bfill: use next valid observation to fill gap (backward
          fill).
limit : integer, optional
    Limit of how many values to fill.

Returns
-------
Series, DataFrame
    An upsampled Series or DataFrame with backward or forwards filled
    NaN values.

Examples
--------

Resampling a Series:

>>> s = pd.Series([1, 2, 3],
...               index=pd.date_range('20180101', periods=3, freq='h'))
>>> s
2018-01-01 00:00:00    1
2018-01-01 01:00:00    2
2018-01-01 02:00:00    3
Freq: H, dtype: int64

>>> s.resample('30min').fillna("bfill")
2018-01-01 00:00:00    1
2018-01-01 00:30:00    2
2018-01-01 01:00:00    2
2018-01-01 01:30:00    3
2018-01-01 02:00:00    3
Freq: 30T, dtype: int64

>>> s.resample('15min').fillna("bfill", limit=2)
2018-01-01 00:00:00    1.0
2018-01-01 00:15:00    NaN
2018-01-01 00:30:00    2.0
2018-01-01 00:45:00    2.0
2018-01-01 01:00:00    2.0
2018-01-01 01:15:00    NaN
2018-01-01 01:30:00    3.0
2018-01-01 01:45:00    3.0
2018-01-01 02:00:00    3.0
Freq: 15T, dtype: float64

>>> s.resample('30min').fillna("ffill")
2018-01-01 00:00:00    1
2018-01-01 00:30:00    1
2018-01-01 01:00:00    2
2018-01-01 01:30:00    2
2018-01-01 02:00:00    3
Freq: 30T, dtype: int64

Resampling a DataFrame that has missing values:

>>> df = pd.DataFrame({'a': [2, np.nan, 6], 'b': [1, 3, 5]},
...                   index=pd.date_range('20180101', periods=3,
...                                       freq='h'))
>>> df
                       a  b
2018-01-01 00:00:00  2.0  1
2018-01-01 01:00:00  NaN  3
2018-01-01 02:00:00  6.0  5

>>> df.resample('30min').fillna("bfill")
                       a  b
2018-01-01 00:00:00  2.0  1
2018-01-01 00:30:00  NaN  3
2018-01-01 01:00:00  NaN  3
2018-01-01 01:30:00  6.0  5
2018-01-01 02:00:00  6.0  5

>>> df.resample('15min').fillna("bfill", limit=2)
                       a    b
2018-01-01 00:00:00  2.0  1.0
2018-01-01 00:15:00  NaN  NaN
2018-01-01 00:30:00  NaN  3.0
2018-01-01 00:45:00  NaN  3.0
2018-01-01 01:00:00  NaN  3.0
2018-01-01 01:15:00  NaN  NaN
2018-01-01 01:30:00  6.0  5.0
2018-01-01 01:45:00  6.0  5.0
2018-01-01 02:00:00  6.0  5.0

>>> df.resample('30min').fillna("ffill")
                      a b
2018-01-01 00:00:00     2.0     1
2018-01-01 00:30:00     2.0     1
2018-01-01 01:00:00     NaN     3
2018-01-01 01:30:00     NaN     3
2018-01-01 02:00:00     6.0     5

See Also
--------
backfill : Backward fill NaN values in the resampled data.
pad : Forward fill NaN values in the resampled data.
bfill : Alias of backfill.
ffill: Alias of pad.
nearest : Fill NaN values in the resampled data
    with nearest neighbor starting from center.
pandas.Series.fillna : Fill NaN values in the Series using the
    specified method, which can be 'bfill' and 'ffill'.
pandas.DataFrame.fillna : Fill NaN values in the DataFrame using the
    specified method, which can be 'bfill' and 'ffill'.

References
----------
.. [1] https://en.wikipedia.org/wiki/Imputation_(statistics)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.core.resample.Resampler.fillna" correct. :)
```

Labels:
name: Docs

Comments:
The nice thing about the DataFrame example for `limit` is that you can show
side-by-side how only newly-introduced
missing values are filled.

On Fri, Mar 16, 2018 at 10:54 AM, Joris Van den Bossche <
notifications@github.com> wrote:

> *@jorisvandenbossche* commented on this pull request.
> ------------------------------
>
> In pandas/core/resample.py
> <https://github.com/pandas-dev/pandas/pull/20379#discussion_r175134071>:
>
> > @@ -624,18 +624,134 @@ def backfill(self, limit=None):
>
>      def fillna(self, method, limit=None):
>          """
> -        Fill missing values
> +        Fill the new missing values in the resampled data using different
> +        methods.
>
> Can you try to get this on a single line?
> ------------------------------
>
> In pandas/core/resample.py
> <https://github.com/pandas-dev/pandas/pull/20379#discussion_r175134635>:
>
> > +        2018-01-01 00:00:00    1
> +        2018-01-01 00:30:00    1
> +        2018-01-01 01:00:00    2
> +        2018-01-01 01:30:00    2
> +        2018-01-01 02:00:00    3
> +        Freq: 30T, dtype: int64
> +
> +        Resampling a DataFrame that has missing values:
> +
> +        >>> df = pd.DataFrame({'a': [2, np.nan, 6], 'b': [1, 3, 5]},
> +        ...                   index=pd.date_range('20180101', periods=3,
> +        ...                                       freq='h'))
> +        >>> df
> +                               a  b
> +        2018-01-01 00:00:00  2.0  1
> +        2018-01-01 01:00:00  NaN  3
>
> I would add such an example with a missing value above for Series as well
> (or instead of this example).
> I think using a Series will make it easier to understand and easier to
> focus on that specific behaviour.
>
> In the end, we can limit the number of examples for DataFrame and
> basically say that for a DataFrame everything works similar as for Series
> column-by-column
>
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/20379#pullrequestreview-104619907>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHIhLxXLjCR0_ZYmYNh9bGaifDMlvCks5te-AzgaJpZM4St5WE>
> .
>

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20379?src=pr&el=h1) Report
> Merging [#20379](https://codecov.io/gh/pandas-dev/pandas/pull/20379?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/8a5830305d2d9a087fbe46bd968218104ffdfc49?src=pr&el=desc) will **decrease** coverage by `0.02%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20379/graphs/tree.svg?height=150&src=pr&token=eZ4WkYLtcO&width=650)](https://codecov.io/gh/pandas-dev/pandas/pull/20379?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20379      +/-   ##
==========================================
- Coverage   91.79%   91.77%   -0.03%     
==========================================
  Files         152      152              
  Lines       49184    49184              
==========================================
- Hits        45150    45138      -12     
- Misses       4034     4046      +12
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.15% <ø> (-0.03%)` | :arrow_down: |
| #single | `41.83% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20379?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/resample.py](https://codecov.io/gh/pandas-dev/pandas/pull/20379/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzYW1wbGUucHk=) | `96.43% <ø> (ø)` | :arrow_up: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/20379/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `65.07% <0%> (-1.74%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20379?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20379?src=pr&el=footer). Last update [8a58303...39e69ba](https://codecov.io/gh/pandas-dev/pandas/pull/20379?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Made the requested changes, also adding a little more info between examples.
Moved the See Also up. Thanks @prcastro .