API ref missing DataFrameGroupBy objects?

pandas, python

Solution

The easiest way to find out what a function does is to consult the docstring:

In [24]: gb.filter?  # help(gb.filter) in python interpreter
Type:       instancemethod
String Form:<bound method DataFrameGroupBy.filter of <pandas.core.groupby.DataFrameGroupBy object at 0x1046ad290>>
File:       /Users/andy/pandas/pandas/core/groupby.py
Definition: g.filter(self, func, dropna=True, *args, **kwargs)
Docstring:
Return a copy of a DataFrame excluding elements from groups that
do not satisfy the boolean criterion specified by func.

Parameters
----------
f : function
    Function to apply to each subframe. Should return True or False.
dropna : Drop groups that do not pass the filter. True by default;
    if False, groups that evaluate False are filled with NaNs.

Notes
-----
Each subframe is endowed the attribute 'name' in case you need to know
which group you are working on.

Example
--------
>>> grouped = df.groupby(lambda x: mapping[x])
>>> grouped.filter(lambda x: x['A'].sum() + x['B'].sum() > 0)

However there's a bug that the "fall through" methods do not show a valid docstring, but rather show only the wrapper for the DataFrame method they call.

For example, `gb.cummin(*args, **kwargs)` is equivalent to `gb.apply(lambda x: x.cummin(*args, **kwargs))`.

In [31]: gb.cummin?
Type:       function
String Form:<function wrapper at 0x1046a9410>
File:       /Users/andy/pandas/pandas/core/groupby.py
Definition: g.cummin(*args, **kwargs)
Docstring:  <no docstring>

In [32]: df.cummin?
Type:       instancemethod
String Form:
<bound method DataFrame.min of    a  b
0  1  2

[1 rows x 2 columns]>
File:       /Users/andy/pandas/pandas/core/generic.py
Definition: df.cummin(self, axis=None, dtype=None, out=None, skipna=True, **kwargs)
Docstring:
Return cumulative min over requested axis.

Parameters
----------
axis : {index (0), columns (1)}
skipna : boolean, default True
    Exclude NA/null values. If an entire row/column is NA, the result
    will be NA

Returns
-------
min : Series

To give an example to explain this particular method and demonstrate the equivalence:

In [41]: df = pd.DataFrame([[2, 4], [1, 5], [2, 2], [1, 3]], columns=['a', 'b'])

In [42]: df
Out[42]:
   a  b
0  2  4
1  1  5
2  2  2
3  1  3

In [43]: gb = df.groupby('a')

In [44]: gb.cummin()
Out[44]:
   a  b
0  2  4
1  1  5
2  2  2
3  1  3

In [45]: gb.apply(lambda x: x.cummin())
Out[45]:
   a  b
0  2  4
1  1  5
2  2  2
3  1  3

Note: I think there is quite a lot of low-hanging fruit here (to make these groupby functions more efficient, as well as add docstrings) and we'll likely see this in 0.14...

Problem

Original source