DOC: Order of groups in groupby and head method

When sort = True is passed to groupby (which is by default) the groups will be in sorted order. If you loop through them they are in sorted order, if you compute the mean, std… they are in sorted order but if you use the method head they are NOT in sorted order.

import pandas as pd

df = pd.DataFrame([[2, 100], [2, 200], [2, 300], [1, 400], [1, 500], [1, 600]], columns = ['A', 'B'])

grouped = df.groupby(df['A'], sort = True)
for name, group in grouped:
    print(group)
print(grouped.mean())
print(grouped.head(1))

Is this expected? I have not found this behaviour documented. I think it is confusing and has caused me a headache because I was combining output of the mean and head methods in the same DataFrame, and since the data was not ordered before those results were getting mixed because of these order issues. I have pandas 0.20.3

[tdpetrou]

There is a big problem with the docstrings here for DataFrameGroupBy.head. They say:

Essentially equivalent to ``.apply(lambda x: x.head(n))``,
except ignores as_index flag.

Dataframegroupby.head keeps the original ordering of the dataframe. It doesn’t even order by the keys. Using .apply(lambda x: x.head(n)) puts the group keys in the index and sorts them.

Edit, I see that @Ifnister already pointed this out. I think it would make a lot more sense to actually do .apply(lambda x: x.head(n)).

[rhshadrach]

Head is a filter; sort is only applied to reducers within groupby. To my knowledge this isn’t documented, but I haven’t checked. I think documentation on this should be added to the Series.groupby and DataFrame.groupby API docs as well as the User Guide.