DOC: DataFrameGroupBy.filter documentation is misleading

[adamreeve]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.core.groupby.DataFrameGroupBy.filter.html and https://pandas.pydata.org/docs/reference/api/pandas.core.groupby.SeriesGroupBy.filter.html

Documentation problem

Both DataFrameGroupBy.filter and SeriesGroupBy.filter state that they "filter elements from groups".

This is not true, these methods filter whole groups. If you attempt to filter individual elements within a group by returning a series of boolean you get an error:

df = pd.DataFrame({'A' : ['foo', 'bar', 'foo', 'bar',
                          'foo', 'bar'],
                   'B' : [1, 2, 3, 4, 5, 6],
                  'C' : [2.0, 5., 8., 1., 2., 9.]})
df.groupby("A").filter(lambda x: x['B'] > 1).sum()

TypeError: filter function returned a Series, but expected a scalar bool

Suggested fix for documentation

Suggested documentation:

Filter groups that don’t satisfy a criterion.

Groups are filtered if they do not satisfy the boolean criterion specified by func.

[adamreeve]

After looking at this again, I think the documentation does make sense but I was misinterpreting it. This does filter out rows/elements rather than whole groups, but it filters rows based on a criterion that applies to the whole group rather than to rows within the group.