DOC: add basic documentation to some of the GroupBy properties and methods

[dwiel]

I added some simple documentation to the GroupBy and Grouper classes

[rockg]

@dwiel I think you should add this to the API documentation as well.

[jtratner]

missing the second }

[dwiel]

doh, looks like the same thing happened on the GroupBy.indicies docstring as well. Just pushed a fix for both of them

[dwiel]

@rockg, is there documentation somewhere about how to do that? I've looked around a little bit, but I'm not finding anything.

[jtratner]

look at api.rst

[jorisvandenbossche]

I don't think the GroupBy object is available in the pandas namespace. I think you will have to add something like .. currentmodule:: pandas.core.groupby

[cancan101]

This might be a related issue: #4500

[dwiel]

yeah, #4500 deffinitely looks related, though the bulk of the conversation is more about automatic missing documentation finding rather than the original topic of lacking GroupBy documentation.

I left GroupBy.ngroups undocumented because it always gives the same result as len, but the code paths are different, and it wasn't clear to me why.

[jorisvandenbossche]

Super that you wan't to work on this! Docs on these groupby things are really a gap in the documentation at the moment IMHO..

I also have been thinking about it some time ago, and I think there are some issues to pay attention to:

• Not all methods are implemented as methods from the Groupby class, also some in DataFrameGroupby and SeriesGroupby (eg aggregate) or NDFrameGroupby. This can make it complex to the user.
• These methods appear as methods of the GroupBy (or other as DataFrameGrouBy etc) object. I think it has to be clearly stated that such an object is the result of a df.groupby() call and that these methods are applicable on that. Maybe some lines can be added to api.rst to explain that.
• Another thing that makes it complicated, is that actually also other Series/DataFrame methods can be applied on a groupby method. Eg. the 'missing' doc on the nunique function as mentioned in Docs for lurking groupby methods #4500 is actually not really missing, as this is just a Series method (so adding these all to the docs is not really possible, but a better explanation of this in the narrative groupby docs can of course help a lot).

But it is certainly a good start!

Something else (but that is a broader discussion), the mentioning of NDFrame is also somewhat problematic I think, as nowhere in the docs it is really explained what this is (as far as I know?). But this is something that maybe needs some seperate discussion, as it also appears in other parts of the docs, certainly now more functions are made 'generic' and not seperately implemented for Series and DataFrame.

[jreback]

@dwiel #4887 is the issue which esentially whitelisted methods that can be used on groupby
(what @jorisvandenbossche mentioned above). These are created as wrapper methods so they don't explicity live in groupby (except the cythonized versions of some of these), others are delegated to the underlying object. This is why its 'magical' why some things just work!

[jorisvandenbossche]

@dwiel Do you have time to finish this?
My main comment on this is to add some explanation in api.rst that the GroupBy object is the result of a df.groupby() for clarity, and you should also squash your commits.

If you have some more time, the GroupBy.aggregate and GroupBy.transform methods you added to api.rst don't have a docstring yet. But that could also be something for a another PR.

[dwiel]

I've added an explanation to api.rst and squashed the commits. I'm not entirely sure how to get the comments into the api.rst since the doc string is there, its just loaded with the Appender decorator. The docstring shows up in ipython help for example. If you would rather I remove them from the api.rst for now since it isn't picking them up, that is fine.

I haven't made many contributions to Open Source projects yet, but your previous comment @jorisvandenbossche was the first appreciative comment I've received, and it was very welcome. Thanks!

[jorisvandenbossche]

You can make DataFrame.groupby link to the rendered docstring of groupby by using :func:pandas.DataFrame.groupby``. However, this will not work in the bold text environment ** ... **.

[jorisvandenbossche]

And you are thanked for your contribution!

I added one more comment.
The problem with aggregate and transform docstrings not appearing in the html builds, while you see them in ipython help, is because it are methods of DataFrameGroupBy instead of the generic GroupBy (like I already commented earlier as a difficulty to document these functions).

[jreback]

@jorisvandenbossche can you review?

[jorisvandenbossche]

@jreback I think my most important comments are adressed, and the others can wait for later PRs (I will turn them in some issues).
The only thing I am not certain about is that now GroupBy.aggregate/transform is listed in api.rst, but if you click on it to go the docstring page, it is empty (as it is actually DataFrame/SeriesGroupBy.aggregate that has a docstring in the code).

[jreback]

ok.....will merge this then

[jtratner]

@dwiel thanks for this! (and what a bummer that you didn't get positive
feedback on other contributions!)

[dwiel]

The feedback is appreciated, I was getting worried that I wasn't actually helping.