DOC: update the GroupBy.apply docstring #20098

ajdyka · 2018-03-10T08:15:27Z

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant
closes Docs: broken groupby.GroupBy.apply example #19337

Please include the output of the validation script below between the "```" ticks:

################################################################################
################ Docstring (pandas.core.groupby.GroupBy.apply)  ################
################################################################################

Apply function ``func``  group-wise and combine the results together.

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

While ``apply`` is a very flexible method, its downside is that
using it can be quite a bit slower than using more specific methods.
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
----------
func : function
    A callable that takes a dataframe as its first argument, and
    returns a dataframe, a series or a scalar. In addition the
    callable may take positional and keyword arguments.
args : tuple
    Optional positional and keyword arguments to pass to ``func``.
kwargs : dict
    Optional positional and keyword arguments to pass to ``func``.

Returns
-------
applied : Series or DataFrame

Notes
-----
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
side-effects, as they will take effect twice for the first
group.

Examples
--------

>>> df = pd.DataFrame({'A': 'a a b'.split(), 'B': [1,2,3], 'C': [4,6, 5]})
>>> g = df.groupby('A')

From ``df`` above we can see that ``g`` has two groups, ``a``, ``b``.
Calling ``apply`` in various ways, we can get different grouping results:

Example 1: below the function passed to ``apply`` takes a dataframe as
its argument and returns a dataframe. ``apply`` combines the result for
each group together into a new dataframe:

>>> g[['B','C']].apply(lambda x: x / x.sum())
          B    C
0  0.333333  0.4
1  0.666667  0.6
2  1.000000  1.0

Example 2: The function passed to ``apply`` takes a dataframe as
its argument and returns a series.  ``apply`` combines the result for
each group together into a new dataframe:

>>> g[['B','C']].apply(lambda x: x.max() - x.min())
   B  C
A
a  1  2
b  0  0

Example 3: The function passed to ``apply`` takes a dataframe as
its argument and returns a scalar. ``apply`` combines the result for
each group together into a series, including setting the index as
appropriate:

>>> g.apply(lambda x: x.C.max() - x.B.min())
A
a    5
b    2
dtype: int64

See also
--------
pipe : Apply function to the full GroupBy object instead of to each
    group.
aggregate : Apply aggregate function to the GroupBy object.
transform : Apply function column-by-column to the GroupBy object.

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.core.groupby.GroupBy.apply" correct. :)

DOC: update the GroupBy.apply see also to include description

jorisvandenbossche

Thanks for the docstring!

Can you change the occurences of ``func`` to `func`? (we use single backtick quotes for parameter names)

jorisvandenbossche · 2018-03-10T09:25:10Z

pandas/core/groupby.py

-    args, kwargs : tuple and dict
-        Optional positional and keyword arguments to pass to ``func``
+        callable may take positional and keyword arguments.
+    args : tuple


Can you make this *args ? (and you can leave out the 'tuple')

jorisvandenbossche · 2018-03-10T09:26:09Z

pandas/core/groupby.py

+        callable may take positional and keyword arguments.
+    args : tuple
+        Optional positional and keyword arguments to pass to ``func``.
+    kwargs : dict


Here the same **kwargs (and without dict)

jorisvandenbossche · 2018-03-10T09:27:02Z

pandas/core/groupby.py

-        Optional positional and keyword arguments to pass to ``func``
+        callable may take positional and keyword arguments.
+    args : tuple
+        Optional positional and keyword arguments to pass to ``func``.


This are only the positional ones, and below the keyword ones.

I think it would also be a good idea to add an example of this in the Examples section

codecov · 2018-03-10T12:58:01Z

Codecov Report

Merging #20098 into master will decrease coverage by 0.26%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20098      +/-   ##
==========================================
- Coverage   91.99%   91.73%   -0.27%     
==========================================
  Files         167      150      -17     
  Lines       50578    49168    -1410     
==========================================
- Hits        46530    45102    -1428     
- Misses       4048     4066      +18

Flag	Coverage Δ
#multiple	`90.11% <ø> (-0.29%)`	⬇️
#single	`41.86% <ø> (-0.31%)`	⬇️

Impacted Files	Coverage Δ
pandas/core/groupby.py	`92.14% <ø> (ø)`
pandas/plotting/_compat.py	`62% <0%> (-28.91%)`	⬇️
pandas/io/s3.py	`72.72% <0%> (-13.64%)`	⬇️
pandas/core/arrays/base.py	`74.35% <0%> (-13.5%)`	⬇️
pandas/util/_doctools.py	`0% <0%> (-12.88%)`	⬇️
pandas/io/formats/terminal.py	`16.43% <0%> (-4.55%)`	⬇️
pandas/io/formats/printing.py	`89.38% <0%> (-3.71%)`	⬇️
pandas/io/html.py	`86.6% <0%> (-2.57%)`	⬇️
pandas/core/dtypes/missing.py	`91.07% <0%> (-2.5%)`	⬇️
pandas/io/formats/format.py	`96.26% <0%> (-1.99%)`	⬇️
... and 98 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 322dbf4...cf3b3e9. Read the comment docs.

jreback · 2018-03-10T13:13:12Z

pandas/core/groupby.py

@@ -118,12 +120,12 @@
    Examples
    --------
    {examples}
-
    See also
    --------


can you reference Series/DataFrame.apply as well

Could you add these to the See Also?

TomAugspurger · 2018-03-12T13:09:58Z

