From 5bffa504cc887987fc4b49c50cd2e7fe1ead135b Mon Sep 17 00:00:00 2001 From: AJ Dyka Date: Sat, 10 Mar 2018 13:15:47 +0800 Subject: [PATCH 1/9] docstring groupby.apply initial commit --- pandas/core/groupby.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py index 285c5786b532b..706943ba9114a 100644 --- a/pandas/core/groupby.py +++ b/pandas/core/groupby.py @@ -99,9 +99,11 @@ func : function A callable that takes a {input} as its first argument, and 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`` + 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 ------- @@ -136,7 +138,7 @@ its argument and returns a dataframe. ``apply`` combines the result for each group together into a new dataframe: - >>> g.apply(lambda x: x / x.sum()) + >>> g[['B','C']].apply(lambda x: x / x.sum()) B C 0 0.333333 0.4 1 0.666667 0.6 @@ -146,7 +148,7 @@ its argument and returns a series. ``apply`` combines the result for each group together into a new dataframe: - >>> g.apply(lambda x: x.max() - x.min()) + >>> g[['B','C']].apply(lambda x: x.max() - x.min()) B C A a 1 2 From 7c51bb5776e6261c6879545bd7b27e4b393b1ee2 Mon Sep 17 00:00:00 2001 From: AJ Dyka Date: Sat, 10 Mar 2018 13:45:47 +0800 Subject: [PATCH 2/9] DOC: update the GroupBy.apply docstring --- pandas/core/groupby.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py index 706943ba9114a..3b993eaa1a0a1 100644 --- a/pandas/core/groupby.py +++ b/pandas/core/groupby.py @@ -120,12 +120,12 @@ Examples -------- {examples} - See also -------- pipe : Apply function to the full GroupBy object instead of to each group. - aggregate, transform + aggregate : + transform : """, dataframe_examples=""" >>> df = pd.DataFrame({'A': 'a a b'.split(), 'B': [1,2,3], 'C': [4,6, 5]}) From 304e943818889445f3570e26ce99f57983dae1a4 Mon Sep 17 00:00:00 2001 From: AJ Dyka Date: Sat, 10 Mar 2018 13:57:44 +0800 Subject: [PATCH 3/9] DOC: update the GroupBy.apply docstring --- pandas/core/groupby.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py index 3b993eaa1a0a1..89395d2db43cf 100644 --- a/pandas/core/groupby.py +++ b/pandas/core/groupby.py @@ -124,8 +124,7 @@ -------- pipe : Apply function to the full GroupBy object instead of to each group. - aggregate : - transform : + aggregate, transform """, dataframe_examples=""" >>> df = pd.DataFrame({'A': 'a a b'.split(), 'B': [1,2,3], 'C': [4,6, 5]}) @@ -138,7 +137,7 @@ 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()) + >>> g[['B','C']].apply(lambda x: x / x.sum()) B C 0 0.333333 0.4 1 0.666667 0.6 @@ -148,7 +147,7 @@ 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()) + >>> g[['B','C']].apply(lambda x: x.max() - x.min()) B C A a 1 2 From a35eef138bbd05bdd2b08d02f49af4be942bd0a7 Mon Sep 17 00:00:00 2001 From: Simon Dambe Date: Sat, 10 Mar 2018 16:04:03 +0800 Subject: [PATCH 4/9] DOC: update the GroupBy.apply see also to include description --- pandas/core/groupby.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py index 89395d2db43cf..786bf09029c69 100644 --- a/pandas/core/groupby.py +++ b/pandas/core/groupby.py @@ -124,7 +124,8 @@ -------- pipe : Apply function to the full GroupBy object instead of to each group. - aggregate, transform + aggregate : Apply aggregate function to the GroupBy object. + transform : Apply function column-by-column to the GroupBy object. """, dataframe_examples=""" >>> df = pd.DataFrame({'A': 'a a b'.split(), 'B': [1,2,3], 'C': [4,6, 5]}) From 4ec814a95d4e4889f48bb30f44aabece7e9349bd Mon Sep 17 00:00:00 2001 From: AJ Dyka Date: Sat, 10 Mar 2018 16:11:50 +0800 Subject: [PATCH 5/9] DOC: update the GroupBy.apply docstring --- pandas/core/groupby.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py index 786bf09029c69..622a8e298b9e8 100644 --- a/pandas/core/groupby.py +++ b/pandas/core/groupby.py @@ -124,7 +124,7 @@ -------- pipe : Apply function to the full GroupBy object instead of to each group. - aggregate : Apply aggregate function to the GroupBy object. + aggregate : Apply aggregate function to the GroupBy object. transform : Apply function column-by-column to the GroupBy object. """, dataframe_examples=""" From d1faa3d1fb503cfeddb11d69f38e5ac11dd9e0e5 Mon Sep 17 00:00:00 2001 From: AJ Dyka Date: Mon, 12 Mar 2018 07:54:08 +0800 Subject: [PATCH 6/9] DOC: update the GroupBy.apply docstring --- pandas/core/groupby.py | 76 ++++++++++++++++++++---------------------- 1 file changed, 37 insertions(+), 39 deletions(-) diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py index 622a8e298b9e8..674616befa130 100644 --- a/pandas/core/groupby.py +++ b/pandas/core/groupby.py @@ -80,19 +80,19 @@ _apply_docs = dict( 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, a series or a scalar. ``apply`` will + The function passed to `apply` must take a {input} 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 + 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. 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``. + than using `apply` for their specific purposes, so try to use them + before reaching for `apply`. Parameters ---------- @@ -100,10 +100,8 @@ A callable that takes a {input} 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``. + *args : Optional positional and keyword arguments to pass to `func`. + **kwargs : Optional positional and keyword arguments to pass to `func`. Returns ------- @@ -111,7 +109,7 @@ 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 side-effects, as they will take effect twice for the first @@ -131,11 +129,11 @@ >>> 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: + 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 + 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()) @@ -144,8 +142,8 @@ 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 + 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()) @@ -154,8 +152,8 @@ 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 + 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: @@ -169,11 +167,11 @@ >>> ser = pd.Series([0, 1, 2], index='a a b'.split()) >>> g = ser.groupby(ser.index) - From ``ser`` above we can see that ``g`` has two groups, ``a``, ``b``. - Calling ``apply`` in various ways, we can get different grouping results: + From `ser` above we can see that `g` has two groups, `a`, `b`. + Calling `apply` in various ways, we can get different grouping results: - Example 1: The function passed to ``apply`` takes a series as - its argument and returns a series. ``apply`` combines the result for + Example 1: The function passed to `apply` takes a series as + its argument and returns a series. `apply` combines the result for each group together into a new series: >>> g.apply(lambda x: x*2 if x.name == 'b' else x/2) @@ -182,8 +180,8 @@ 2 4.0 dtype: float64 - Example 2: The function passed to ``apply`` takes a series as - its argument and returns a scalar. ``apply`` combines the result for + Example 2: The function passed to `apply` takes a series as + its argument and returns a scalar. `apply` combines the result for each group together into a series, including setting the index as appropriate: @@ -194,12 +192,12 @@ """) _pipe_template = """\ -Apply a function ``func`` with arguments to this %(klass)s object and return +Apply a function `func` with arguments to this %(klass)s object and return the function's result. %(versionadded)s -Use ``.pipe`` when you want to improve readability by chaining together +Use `.pipe` when you want to improve readability by chaining together functions that expect Series, DataFrames, GroupBy or Resampler objects. Instead of writing @@ -218,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 + string indicating the keyword of `callable` that expects the %(klass)s object. args : iterable, optional - positional arguments passed into ``func``. + positional arguments passed into `func`. kwargs : dict, optional - a dictionary of keyword arguments passed into ``func``. + a dictionary of keyword arguments passed into `func`. Returns ------- -object : the return type of ``func``. +object : the return type of `func`. Notes ----- @@ -381,7 +379,7 @@ class Grouper(object): sort : boolean, default to False whether to sort the resulting labels - additional kwargs to control time-like groupers (when ``freq`` is passed) + additional kwargs to control time-like groupers (when `freq` is passed) closed : closed end of interval; 'left' or 'right' label : interval boundary to use for labeling; 'left' or 'right' @@ -396,7 +394,7 @@ class Grouper(object): Examples -------- - Syntactic sugar for ``df.groupby('A')`` + Syntactic sugar for `df.groupby('A')` >>> df.groupby(Grouper(key='A')) @@ -1627,7 +1625,7 @@ def nth(self, n, dropna=None): 2 3.0 2 5.0 - Specifying ``dropna`` allows count ignoring NaN + Specifying `dropna` allows count ignoring NaN >>> g.nth(0, dropna='any') B @@ -1643,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. >>> df.groupby('A', as_index=False).nth(1) A B @@ -2069,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))`, except ignores as_index flag. Examples @@ -2096,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))`, except ignores as_index flag. Examples From 9ab975a801ebc140af3045d07560cca0ecac27cd Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 15 Mar 2018 14:33:50 -0500 Subject: [PATCH 7/9] Updated [ci skip] [ci skip] --- pandas/core/groupby.py | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py index 674616befa130..e7a164479ed8f 100644 --- a/pandas/core/groupby.py +++ b/pandas/core/groupby.py @@ -96,12 +96,14 @@ Parameters ---------- - func : function + func : callable A callable that takes a {input} as its first argument, and returns a dataframe, a series or a scalar. In addition the callable may take positional and keyword arguments. - *args : Optional positional and keyword arguments to pass to `func`. - **kwargs : Optional positional and keyword arguments to pass to `func`. + *args + Additional positional arguments are passed through to `func`. + **kwargs + Additional keyword arguments are passed through to `func`. Returns ------- @@ -118,12 +120,15 @@ Examples -------- {examples} - See also + 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. + Series.apply : Apply a function to a Series. + DataFrame.apply : Apply a function to each row or column of a + DataFrame. """, dataframe_examples=""" >>> df = pd.DataFrame({'A': 'a a b'.split(), 'B': [1,2,3], 'C': [4,6, 5]}) @@ -216,7 +221,7 @@ ---------- 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 + a ``(callable, data_keyword)`` tuple where `data_keyword` is a string indicating the keyword of `callable` that expects the %(klass)s object. args : iterable, optional @@ -394,7 +399,7 @@ class Grouper(object): Examples -------- - Syntactic sugar for `df.groupby('A')` + Syntactic sugar for ``df.groupby('A')`` >>> df.groupby(Grouper(key='A')) @@ -1641,7 +1646,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. >>> df.groupby('A', as_index=False).nth(1) A B @@ -2067,7 +2072,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))``, except ignores as_index flag. Examples @@ -2094,7 +2099,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))``, except ignores as_index flag. Examples From e88d7f1fb33ba94ef480a38ac9676ccbe7b7087b Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 15 Mar 2018 14:39:14 -0500 Subject: [PATCH 8/9] Updates [ci skip] * Undo some single backticking * PEP8 on examples * Reword [ci skip] --- pandas/core/groupby.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/pandas/core/groupby.py b/pandas/core/groupby.py index e7a164479ed8f..6f9e9ddd30230 100644 --- a/pandas/core/groupby.py +++ b/pandas/core/groupby.py @@ -83,16 +83,16 @@ 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, a series or a scalar. `apply` will + 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 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`. + 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`. Parameters ---------- @@ -111,9 +111,9 @@ 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. @@ -131,17 +131,19 @@ DataFrame. """, dataframe_examples=""" - >>> df = pd.DataFrame({'A': 'a a b'.split(), 'B': [1,2,3], 'C': [4,6, 5]}) + >>> 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`. + Notice that ``g`` has two groups, ``a``, and ``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()) + >>> g[['B', 'C']].apply(lambda x: x / x.sum()) B C 0 0.333333 0.4 1 0.666667 0.6 @@ -151,7 +153,7 @@ 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()) + >>> g[['B', 'C']].apply(lambda x: x.max() - x.min()) B C A a 1 2 From cf3b3e9f23b99aac5fcd0dfca1fe93bd1e62a72b Mon Sep 17 00:00:00 2001 From: Will Ayd Date: Sat, 21 Jul 2018 09:58:55 -0700 Subject: [PATCH 9/9] Updated documentation --- pandas/core/groupby/groupby.py | 101 +++++++++++++++++---------------- pandas/core/groupby/grouper.py | 2 +- 2 files changed, 54 insertions(+), 49 deletions(-) diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index cb045b08f3629..4b0143b3e1ced 100644 --- a/pandas/core/groupby/groupby.py +++ b/pandas/core/groupby/groupby.py @@ -55,28 +55,28 @@ class providing the base-class of operations. _apply_docs = dict( 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, a series or a 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 - 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``. + 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`. Parameters ---------- - func : function + func : callable A callable that takes a {input} as its first argument, and returns a dataframe, a series or a scalar. In addition the - callable may take positional and keyword arguments + 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 ------- @@ -84,9 +84,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. @@ -98,38 +98,43 @@ class providing the base-class of operations. -------- pipe : Apply function to the full GroupBy object instead of to each group. - aggregate, transform + aggregate : Apply aggregate function to the GroupBy object. + transform : Apply function column-by-column to the GroupBy object. + Series.apply : Apply a function to a Series. + DataFrame.apply : Apply a function to each row or column of a DataFrame. """, dataframe_examples=""" - >>> df = pd.DataFrame({'A': 'a a b'.split(), 'B': [1,2,3], 'C': [4,6, 5]}) + >>> 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: + Notice that ``g`` has two groups, ``a`` and ``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: + 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.apply(lambda x: x / x.sum()) + >>> 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: + 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.apply(lambda x: x.max() - x.min()) + >>> 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 + 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()) @@ -139,15 +144,15 @@ class providing the base-class of operations. dtype: int64 """, series_examples=""" - >>> ser = pd.Series([0, 1, 2], index='a a b'.split()) - >>> g = ser.groupby(ser.index) + >>> s = pd.Series([0, 1, 2], index='a a b'.split()) + >>> g = s.groupby(s.index) - From ``ser`` above we can see that ``g`` has two groups, ``a``, ``b``. - Calling ``apply`` in various ways, we can get different grouping results: + From ``s`` above we can see that ``g`` has two groups, ``a`` and ``b``. + Calling `apply` in various ways, we can get different grouping results: - Example 1: The function passed to ``apply`` takes a series as - its argument and returns a series. ``apply`` combines the result for - each group together into a new series: + Example 1: The function passed to `apply` takes a Series as + its argument and returns a Series. `apply` combines the result for + each group together into a new Series: >>> g.apply(lambda x: x*2 if x.name == 'b' else x/2) 0 0.0 @@ -155,9 +160,9 @@ class providing the base-class of operations. 2 4.0 dtype: float64 - Example 2: The function passed to ``apply`` takes a series as - its argument and returns a scalar. ``apply`` combines the result for - each group together into a series, including setting the index as + Example 2: The function passed to `apply` takes a Series 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.max() - x.min()) @@ -167,12 +172,12 @@ class providing the base-class of operations. """) _pipe_template = """\ -Apply a function ``func`` with arguments to this %(klass)s object and return +Apply a function `func` with arguments to this %(klass)s object and return the function's result. %(versionadded)s -Use ``.pipe`` when you want to improve readability by chaining together +Use `.pipe` when you want to improve readability by chaining together functions that expect Series, DataFrames, GroupBy or Resampler objects. Instead of writing @@ -191,17 +196,17 @@ class providing the base-class of operations. ---------- 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 + string indicating the keyword of `callable` that expects the %(klass)s object. args : iterable, optional - positional arguments passed into ``func``. + positional arguments passed into `func`. kwargs : dict, optional - a dictionary of keyword arguments passed into ``func``. + a dictionary of keyword arguments passed into `func`. Returns ------- -object : the return type of ``func``. +object : the return type of `func`. Notes ----- @@ -1442,7 +1447,7 @@ def nth(self, n, dropna=None): 2 3.0 2 5.0 - Specifying ``dropna`` allows count ignoring NaN + Specifying `dropna` allows count ignoring ``NaN`` >>> g.nth(0, dropna='any') B @@ -1458,7 +1463,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. >>> df.groupby('A', as_index=False).nth(1) A B diff --git a/pandas/core/groupby/grouper.py b/pandas/core/groupby/grouper.py index a1511b726c705..3070fa0e63c88 100644 --- a/pandas/core/groupby/grouper.py +++ b/pandas/core/groupby/grouper.py @@ -59,7 +59,7 @@ class Grouper(object): sort : boolean, default to False whether to sort the resulting labels - additional kwargs to control time-like groupers (when ``freq`` is passed) + additional kwargs to control time-like groupers (when `freq` is passed) closed : closed end of interval; 'left' or 'right' label : interval boundary to use for labeling; 'left' or 'right'