Skip to content

DOC: Fix documentation for DataFrame.groupby.transform #40506

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 25, 2021
Merged

DOC: Fix documentation for DataFrame.groupby.transform #40506

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
31ac01b
DOC: Fix documentation for DataFrame.groupby.transform
vladu Mar 18, 2021
48d5011
DOC: One more little fix to groupby.apply function doc, for consistency.
vladu Mar 18, 2021
291e6a9
Merge branch 'master' into vladu-doc-fixes-1
vladu Mar 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions pandas/core/groupby/groupby.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,19 +119,19 @@ class providing the base-class of operations.

_apply_docs = {
"template": """
Apply function `func` group-wise and combine the results together.
Apply function ``func`` group-wise and combine the results together.

The function passed to `apply` must take a {input} as its first
argument and return a DataFrame, Series or scalar. `apply` will
The function passed to ``apply`` must take a {input} as its first
argument and return a DataFrame, Series or scalar. ``apply`` will
then take care of combining the results back together into a single
dataframe or series. `apply` is therefore a highly flexible
dataframe or series. ``apply`` is therefore a highly flexible
grouping method.

While `apply` is a very flexible method, its downside is that
While ``apply`` is a very flexible method, its downside is that
using it can be quite a bit slower than using more specific methods
like `agg` or `transform`. Pandas offers a wide range of method that will
be much faster than using `apply` for their specific purposes, so try to
use them before reaching for `apply`.
like ``agg`` or ``transform``. Pandas offers a wide range of method that will
be much faster than using ``apply`` for their specific purposes, so try to
use them before reaching for ``apply``.

Parameters
----------
Expand All @@ -140,7 +140,7 @@ class providing the base-class of operations.
returns a dataframe, a series or a scalar. In addition the
callable may take positional and keyword arguments.
args, kwargs : tuple and dict
Optional positional and keyword arguments to pass to `func`.
Optional positional and keyword arguments to pass to ``func``.

Returns
-------
Expand All @@ -157,9 +157,9 @@ class providing the base-class of operations.

Notes
-----
In the current implementation `apply` calls `func` twice on the
In the current implementation ``apply`` calls ``func`` twice on the
first group to decide whether it can take a fast or slow code
path. This can lead to unexpected behavior if `func` has
path. This can lead to unexpected behavior if ``func`` has
side-effects, as they will take effect twice for the first
group.

Expand Down Expand Up @@ -350,12 +350,12 @@ class providing the base-class of operations.

See Also
--------
%(klass)s.groupby.apply : Apply function func group-wise
and combine the results together.
%(klass)s.groupby.apply : Apply function ``func`` group-wise and combine
the results together.
%(klass)s.groupby.aggregate : Aggregate using one or more
operations over the specified axis.
%(klass)s.transform : Transforms the Series on each group
based on the given function.
%(klass)s.transform : Call ``func`` on self producing a %(klass)s with
Copy link
Member

@rhshadrach rhshadrach Mar 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would think that this should be about DataFrame.groupby.transform, rather than DataFrame.transform.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this is the doc string for DataFrame.groupby.transform. So in the "See Also" section, it makes sense to me that it references the ungrouped DataFrame.transform.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh, whoops, thanks! In that case, may want to specify that transform operates on the columns rather than self.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, let me be more specific. This is a template doc-string that is reused for both [DataFrame|Series].groupby.transform. Hence the "klass" templating. In master right now, the "see also" section specifically talks about Series, which doesn't make sense for DataFrame. So my PR here is to fix that. The text I inserted, is taken verbatim from the template for [DataFrame|Series].tansform. I think that's the reason it's being a little vague, and avoiding verbiage that would imply dimensionality.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks - make sense. It does seem to me desirable to improve this (namely, it seems to me to be misleading in the DataFrame case), but okay for this PR.

transformed values.

Notes
-----
Expand Down