ENH: Add numeric_only to resampler methods
State: closed

- [ ] closes #46442
- [x] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [x] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [x] Added an entry in the latest `doc/source/whatsnew/vX.X.X.rst` file if fixing a bug or adding a new feature.

After examining the reported issue #46442, I found the issue exists in all the following docs.
https://pandas.pydata.org/docs/reference/api/pandas.core.resample.Resampler.sum.html
https://pandas.pydata.org/docs/reference/api/pandas.core.resample.Resampler.prod.html
https://pandas.pydata.org/docs/reference/api/pandas.core.resample.Resampler.min.html
https://pandas.pydata.org/docs/reference/api/pandas.core.resample.Resampler.max.html
https://pandas.pydata.org/docs/reference/api/pandas.core.resample.Resampler.first.html
https://pandas.pydata.org/docs/reference/api/pandas.core.resample.Resampler.last.html

The problem seems to be caused by the fact that the docstrings of `sum`, `prod`, `min`, `max`, `first`, `last` methods
in the `Resampler` class borrow the `_groupby_agg_method_template` template from `GroupBy` class. I think one possible fix is
creating a `_resample_agg_method_template` and using this template to create docstrings for the methods mentioned above.

I am a first-time contributor. Appreciate any suggestions and ideas for fixing this issue.


Labels:
name: Enhancement
name: Resample
description: resample method
name: Nuisance Columns
description: Identifying/Dropping nuisance columns in reductions, groupby.add, DataFrame.apply

Comments:
can you show the rendered doc-string and point to the current one for comparison
Thanks @jreback. The re-rendered doc-string of `pandas.core.resample.Resampler.first` looks as follows.
<dl class="py method">
<dt class="sig sig-object py" id="pandas.core.resample.Resampler.first">
<span class="sig-prename descclassname"><span class="pre">Resampler.</span></span><span class="sig-name descname"><span class="pre">first</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">_method</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'first'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">min_count</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/pandas-dev/pandas/blob/main/pandas/core\resample.py#L1045-L1048"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pandas.core.resample.Resampler.first" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute first of group values.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>min_count</strong><span class="classifier">: int, default 0</span></dt><dd><p>The required number of valid values to perform the operation. If fewer
than <code class="docutils literal notranslate"><span class="pre">min_count</span></code> non-NA values are present the result will be NA.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt>Series or DataFrame</dt><dd><p>Computed first of values within each group.</p>
</dd>
</dl>
</dd>
</dl>
</dd></dl>

===========================================================================
For comparison, the current doc-string of `pandas.core.resample.Resampler.first` looks as follows.
https://pandas.pydata.org/docs/reference/api/pandas.core.resample.Resampler.first.html
<dl class="py method">
<dt class="sig sig-object py" id="pandas.core.resample.Resampler.first">
<span class="sig-prename descclassname"><span class="pre">Resampler.</span></span><span class="sig-name descname"><span class="pre">first</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">_method</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'first'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">min_count</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/pandas-dev/pandas/blob/v1.4.2/pandas/core/resample.py#L1026-L1028"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pandas.core.resample.Resampler.first" title="Permalink to this definition">¶</a></dt>
<dd><p>Compute first of group values.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>numeric_only</strong><span class="classifier">: bool, default False</span></dt><dd><p>Include only float, int, boolean columns. If None, will attempt to use
everything, then use only numeric data.</p>
</dd>
<dt><strong>min_count</strong><span class="classifier">: int, default -1</span></dt><dd><p>The required number of valid values to perform the operation. If fewer
than <code class="docutils literal notranslate"><span class="pre">min_count</span></code> non-NA values are present the result will be NA.</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt>Series or DataFrame</dt><dd><p>Computed first of values within each group.</p>
</dd>
</dl>
</dd>
</dl>
</dd></dl>


cc @rhshadrach 
Thanks for the PR @lorentzbao; this is indeed the path forward mentioned in the linked issue. However, I did not realize that we'd want to deprecate the dropping of nuisance columns in resample similar to what we're doing with with Series/DataFrame/groupby. See #46560 for details (especially the two linked issues there). For this, it seems necessary to add `numeric_only` to these methods, so that when the deprecation is enforced users have an easy way to recover the 1.x behavior (namely, by specifying `numeric_only=True`).

Do you think you could add `numeric_only` to the methods here instead of removing the argument from the documentation?
> Thanks for the PR @lorentzbao; this is indeed the path forward mentioned in the linked issue. However, I did not realize that we'd want to deprecate the dropping of nuisance columns in resample similar to what we're doing with with Series/DataFrame/groupby. See #46560 for details (especially the two linked issues there). For this, it seems necessary to add `numeric_only` to these methods, so that when the deprecation is enforced users have an easy way to recover the 1.x behavior (namely, by specifying `numeric_only=True`).
> 
> 
> 
> Do you think you could add `numeric_only` to the methods here instead of removing the argument from the documentation?

Really appreciate your comments @rhshadrach. Let me go through the links you shared. I think I could have a try adding `numeric_only` to these methods.
I should have also mentioned - see #46708 for similar examples where this argument was added to frame methods.
> I should have also mentioned - see #46708 for similar examples where this argument was added to frame methods.


Thanks @rhshadrach. I have added `numeric_only` to resample `sum`, `prod`, `min`, `max`, `first`, `last` methods, and created a test for this implementation. I'm not sure if I'm on the right track. Appreciate any comments or suggestions.


ping @jreback 
thanks @lorentzbao