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

Checklist for the pandas documentation sprint:

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py pandas.core.resample.Resampler.backfill`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python make.py --single pandas.core.resample.Resampler.backfill`
   (after the modification suggested [here](https://github.com/pandas-dev/pandas/pull/20083#issuecomment-371928588))
- [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.backfill)  #############
################################################################################

Backward fill the new missing values in the resampled data.

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 will replace NaN values that appeared in
the resampled data with the next value in the original sequence.
Missing values that existed in the orginal data will not be modified.

Parameters
----------
limit : integer, optional
    Limit of how many values to fill.

Returns
-------
Series, DataFrame
    An upsampled Series or DataFrame with backward filled NaN values.

See Also
--------
bfill : Alias of backfill.
fillna : Fill NaN values using the specified method, which can be
    'backfill'.
nearest : Fill NaN values with nearest neighbor starting from center.
pad : Forward fill NaN values.
pandas.Series.fillna : Fill NaN values in the Series using the
    specified method, which can be 'backfill'.
pandas.DataFrame.fillna : Fill NaN values in the DataFrame using the
    specified method, which can be 'backfill'.

References
----------
.. [1] https://en.wikipedia.org/wiki/Imputation_(statistics)

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').backfill()
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').backfill(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

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').backfill()
                       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').backfill(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

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.core.resample.Resampler.backfill" correct. :)
```

Labels:
name: Docs
name: Missing-data
description: np.nan, pd.NaT, pd.NA, dropna, isnull, interpolate
name: Resample
description: resample method

Comments:
When I run `python make.py --single pandas.core.resample.Resampler.backfill`, I get the following error message:
```
Traceback (most recent call last):
  File "make.py", line 138, in _process_single_doc
    obj = getattr(obj, name)
AttributeError: module 'pandas.core' has no attribute 'resample'
```

I tested with other modules inside pandas.core, e.g., `python make.py --single pandas.core.groupby`, and the HTML file is generated.
> When I run python make.py --single pandas.core.resample.Resampler.backfill, I get the following error message

cc @datapythonista, @jorisvandenbossche that's because  `pd.core.resample` isn't imported in `pandas/__init__.py`.  We use importlib to import pandas, but we should also import objects that are documented but not imported by default (Styler?, others?)

@gcbeltramini  this should fix it for you for testing, but I think we'll handle all these in a separate PR.

```diff
diff --git a/doc/make.py b/doc/make.py
index 4967f3045..f1b63cf13 100755
--- a/doc/make.py
+++ b/doc/make.py
@@ -349,6 +349,7 @@ def main():
     os.environ['PYTHONPATH'] = args.python_path
     sys.path.append(args.python_path)
     globals()['pandas'] = importlib.import_module('pandas')
+    importlib.import_module('pandas.core.resample')
 
     builder = DocBuilder(args.num_jobs, not args.no_api, args.single,
                          args.verbosity)
```
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20083?src=pr&el=h1) Report
> Merging [#20083](https://codecov.io/gh/pandas-dev/pandas/pull/20083?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/7c14e4f14aff216be558bf5d4d2d00b4838c2360?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #20083      +/-   ##
==========================================
+ Coverage   91.72%   91.72%   +<.01%     
==========================================
  Files         150      150              
  Lines       49122    49152      +30     
==========================================
+ Hits        45057    45086      +29     
- Misses       4065     4066       +1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <ø> (ø)` | :arrow_up: |
| #single | `41.84% <ø> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20083?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/resample.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzYW1wbGUucHk=) | `96.43% <ø> (ø)` | :arrow_up: |
| [pandas/core/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYmFzZS5weQ==) | `96.78% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.64% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.85% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS5weQ==) | `92.14% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.66% <0%> (-0.01%)` | :arrow_down: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.84% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `91.03% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.06% <0%> (ø)` | :arrow_up: |
| [pandas/core/strings.py](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3RyaW5ncy5weQ==) | `98.32% <0%> (ø)` | :arrow_up: |
| ... and [3 more](https://codecov.io/gh/pandas-dev/pandas/pull/20083/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20083?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/20083?src=pr&el=footer). Last update [7c14e4f...4e616f7](https://codecov.io/gh/pandas-dev/pandas/pull/20083?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Thanks @TomAugspurger! I edited the file `doc/make.py` according to your suggestion, and I could see the HTML file.
Thanks all. @gcbeltramini if you could check http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.core.resample.Resampler.backfill.html when https://travis-ci.org/pandas-dev/pandas/jobs/352298397 finishes to see if the links render correctly, we'd appreciate it.
note @TomAugspurger the docs are not actually built because we are not changing any rst files. I just forced a doc-build (though this one is not included as was after). we *could* just disable this check (in build_docs) for say this week
Ah good to know, thanks.

On Mon, Mar 12, 2018 at 7:26 AM, Jeff Reback <notifications@github.com>
wrote:

> note @TomAugspurger <https://github.com/tomaugspurger> the docs are not
> actually built because we are not changing any rst files. I just forced a
> doc-build (though this one is not included as was after). we *could* just
> disable this check (in build_docs) for say this week
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/20083#issuecomment-372292569>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHIvogx3NgVUsObLKfHVFzfNyVSnu0ks5tdmmKgaJpZM4SktPj>
> .
>

I changed this recently, docs are now always built (exactly for this reason, we always want to build the docs)
Ah, no, I changed it in a PR that is not yet merged .. :)
ahh ok, yeah, go ahead and merge that then :>