apply(self, func, *args, **kwargs)

The function passed to apply must take a series 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 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 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 .

Notes

Functions that mutate the passed object can produce unexpected behavior or errors and are not supported. See gotchas.udf-mutation for more details.

Parameters

func : callable

A callable that takes a series 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 .

Returns

applied : Series or DataFrame

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

See Also

DataFrame.apply

Apply a function to each row or column of a DataFrame.

Series.apply

Apply a function to a Series.

aggregate

Apply aggregate function to the GroupBy object.

pipe

Apply function to the full GroupBy object instead of to each group.

transform

Apply function column-by-column to the GroupBy object.

Examples

This example is valid syntax, but we were not able to check execution

>>> s = pd.Series([0, 1, 2], index='a a b'.split())
... g = s.groupby(s.index)

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.

The resulting dtype will reflect the return value of the passed func .

This example is valid syntax, but we were not able to check execution

>>> g.apply(lambda x: x*2 if x.name == 'a' else x/2)
a    0.0
a    2.0
b    1.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 appropriate:

This example is valid syntax, but we were not able to check execution

>>> g.apply(lambda x: x.max() - x.min())
a    1
b    0
dtype: int64

See :

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: /pandas/core/groupby/generic.py#238
type: <class 'function'>
Commit: