DEPR: groupby.grouper

[rhshadrach]

• closes #xxxx (Replace xxxx with the GitHub issue number)
• Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• Added type annotations to new arguments/methods/functions.
• Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

Ref: #55738 (comment)

This reverts the deprecation of grouper.reconstructed_codes and grouper.group_keys_seq from #56149 in favor of deprecating all of grouper.

[jbrockmendel]

either :attr: or the word "attribute" somewhere in here?

[jbrockmendel]

just change to _grouper?

[jbrockmendel]

pretty much all of these can just change grouper->_grouper i think, as long as there are a couple that test the deprecation

[jbrockmendel]

if for some reason this doesnt change to _grouper, i have a medium-strong preference for doing as little inside the context as possible, so e.g. gpr = gr.grouper would go inside the context and the assert_numpy... would go in a separate line

[rhshadrach]

Thanks @jbrockmendel - changes made.

[mroeschke]

Merge when ready @jbrockmendel

[jbrockmendel]

thanks @rhshadrach

[jorisvandenbossche]

@rhshadrach one usage of this that I noticed in downstream (seaborn, mwaskom/seaborn#3615, https://github.com/mwaskom/seaborn/blob/a3cb0f1b33551eb25fed1907d0abdd0237fac215/seaborn/categorical.py#L640) is to access the result_index.

Do we have a good alternative for that?
One could do something like pd.Index(grouped.indices.keys()), but that's less robust (converts from python scalars)

I haven't followed the PR where you are refactoring result_index, so don't know if that will change anything (or only how it is calculated), but would we want to expose something similar on the groupby object itself as alternative?

[rhshadrach]

Using result_index is not currently reliable:

df = pd.DataFrame(
    {
        "a": pd.Categorical([1], categories=[1, 2]),
        "b": pd.Categorical([1], categories=[1, 2]),
        "c": 5,
    }
)
gb = df.groupby(["a", "b"])
print(gb.grouper.result_index)
# MultiIndex([(1, 1)], names=['a', 'b'])
print(gb.size())
# a  b
# 1  1    1
#    2    0
# 2  1    0
#    2    0
# dtype: int64

though #55738 will fix this in all cases I know of. An alternative is to perform a reduction and take the index from the result. I recommend size for this as it doesn't require as much computation as other methods.

size = 100_000
df = pd.DataFrame({'a': np.random.randint(0, 100, size), 'b': np.random.randint(0, 100, size), 'c': np.random.random(size)})
%timeit df.groupby(['a', 'b']).size().index
# 3.68 ms ± 6.2 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
%timeit df.groupby(['a', 'b'])._grouper.result_index
# 3.36 ms ± 31.9 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

We do not need to deprecate grouper for #55738, only certain grouper attributes (see #56149)