pandas/core/groupby.py

@@ -216,17 +216,17 @@
 ----------
 func : callable or tuple of (callable, string)
    Function to apply to this %(klass)s object or, alternatively,
-    a ``(callable, data_keyword)`` tuple where ``data_keyword`` is a
-    string indicating the keyword of ``callable`` that expects the
+    a `(callable, data_keyword)` tuple where `data_keyword` is a


I think this tuple should be double-backticks, since it's a code snippet.

TomAugspurger · 2018-03-12T13:10:32Z

pandas/core/groupby.py

@@ -394,7 +394,7 @@ class Grouper(object):
    Examples
    --------

-    Syntactic sugar for ``df.groupby('A')``
+    Syntactic sugar for `df.groupby('A')`


double backticks

TomAugspurger · 2018-03-12T13:10:52Z

pandas/core/groupby.py

@@ -1641,7 +1641,7 @@ def nth(self, n, dropna=None):
        1 NaN
        2 NaN

-        Specifying ``as_index=False`` in ``groupby`` keeps the original index.
+        Specifying `as_index=False` in `groupby` keeps the original index.


double backtick for as_index=False

TomAugspurger · 2018-03-12T13:10:58Z

pandas/core/groupby.py

@@ -2067,7 +2067,7 @@ def head(self, n=5):
        """
        Returns first n rows of each group.

-        Essentially equivalent to ``.apply(lambda x: x.head(n))``,
+        Essentially equivalent to `.apply(lambda x: x.head(n))`,


double backticks

TomAugspurger · 2018-03-12T13:11:03Z

pandas/core/groupby.py

@@ -2094,7 +2094,7 @@ def tail(self, n=5):
        """
        Returns last n rows of each group

-        Essentially equivalent to ``.apply(lambda x: x.tail(n))``,
+        Essentially equivalent to `.apply(lambda x: x.tail(n))`,


double backtics

TomAugspurger · 2018-03-12T13:11:40Z

pandas/core/groupby.py

@@ -118,12 +120,12 @@
    Examples
    --------
    {examples}
-
    See also
    --------


Could you add these to the See Also?

TomAugspurger · 2018-03-12T13:13:59Z

pandas/core/groupby.py

-    args, kwargs : tuple and dict
-        Optional positional and keyword arguments to pass to ``func``
+        callable may take positional and keyword arguments.
+    *args : Optional positional and keyword arguments to pass to `func`.


This should be formatted as

*args Additional positional arguments are passed through to `func`. **kwargs Additional keyword arguments are passed through to `func`.

[ci skip]

* Undo some single backticking * PEP8 on examples * Reword [ci skip]

jreback · 2018-04-14T13:48:45Z

can you rebase this

…_apply

WillAyd · 2018-07-21T17:00:43Z

Thanks @ajdyka !

ajdyka and others added 6 commits March 10, 2018 13:15

docstring groupby.apply initial commit

5bffa50

DOC: update the GroupBy.apply docstring

7c51bb5

DOC: update the GroupBy.apply docstring

304e943

DOC: update the GroupBy.apply see also to include description

a35eef1

Merge pull request #1 from sd1/docstring_groupby_apply

f9a253f

DOC: update the GroupBy.apply see also to include description

DOC: update the GroupBy.apply docstring

4ec814a

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

jreback added Docs Groupby labels Mar 10, 2018

jreback requested changes Mar 10, 2018

View reviewed changes

DOC: update the GroupBy.apply docstring

d1faa3d

TomAugspurger reviewed Mar 12, 2018

View reviewed changes

TomAugspurger added 2 commits March 15, 2018 14:33

Updated [ci skip]

9ab975a

[ci skip]

Updates [ci skip]

e88d7f1

* Undo some single backticking * PEP8 on examples * Reword [ci skip]

TomAugspurger approved these changes Mar 15, 2018

View reviewed changes

TomAugspurger added this to the 0.23.0 milestone Mar 15, 2018

jreback removed this from the 0.23.0 milestone Apr 14, 2018

WillAyd added 2 commits July 21, 2018 09:48

Merge remote-tracking branch 'upstream/master' into docstring_groupby…

ac44f39

…_apply

Updated documentation

cf3b3e9

WillAyd merged commit 8c4ec65 into pandas-dev:master Jul 21, 2018

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

DOC: update the GroupBy.apply docstring (pandas-dev#20098)

946de44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the GroupBy.apply docstring #20098

DOC: update the GroupBy.apply docstring #20098

ajdyka commented Mar 10, 2018

jorisvandenbossche left a comment

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

codecov bot commented Mar 10, 2018 •

edited

Loading

jreback Mar 10, 2018

TomAugspurger Mar 12, 2018

TomAugspurger Mar 12, 2018

TomAugspurger Mar 12, 2018

TomAugspurger Mar 12, 2018

TomAugspurger Mar 12, 2018

TomAugspurger Mar 12, 2018

TomAugspurger Mar 12, 2018

TomAugspurger Mar 12, 2018

jreback commented Apr 14, 2018

WillAyd commented Jul 21, 2018

DOC: update the GroupBy.apply docstring #20098

DOC: update the GroupBy.apply docstring #20098

Conversation

ajdyka commented Mar 10, 2018

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Mar 10, 2018 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback commented Apr 14, 2018

WillAyd commented Jul 21, 2018

codecov bot commented Mar 10, 2018 •

edited

Loading