DEPR: pd.TimeGrouper

[tdpetrou]

Problem description

The TimeGrouper docstrings are missing the key and level parameters. TimeGrouper is also absent from the API reference page in the docs. I think it would also be nice to have a section in the docs on how it differs than resample.

[TomAugspurger]

It is documented under Grouper: http://pandas.pydata.org/pandas-docs/stable/generated/pandas.Grouper.html I thought we always recommended it rather than TimeGrouper, but grepping through the docs shows that not to be the case.

[TomAugspurger]

http://pandas.pydata.org/pandas-docs/stable/groupby.html#grouping-with-a-grouper-specification is the section in the prose docs.

[tdpetrou]

Does TimeGrouper have any advantage over Grouper other than its more explicit name? If not, shouldn't it be deprecated?

[jreback]

TimeGrouper was the long time way to do resampling from a groupby framework. This has been integrated for quite some time into the exposed Grouper interface. We could deprecate TimeGrouper. it is one of those non-documented, not-directly-exposed things.

[tdpetrou]

I think it doesn't help that the cookbook part of the docs (http://pandas.pydata.org/pandas-docs/stable/cookbook.html?highlight=timegrouper#resampling) directly links to three TimeGrouper use cases, two on stackoverflow. From experience and searching stackoverflow, it appears that some of the most viewed questions involving grouping by dates use TimeGrouper. Stackoverflow tends to perpetuate bad pandas practice, most noticeably with the continued daily questions that use .ix.

[jreback]

@tdpetrou yep certianly the cookbook could be updated to directly use Grouper. So if you want to fix up docs that would be good, independetly could deprecate this (meaning 2 PR's).

[jreback]

Stackoverflow tends to perpetuate bad pandas practice, most noticeably with the continued daily questions that use .ix.

SO is love-hate. Feel free to add links on questions where appropriate!

[manikbhandari]

certianly the cookbook could be updated to directly use Grouper

I would like to take this up.

[jreback]

closed by #16794

[jreback]

re-opening, this can track the deprecation.