ENH: add fill_value to resample
State: closed

 - [x] closes #3715 
 - [x] tests added / passed
 - [x] passes ``git diff upstream/master | flake8 --diff``
 - [x] whatsnew entry


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

Comments:
If I'm understanding this correctly, this is equivalent to `.fillna` _prior_ to `.resample`. Another interpretation of the kwarg is that it fills a value _while_ upsampling.

If that's right, is this worth a kwarg? Why not just leave it to the user to `fillna` prior to resampling?

I think that's a fair question.  This is how i understood [3755](https://github.com/pandas-dev/pandas/issues/3715).  An argument for this feature is that you have a fill_value kwarg in reindex, whereas that's equivalent to just running reindex(...).fillna(), right?

That kwarg `reindex` only fills empty values _created on reindex_. (although I also recall that behavior not being consistent):

``` python
In [3]: series = pd.Series(range(4))

In [4]: series[2] = pd.np.nan

In [5]: series
Out[5]:
0    0.0
1    1.0
2    NaN
3    3.0
dtype: float64

In [6]: series.reindex(range(6), fill_value=9)
Out[6]:
0    0.0
1    1.0
2    NaN
3    3.0
4    9.0
5    9.0
dtype: float64
```

i see. got it, thanks.

@nchmura4 As Maximilian said, I also think that a possible `fill_value` keyword should be for filling NaNs created _during_ resampling, not to fill NaNs before resample (as IMO a keyword for that should not be worth it as `df.fillna(..).resample(..)` is just much more explicit that is does that). 
Sorry if we weren't clear about that on the issue!

no problem, thanks for the feedback. Would this example illustrate the desired behavior?

```
rng = pd.date_range('1/1/2016', periods=5, freq='4s')
ts = pd.Series(np.arange(len(rng)), index=rng)
ts2 = pd.Series([1,2,None,4,5], index=rng)
df = pd.DataFrame({'one': ts, 'two': ts2})
df

                    one two
2016-01-01 00:00:00 0   1.0
2016-01-01 00:00:04 1   2.0
2016-01-01 00:00:08 2   NaN
2016-01-01 00:00:12 3   4.0
2016-01-01 00:00:16 4   5.0
```

upsampling with fill_value doesn't fill any NaN's already in the dataframe, but does fill new rows during resampling:
`df.resample("2s", fill_value=9).asfreq()`

```
                    one two
2016-01-01 00:00:00 0.0 1.0
2016-01-01 00:00:02 9.0 9.0
2016-01-01 00:00:04 1.0 2.0
2016-01-01 00:00:06 9.0 9.0
2016-01-01 00:00:08 2.0 NaN
2016-01-01 00:00:10 9.0 9.0
2016-01-01 00:00:12 3.0 4.0
2016-01-01 00:00:14 9.0 9.0
2016-01-01 00:00:16 4.0 5.0
```

@nchmura4 yes, I think that is a correct example.

Question is here maybe: where does this keyword belong? In `resample`, or in `asfreq` ? Or to put it in other words: does such a possible `fill_value` keyword make sense for all methods on a resample, or only for some?

I think this only makes sense on unsampling. I can't think of a use case for downsampling.  So then I think it belongs in asfreq().  I'm working on that.

## [Current coverage](https://codecov.io/gh/pandas-dev/pandas/pull/14591?src=pr) is 85.55% (diff: 100%)
> Merging [#14591](https://codecov.io/gh/pandas-dev/pandas/pull/14591?src=pr) into [master](https://codecov.io/gh/pandas-dev/pandas/branch/master?src=pr) will not change coverage

```diff
@@             master     #14591   diff @@
==========================================
  Files           145        145          
  Lines         51352      51352          
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
  Hits          43932      43932          
  Misses         7420       7420          
  Partials          0          0          
```

> Powered by [Codecov](https://codecov.io?src=pr). Last update [362e78d...45a9e8e](https://codecov.io/gh/pandas-dev/pandas/compare/362e78d944cc72d9da95c7feb0e7d385a63beeae...45a9e8e0917e9b72b241c9235a66e50c03dc69f7?src=pr)
@nchmura4 looks pretty good. 
thanks - I added documentation and tests you suggested
thanks for the feedback
sorry, i think i accidentally messed this pull request up :/ was trying to pull new changes locally and accidentally pushed them into this PR. Can someone help me? sorry!
@nchmura4 If you follow those steps, it should be solved:

```
git fetch upstream
git checkout nchmura-resample-fill-value
git rebase upstream/master
git push -f origin nchmura-resample-fill-value
```
@jorisvandenbossche thank you! i see what i did wrong.  PR all up to date now :)
can you rebase
thanks @nchmura4 !
closed by https://github.com/pandas-dev/pandas/commit/2540d5ac7dd772daa307395be982dc5ce86c3c3f