DEPR: Add note to groupby docstring about deprecation of axis=1

[rhshadrach]

Ref: #51395 (comment)

The docstring of both DataFrame.groupby and Series.groupby should be updated to indicate the deprecation. Marking as a regression to make clear this goes into 2.1.1.

[rsm-23]

take

[blaiseli]

I saw a deprecation warning when running some unittest code of mine containing a groupby with axis=1, so I tried to run it with the only slight modification suggested (i.e. transposing my DataFrame and running groupby on it without axis, and now my code fails.

    # This works but issues a deprecation warning:
    #zero_counts_in_a_sample = (counts.groupby(
    #    level=[
    #        i for i in range(len(counts.columns.names))
    #        if i != counts.columns.names.index("count")],
    #    axis=1).sum() == 0.0).any(axis=1)
    # This fails
    zero_counts_in_a_sample = (counts.T.groupby(
        level=[
            i for i in range(len(counts.columns.names))
            if i != counts.columns.names.index("count")]).sum() == 0.0).any(axis=1)

The error is as follows:

Traceback (most recent call last):
  File "/home/bli/src/libsnp/./tests/test_libsnp.py", line 65, in test_concat_data
    counts = concat_counts_from_dicts(self.counts_dict)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bli/src/libsnp/src/libsnp/libsnp.py", line 116, in concat_counts_from_dicts
    counts = counts.loc[~zero_counts_in_a_sample]
             ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bli/src/libsnp/.venv/lib/python3.11/site-packages/pandas/core/indexing.py", line 1153, in __getitem__
    return self._getitem_axis(maybe_callable, axis=axis)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bli/src/libsnp/.venv/lib/python3.11/site-packages/pandas/core/indexing.py", line 1375, in _getitem_axis
    return self._getbool_axis(key, axis=axis)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bli/src/libsnp/.venv/lib/python3.11/site-packages/pandas/core/indexing.py", line 1171, in _getbool_axis
    key = check_bool_indexer(labels, key)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/bli/src/libsnp/.venv/lib/python3.11/site-packages/pandas/core/indexing.py", line 2575, in check_bool_indexer
    raise IndexingError(
pandas.errors.IndexingError: Unalignable boolean Series provided as indexer (index of the boolean Series and of the indexed object do not match).

So I believe the deprecation explanation should provide more details regarding what to do.

[blaiseli]

The comment here helped me solve my issue:
#51203 (comment)

I suggest the docstring as well as the deprecation warning mention the back-transposition necessary to obtain functionally equivalent code:

DataFrame.groupby with axis=1 is deprecated. Do frame.T.groupby(...).<insert your operation here>(...).T without axis instead.