Group By: split-apply-combine

By “group by” we are referring to a process involving one or more of the followingsteps:

• Splitting the data into groups based on some criteria.
• Applying a function to each group independently.
• Combining the results into a data structure.

Out of these, the split step is the most straightforward. In fact, in manysituations we may wish to split the data set into groups and do something withthose groups. In the apply step, we might wish to do one of thefollowing:

• Aggregation: compute a summary statistic (or statistics) for eachgroup. Some examples:

• Compute group sums or means.
• Compute group sizes / counts.

• Transformation: perform some group-specific computations and return alike-indexed object. Some examples:

• Standardize data (zscore) within a group.
• Filling NAs within groups with a value derived from each group.

• Filtration: discard some groups, according to a group-wise computationthat evaluates True or False. Some examples:

• Discard data that belongs to groups with only a few members.
• Filter out data based on the group sum or mean.

• Some combination of the above: GroupBy will examine the results of the applystep and try to return a sensibly combined result if it doesn’t fit intoeither of the above two categories.

Since the set of object instance methods on pandas data structures are generallyrich and expressive, we often simply want to invoke, say, a DataFrame functionon each group. The name GroupBy should be quite familiar to those who have useda SQL-based tool (or itertools), in which you can write code like:

SELECT Column1, Column2, mean(Column3), sum(Column4)
FROM SomeTable
GROUP BY Column1, Column2

We aim to make operations like this natural and easy to express usingpandas. We’ll address each area of GroupBy functionality then provide somenon-trivial examples / use cases.

See the cookbook for some advanced strategies.

Splitting an object into groups

pandas objects can be split on any of their axes. The abstract definition ofgrouping is to provide a mapping of labels to group names. To create a GroupByobject (more on what the GroupBy object is later), you may do the following:

In [1]: df = pd.DataFrame([('bird', 'Falconiformes', 389.0),
   ...:                    ('bird', 'Psittaciformes', 24.0),
   ...:                    ('mammal', 'Carnivora', 80.2),
   ...:                    ('mammal', 'Primates', np.nan),
   ...:                    ('mammal', 'Carnivora', 58)],
   ...:                   index=['falcon', 'parrot', 'lion', 'monkey', 'leopard'],
   ...:                   columns=('class', 'order', 'max_speed'))
   ...: 
 
In [2]: df
Out[2]: 
          class           order  max_speed
falcon     bird   Falconiformes      389.0
parrot     bird  Psittaciformes       24.0
lion     mammal       Carnivora       80.2
monkey   mammal        Primates        NaN
leopard  mammal       Carnivora       58.0
 
# default is axis=0
In [3]: grouped = df.groupby('class')
 
In [4]: grouped = df.groupby('order', axis='columns')
 
In [5]: grouped = df.groupby(['class', 'order'])

The mapping can be specified many different ways:

• A Python function, to be called on each of the axis labels.
• A list or NumPy array of the same length as the selected axis.
• A dict or Series, providing a label -> group name mapping.
• For DataFrame objects, a string indicating a column to be used to group.Of course df.groupby('A') is just syntactic sugar fordf.groupby(df['A']), but it makes life simpler.
• For DataFrame objects, a string indicating an index level to be used togroup.
• A list of any of the above things.

Collectively we refer to the grouping objects as the keys. For example,consider the following DataFrame:

Note

A string passed to groupby may refer to either a column or an index level.If a string matches both a column name and an index level name, aValueError will be raised.

In [6]: df = pd.DataFrame({'A': ['foo', 'bar', 'foo', 'bar',
   ...:                          'foo', 'bar', 'foo', 'foo'],
   ...:                    'B': ['one', 'one', 'two', 'three',
   ...:                          'two', 'two', 'one', 'three'],
   ...:                    'C': np.random.randn(8),
   ...:                    'D': np.random.randn(8)})
   ...: 
 
In [7]: df
Out[7]: 
     A      B         C         D
0  foo    one  0.469112 -0.861849
1  bar    one -0.282863 -2.104569
2  foo    two -1.509059 -0.494929
3  bar  three -1.135632  1.071804
4  foo    two  1.212112  0.721555
5  bar    two -0.173215 -0.706771
6  foo    one  0.119209 -1.039575
7  foo  three -1.044236  0.271860

On a DataFrame, we obtain a GroupBy object by calling groupby().We could naturally group by either the A or B columns, or both:

In [8]: grouped = df.groupby('A')
 
In [9]: grouped = df.groupby(['A', 'B'])

New in version 0.24.

If we also have a MultiIndex on columns A and B, we can group by allbut the specified columns

In [10]: df2 = df.set_index(['A', 'B'])
 
In [11]: grouped = df2.groupby(level=df2.index.names.difference(['B']))
 
In [12]: grouped.sum()
Out[12]: 
            C         D
A                      
bar -1.591710 -1.739537
foo -0.752861 -1.402938

These will split the DataFrame on its index (rows). We could also split by thecolumns:

In [13]: def get_letter_type(letter):
   ....:     if letter.lower() in 'aeiou':
   ....:         return 'vowel'
   ....:     else:
   ....:         return 'consonant'
   ....: 
 
In [14]: grouped = df.groupby(get_letter_type, axis=1)

pandas Index objects support duplicate values. If anon-unique index is used as the group key in a groupby operation, all valuesfor the same index value will be considered to be in one group and thus theoutput of aggregation functions will only contain unique index values:

In [15]: lst = [1, 2, 3, 1, 2, 3]
 
In [16]: s = pd.Series([1, 2, 3, 10, 20, 30], lst)
 
In [17]: grouped = s.groupby(level=0)
 
In [18]: grouped.first()
Out[18]: 
1    1
2    2
3    3
dtype: int64
 
In [19]: grouped.last()
Out[19]: 
1    10
2    20
3    30
dtype: int64
 
In [20]: grouped.sum()
Out[20]: 
1    11
2    22
3    33
dtype: int64

Note that no splitting occurs until it’s needed. Creating the GroupBy objectonly verifies that you’ve passed a valid mapping.

Note

Many kinds of complicated data manipulations can be expressed in terms ofGroupBy operations (though can’t be guaranteed to be the mostefficient). You can get quite creative with the label mapping functions.

GroupBy sorting

By default the group keys are sorted during the groupby operation. You may however pass sort=False for potential speedups:

In [21]: df2 = pd.DataFrame({'X': ['B', 'B', 'A', 'A'], 'Y': [1, 2, 3, 4]})
 
In [22]: df2.groupby(['X']).sum()
Out[22]: 
   Y
X   
A  7
B  3
 
In [23]: df2.groupby(['X'], sort=False).sum()
Out[23]: 
   Y
X   
B  3
A  7

Note that groupby will preserve the order in which observations are sorted within each group.For example, the groups created by groupby() below are in the order they appeared in the original DataFrame:

In [24]: df3 = pd.DataFrame({'X': ['A', 'B', 'A', 'B'], 'Y': [1, 4, 3, 2]})
 
In [25]: df3.groupby(['X']).get_group('A')
Out[25]: 
   X  Y
0  A  1
2  A  3
 
In [26]: df3.groupby(['X']).get_group('B')
Out[26]: 
   X  Y
1  B  4
3  B  2

GroupBy object attributes

The groups attribute is a dict whose keys are the computed unique groupsand corresponding values being the axis labels belonging to each group. In theabove example we have:

In [27]: df.groupby('A').groups
Out[27]: 
{'bar': Int64Index([1, 3, 5], dtype='int64'),
 'foo': Int64Index([0, 2, 4, 6, 7], dtype='int64')}
 
In [28]: df.groupby(get_letter_type, axis=1).groups
Out[28]: 
{'consonant': Index(['B', 'C', 'D'], dtype='object'),
 'vowel': Index(['A'], dtype='object')}

Calling the standard Python len function on the GroupBy object just returnsthe length of the groups dict, so it is largely just a convenience:

In [29]: grouped = df.groupby(['A', 'B'])
 
In [30]: grouped.groups
Out[30]: 
{('bar', 'one'): Int64Index([1], dtype='int64'),
 ('bar', 'three'): Int64Index([3], dtype='int64'),
 ('bar', 'two'): Int64Index([5], dtype='int64'),
 ('foo', 'one'): Int64Index([0, 6], dtype='int64'),
 ('foo', 'three'): Int64Index([7], dtype='int64'),
 ('foo', 'two'): Int64Index([2, 4], dtype='int64')}
 
In [31]: len(grouped)
Out[31]: 6

GroupBy will tab complete column names (and other attributes):

In [32]: df
Out[32]: 
               height      weight  gender
2000-01-01  42.849980  157.500553    male
2000-01-02  49.607315  177.340407    male
2000-01-03  56.293531  171.524640    male
2000-01-04  48.421077  144.251986  female
2000-01-05  46.556882  152.526206    male
2000-01-06  68.448851  168.272968  female
2000-01-07  70.757698  136.431469    male
2000-01-08  58.909500  176.499753  female
2000-01-09  76.435631  174.094104  female
2000-01-10  45.306120  177.540920    male
 
In [33]: gb = df.groupby('gender')

In [34]: gb.<TAB>  # noqa: E225, E999
gb.agg        gb.boxplot    gb.cummin     gb.describe   gb.filter     gb.get_group  gb.height     gb.last       gb.median     gb.ngroups    gb.plot       gb.rank       gb.std        gb.transform
gb.aggregate  gb.count      gb.cumprod    gb.dtype      gb.first      gb.groups     gb.hist       gb.max        gb.min        gb.nth        gb.prod       gb.resample   gb.sum        gb.var
gb.apply      gb.cummax     gb.cumsum     gb.fillna     gb.gender     gb.head       gb.indices    gb.mean       gb.name       gb.ohlc       gb.quantile   gb.size       gb.tail       gb.weight

GroupBy with MultiIndex

With hierarchically-indexed data, it’s quitenatural to group by one of the levels of the hierarchy.

Let’s create a Series with a two-level MultiIndex.

In [35]: arrays = [['bar', 'bar', 'baz', 'baz', 'foo', 'foo', 'qux', 'qux'],
   ....:           ['one', 'two', 'one', 'two', 'one', 'two', 'one', 'two']]
   ....: 
 
In [36]: index = pd.MultiIndex.from_arrays(arrays, names=['first', 'second'])
 
In [37]: s = pd.Series(np.random.randn(8), index=index)
 
In [38]: s
Out[38]: 
first  second
bar    one      -0.919854
       two      -0.042379
baz    one       1.247642
       two      -0.009920
foo    one       0.290213
       two       0.495767
qux    one       0.362949
       two       1.548106
dtype: float64

We can then group by one of the levels in s.

In [39]: grouped = s.groupby(level=0)
 
In [40]: grouped.sum()
Out[40]: 
first
bar   -0.962232
baz    1.237723
foo    0.785980
qux    1.911055
dtype: float64

If the MultiIndex has names specified, these can be passed instead of the levelnumber:

In [41]: s.groupby(level='second').sum()
Out[41]: 
second
one    0.980950
two    1.991575
dtype: float64

The aggregation functions such as sum will take the level parameterdirectly. Additionally, the resulting index will be named according to thechosen level:

In [42]: s.sum(level='second')
Out[42]: 
second
one    0.980950
two    1.991575
dtype: float64

Grouping with multiple levels is supported.

In [43]: s
Out[43]: 
first  second  third
bar    doo     one     -1.131345
               two     -0.089329
baz    bee     one      0.337863
               two     -0.945867
foo    bop     one     -0.932132
               two      1.956030
qux    bop     one      0.017587
               two     -0.016692
dtype: float64
 
In [44]: s.groupby(level=['first', 'second']).sum()
Out[44]: 
first  second
bar    doo      -1.220674
baz    bee      -0.608004
foo    bop       1.023898
qux    bop       0.000895
dtype: float64

New in version 0.20.

Index level names may be supplied as keys.

In [45]: s.groupby(['first', 'second']).sum()
Out[45]: 
first  second
bar    doo      -1.220674
baz    bee      -0.608004
foo    bop       1.023898
qux    bop       0.000895
dtype: float64

More on the sum function and aggregation later.

Grouping DataFrame with Index levels and columns

A DataFrame may be grouped by a combination of columns and index levels byspecifying the column names as strings and the index levels as pd.Grouperobjects.

In [46]: arrays = [['bar', 'bar', 'baz', 'baz', 'foo', 'foo', 'qux', 'qux'],
   ....:           ['one', 'two', 'one', 'two', 'one', 'two', 'one', 'two']]
   ....: 
 
In [47]: index = pd.MultiIndex.from_arrays(arrays, names=['first', 'second'])
 
In [48]: df = pd.DataFrame({'A': [1, 1, 1, 1, 2, 2, 3, 3],
   ....:                    'B': np.arange(8)},
   ....:                   index=index)
   ....: 
 
In [49]: df
Out[49]: 
              A  B
first second      
bar   one     1  0
      two     1  1
baz   one     1  2
      two     1  3
foo   one     2  4
      two     2  5
qux   one     3  6
      two     3  7

The following example groups df by the second index level andthe A column.

In [50]: df.groupby([pd.Grouper(level=1), 'A']).sum()
Out[50]: 
          B
second A   
one    1  2
       2  4
       3  6
two    1  4
       2  5
       3  7

Index levels may also be specified by name.

In [51]: df.groupby([pd.Grouper(level='second'), 'A']).sum()
Out[51]: 
          B
second A   
one    1  2
       2  4
       3  6
two    1  4
       2  5
       3  7

New in version 0.20.

Index level names may be specified as keys directly to groupby.

In [52]: df.groupby(['second', 'A']).sum()
Out[52]: 
          B
second A   
one    1  2
       2  4
       3  6
two    1  4
       2  5
       3  7

DataFrame column selection in GroupBy

Once you have created the GroupBy object from a DataFrame, you might want to dosomething different for each of the columns. Thus, using [] similar togetting a column from a DataFrame, you can do:

In [53]: grouped = df.groupby(['A'])
 
In [54]: grouped_C = grouped['C']
 
In [55]: grouped_D = grouped['D']

This is mainly syntactic sugar for the alternative and much more verbose:

In [56]: df['C'].groupby(df['A'])
Out[56]: <pandas.core.groupby.generic.SeriesGroupBy object at 0x7f45270d68d0>

Additionally this method avoids recomputing the internal grouping informationderived from the passed key.

Iterating through groups

With the GroupBy object in hand, iterating through the grouped data is verynatural and functions similarly to itertools.groupby():

In [57]: grouped = df.groupby('A')
 
In [58]: for name, group in grouped:
   ....:     print(name)
   ....:     print(group)
   ....: 
bar
     A      B         C         D
1  bar    one  0.254161  1.511763
3  bar  three  0.215897 -0.990582
5  bar    two -0.077118  1.211526
foo
     A      B         C         D
0  foo    one -0.575247  1.346061
2  foo    two -1.143704  1.627081
4  foo    two  1.193555 -0.441652
6  foo    one -0.408530  0.268520
7  foo  three -0.862495  0.024580

In the case of grouping by multiple keys, the group name will be a tuple:

In [59]: for name, group in df.groupby(['A', 'B']):
   ....:     print(name)
   ....:     print(group)
   ....: 
('bar', 'one')
     A    B         C         D
1  bar  one  0.254161  1.511763
('bar', 'three')
     A      B         C         D
3  bar  three  0.215897 -0.990582
('bar', 'two')
     A    B         C         D
5  bar  two -0.077118  1.211526
('foo', 'one')
     A    B         C         D
0  foo  one -0.575247  1.346061
6  foo  one -0.408530  0.268520
('foo', 'three')
     A      B         C        D
7  foo  three -0.862495  0.02458
('foo', 'two')
     A    B         C         D
2  foo  two -1.143704  1.627081
4  foo  two  1.193555 -0.441652

See Iterating through groups.

Selecting a group

A single group can be selected usingget_group():

In [60]: grouped.get_group('bar')
Out[60]: 
     A      B         C         D
1  bar    one  0.254161  1.511763
3  bar  three  0.215897 -0.990582
5  bar    two -0.077118  1.211526

Or for an object grouped on multiple columns:

In [61]: df.groupby(['A', 'B']).get_group(('bar', 'one'))
Out[61]: 
     A    B         C         D
1  bar  one  0.254161  1.511763

Aggregation

Once the GroupBy object has been created, several methods are available toperform a computation on the grouped data. These operations are similar to theaggregating API, window functions API,and resample API.

An obvious one is aggregation via theaggregate() or equivalentlyagg() method:

In [62]: grouped = df.groupby('A')
 
In [63]: grouped.aggregate(np.sum)
Out[63]: 
            C         D
A                      
bar  0.392940  1.732707
foo -1.796421  2.824590
 
In [64]: grouped = df.groupby(['A', 'B'])
 
In [65]: grouped.aggregate(np.sum)
Out[65]: 
                  C         D
A   B                        
bar one    0.254161  1.511763
    three  0.215897 -0.990582
    two   -0.077118  1.211526
foo one   -0.983776  1.614581
    three -0.862495  0.024580
    two    0.049851  1.185429

As you can see, the result of the aggregation will have the group names as thenew index along the grouped axis. In the case of multiple keys, the result is aMultiIndex by default, though this can bechanged by using the as_index option:

In [66]: grouped = df.groupby(['A', 'B'], as_index=False)
 
In [67]: grouped.aggregate(np.sum)
Out[67]: 
     A      B         C         D
0  bar    one  0.254161  1.511763
1  bar  three  0.215897 -0.990582
2  bar    two -0.077118  1.211526
3  foo    one -0.983776  1.614581
4  foo  three -0.862495  0.024580
5  foo    two  0.049851  1.185429
 
In [68]: df.groupby('A', as_index=False).sum()
Out[68]: 
     A         C         D
0  bar  0.392940  1.732707
1  foo -1.796421  2.824590

Note that you could use the reset_index DataFrame function to achieve thesame result as the column names are stored in the resulting MultiIndex:

In [69]: df.groupby(['A', 'B']).sum().reset_index()
Out[69]: 
     A      B         C         D
0  bar    one  0.254161  1.511763
1  bar  three  0.215897 -0.990582
2  bar    two -0.077118  1.211526
3  foo    one -0.983776  1.614581
4  foo  three -0.862495  0.024580
5  foo    two  0.049851  1.185429

Another simple aggregation example is to compute the size of each group.This is included in GroupBy as the size method. It returns a Series whoseindex are the group names and whose values are the sizes of each group.

In [70]: grouped.size()
Out[70]: 
A    B    
bar  one      1
     three    1
     two      1
foo  one      2
     three    1
     two      2
dtype: int64

In [71]: grouped.describe()
Out[71]: 
      C                                                                           D                                                                      
  count      mean       std       min       25%       50%       75%       max count      mean       std       min       25%       50%       75%       max
0   1.0  0.254161       NaN  0.254161  0.254161  0.254161  0.254161  0.254161   1.0  1.511763       NaN  1.511763  1.511763  1.511763  1.511763  1.511763
1   1.0  0.215897       NaN  0.215897  0.215897  0.215897  0.215897  0.215897   1.0 -0.990582       NaN -0.990582 -0.990582 -0.990582 -0.990582 -0.990582
2   1.0 -0.077118       NaN -0.077118 -0.077118 -0.077118 -0.077118 -0.077118   1.0  1.211526       NaN  1.211526  1.211526  1.211526  1.211526  1.211526
3   2.0 -0.491888  0.117887 -0.575247 -0.533567 -0.491888 -0.450209 -0.408530   2.0  0.807291  0.761937  0.268520  0.537905  0.807291  1.076676  1.346061
4   1.0 -0.862495       NaN -0.862495 -0.862495 -0.862495 -0.862495 -0.862495   1.0  0.024580       NaN  0.024580  0.024580  0.024580  0.024580  0.024580
5   2.0  0.024925  1.652692 -1.143704 -0.559389  0.024925  0.609240  1.193555   2.0  0.592714  1.462816 -0.441652  0.075531  0.592714  1.109898  1.627081

Note

Aggregation functions will not return the groups that you are aggregating overif they are named columns, when as_index=True, the default. The grouped columns willbe the indices of the returned object.

Passing asindex=False will return the groups that you are aggregating over, if they arenamed _columns.

Aggregating functions are the ones that reduce the dimension of the returned objects.Some common aggregating functions are tabulated below:

The aggregating functions above will exclude NA values. Any function whichreduces a Series to a scalar value is an aggregation function and will work,a trivial example is df.groupby('A').agg(lambda ser: 1). Note thatnth() can act as a reducer or afilter, see here.

Applying multiple functions at once

With grouped Series you can also pass a list or dict of functions to doaggregation with, outputting a DataFrame:

In [72]: grouped = df.groupby('A')
 
In [73]: grouped['C'].agg([np.sum, np.mean, np.std])
Out[73]: 
          sum      mean       std
A                                
bar  0.392940  0.130980  0.181231
foo -1.796421 -0.359284  0.912265

On a grouped DataFrame, you can pass a list of functions to apply to eachcolumn, which produces an aggregated result with a hierarchical index:

In [74]: grouped.agg([np.sum, np.mean, np.std])
Out[74]: 
            C                             D                    
          sum      mean       std       sum      mean       std
A                                                              
bar  0.392940  0.130980  0.181231  1.732707  0.577569  1.366330
foo -1.796421 -0.359284  0.912265  2.824590  0.564918  0.884785

The resulting aggregations are named for the functions themselves. If youneed to rename, then you can add in a chained operation for a Series like this:

In [75]: (grouped['C'].agg([np.sum, np.mean, np.std])
   ....:              .rename(columns={'sum': 'foo',
   ....:                               'mean': 'bar',
   ....:                               'std': 'baz'}))
   ....: 
Out[75]: 
          foo       bar       baz
A                                
bar  0.392940  0.130980  0.181231
foo -1.796421 -0.359284  0.912265

For a grouped DataFrame, you can rename in a similar manner:

In [76]: (grouped.agg([np.sum, np.mean, np.std])
   ....:         .rename(columns={'sum': 'foo',
   ....:                          'mean': 'bar',
   ....:                          'std': 'baz'}))
   ....: 
Out[76]: 
            C                             D                    
          foo       bar       baz       foo       bar       baz
A                                                              
bar  0.392940  0.130980  0.181231  1.732707  0.577569  1.366330
foo -1.796421 -0.359284  0.912265  2.824590  0.564918  0.884785

Note

In general, the output column names should be unique. You can’t applythe same function (or two functions with the same name) to the samecolumn.

In [77]: grouped['C'].agg(['sum', 'sum'])

SpecificationError Traceback (most recent call last)<ipython-input-77-7be02859f395> in <module>——> 1 grouped['C'].agg(['sum', 'sum'])

/pandas/pandas/core/groupby/generic.py in aggregate(self, func_or_funcs, args, *kwargs) 849 # but not the class list / tuple itself. 850 func_or_funcs = _maybe_mangle_lambdas(func_or_funcs)—> 851 ret = self._aggregate_multiple_funcs(func_or_funcs, (_level or 0) + 1) 852 if relabeling: 853 ret.columns = columns

/pandas/pandas/core/groupby/generic.py in _aggregate_multiple_funcs(self, arg, _level) 919 raise SpecificationError( 920 "Function names must be unique, found multiple named "—> 921 "{}".format(name) 922 ) 923

SpecificationError: Function names must be unique, found multiple named sum

Pandas does allow you to provide multiple lambdas. In this case, pandaswill mangle the name of the (nameless) lambda functions, appending _<i>to each subsequent lambda.

In [78]: grouped['C'].agg([lambda x: x.max() - x.min(),
   ....:                   lambda x: x.median() - x.mean()])
   ....: 
Out[78]: 
     <lambda_0>  <lambda_1>
A                          
bar    0.331279    0.084917
foo    2.337259   -0.215962

Named aggregation

New in version 0.25.0.

To support column-specific aggregation with control over the output column names, pandasaccepts the special syntax in GroupBy.agg(), known as “named aggregation”, where

• The keywords are the output column names
• The values are tuples whose first element is the column to selectand the second element is the aggregation to apply to that column. Pandasprovides the pandas.NamedAgg namedtuple with the fields ['column', 'aggfunc']to make it clearer what the arguments are. As usual, the aggregation canbe a callable or a string alias.

In [79]: animals = pd.DataFrame({'kind': ['cat', 'dog', 'cat', 'dog'],
   ....:                         'height': [9.1, 6.0, 9.5, 34.0],
   ....:                         'weight': [7.9, 7.5, 9.9, 198.0]})
   ....: 
 
In [80]: animals
Out[80]: 
  kind  height  weight
0  cat     9.1     7.9
1  dog     6.0     7.5
2  cat     9.5     9.9
3  dog    34.0   198.0
 
In [81]: animals.groupby("kind").agg(
   ....:     min_height=pd.NamedAgg(column='height', aggfunc='min'),
   ....:     max_height=pd.NamedAgg(column='height', aggfunc='max'),
   ....:     average_weight=pd.NamedAgg(column='weight', aggfunc=np.mean),
   ....: )
   ....: 
Out[81]: 
      min_height  max_height  average_weight
kind                                        
cat          9.1         9.5            8.90
dog          6.0        34.0          102.75

pandas.NamedAgg is just a namedtuple. Plain tuples are allowed as well.

In [82]: animals.groupby("kind").agg(
   ....:     min_height=('height', 'min'),
   ....:     max_height=('height', 'max'),
   ....:     average_weight=('weight', np.mean),
   ....: )
   ....: 
Out[82]: 
      min_height  max_height  average_weight
kind                                        
cat          9.1         9.5            8.90
dog          6.0        34.0          102.75

If your desired output column names are not valid python keywords, construct a dictionaryand unpack the keyword arguments

In [83]: animals.groupby("kind").agg(**{
   ....:     'total weight': pd.NamedAgg(column='weight', aggfunc=sum),
   ....: })
   ....: 
Out[83]: 
      total weight
kind              
cat           17.8
dog          205.5

Additional keyword arguments are not passed through to the aggregation functions. Only pairsof (column, aggfunc) should be passed as **kwargs. If your aggregation functionsrequires additional arguments, partially apply them with functools.partial().

Note

For Python 3.5 and earlier, the order of **kwargs in a functions was notpreserved. This means that the output column ordering would not beconsistent. To ensure consistent ordering, the keys (and so output columns)will always be sorted for Python 3.5.

Named aggregation is also valid for Series groupby aggregations. In this case there’sno column selection, so the values are just the functions.

In [84]: animals.groupby("kind").height.agg(
   ....:     min_height='min',
   ....:     max_height='max',
   ....: )
   ....: 
Out[84]: 
      min_height  max_height
kind                        
cat          9.1         9.5
dog          6.0        34.0

Applying different functions to DataFrame columns

By passing a dict to aggregate you can apply a different aggregation to thecolumns of a DataFrame:

In [85]: grouped.agg({'C': np.sum,
   ....:              'D': lambda x: np.std(x, ddof=1)})
   ....: 
Out[85]: 
            C         D
A                      
bar  0.392940  1.366330
foo -1.796421  0.884785

The function names can also be strings. In order for a string to be valid itmust be either implemented on GroupBy or available via dispatching:

In [86]: grouped.agg({'C': 'sum', 'D': 'std'})
Out[86]: 
            C         D
A                      
bar  0.392940  1.366330
foo -1.796421  0.884785

Cython-optimized aggregation functions

Some common aggregations, currently only sum, mean, std, and sem, haveoptimized Cython implementations:

In [87]: df.groupby('A').sum()
Out[87]: 
            C         D
A                      
bar  0.392940  1.732707
foo -1.796421  2.824590
 
In [88]: df.groupby(['A', 'B']).mean()
Out[88]: 
                  C         D
A   B                        
bar one    0.254161  1.511763
    three  0.215897 -0.990582
    two   -0.077118  1.211526
foo one   -0.491888  0.807291
    three -0.862495  0.024580
    two    0.024925  0.592714

Of course sum and mean are implemented on pandas objects, so the abovecode would work even without the special versions via dispatching (see below).

Transformation

The transform method returns an object that is indexed the same (same size)as the one being grouped. The transform function must:

• Return a result that is either the same size as the group chunk orbroadcastable to the size of the group chunk (e.g., a scalar,grouped.transform(lambda x: x.iloc[-1])).
• Operate column-by-column on the group chunk. The transform is applied tothe first group chunk using chunk.apply.
• Not perform in-place operations on the group chunk. Group chunks shouldbe treated as immutable, and changes to a group chunk may produce unexpectedresults. For example, when using fillna, inplace must be False(grouped.transform(lambda x: x.fillna(inplace=False))).
• (Optionally) operates on the entire group chunk. If this is supported, afast path is used starting from the second chunk.

For example, suppose we wished to standardize the data within each group:

In [89]: index = pd.date_range('10/1/1999', periods=1100)
 
In [90]: ts = pd.Series(np.random.normal(0.5, 2, 1100), index)
 
In [91]: ts = ts.rolling(window=100, min_periods=100).mean().dropna()
 
In [92]: ts.head()
Out[92]: 
2000-01-08    0.779333
2000-01-09    0.778852
2000-01-10    0.786476
2000-01-11    0.782797
2000-01-12    0.798110
Freq: D, dtype: float64
 
In [93]: ts.tail()
Out[93]: 
2002-09-30    0.660294
2002-10-01    0.631095
2002-10-02    0.673601
2002-10-03    0.709213
2002-10-04    0.719369
Freq: D, dtype: float64
 
In [94]: transformed = (ts.groupby(lambda x: x.year)
   ....:                  .transform(lambda x: (x - x.mean()) / x.std()))
   ....: 

We would expect the result to now have mean 0 and standard deviation 1 withineach group, which we can easily check:

# Original Data
In [95]: grouped = ts.groupby(lambda x: x.year)
 
In [96]: grouped.mean()
Out[96]: 
2000    0.442441
2001    0.526246
2002    0.459365
dtype: float64
 
In [97]: grouped.std()
Out[97]: 
2000    0.131752
2001    0.210945
2002    0.128753
dtype: float64
 
# Transformed Data
In [98]: grouped_trans = transformed.groupby(lambda x: x.year)
 
In [99]: grouped_trans.mean()
Out[99]: 
2000    1.168208e-15
2001    1.454544e-15
2002    1.726657e-15
dtype: float64
 
In [100]: grouped_trans.std()
Out[100]: 
2000    1.0
2001    1.0
2002    1.0
dtype: float64

We can also visually compare the original and transformed data sets.

In [101]: compare = pd.DataFrame({'Original': ts, 'Transformed': transformed})
 
In [102]: compare.plot()
Out[102]: <matplotlib.axes._subplots.AxesSubplot at 0x7f45292f6910>

Transformation functions that have lower dimension outputs are broadcast tomatch the shape of the input array.

In [103]: ts.groupby(lambda x: x.year).transform(lambda x: x.max() - x.min())
Out[103]: 
2000-01-08    0.623893
2000-01-09    0.623893
2000-01-10    0.623893
2000-01-11    0.623893
2000-01-12    0.623893
                ...   
2002-09-30    0.558275
2002-10-01    0.558275
2002-10-02    0.558275
2002-10-03    0.558275
2002-10-04    0.558275
Freq: D, Length: 1001, dtype: float64

Alternatively, the built-in methods could be used to produce the same outputs.

In [104]: max = ts.groupby(lambda x: x.year).transform('max')
 
In [105]: min = ts.groupby(lambda x: x.year).transform('min')
 
In [106]: max - min
Out[106]: 
2000-01-08    0.623893
2000-01-09    0.623893
2000-01-10    0.623893
2000-01-11    0.623893
2000-01-12    0.623893
                ...   
2002-09-30    0.558275
2002-10-01    0.558275
2002-10-02    0.558275
2002-10-03    0.558275
2002-10-04    0.558275
Freq: D, Length: 1001, dtype: float64

Another common data transform is to replace missing data with the group mean.

In [107]: data_df
Out[107]: 
            A         B         C
0    1.539708 -1.166480  0.533026
1    1.302092 -0.505754       NaN
2   -0.371983  1.104803 -0.651520
3   -1.309622  1.118697 -1.161657
4   -1.924296  0.396437  0.812436
..        ...       ...       ...
995 -0.093110  0.683847 -0.774753
996 -0.185043  1.438572       NaN
997 -0.394469 -0.642343  0.011374
998 -1.174126  1.857148       NaN
999  0.234564  0.517098  0.393534
 
[1000 rows x 3 columns]
 
In [108]: countries = np.array(['US', 'UK', 'GR', 'JP'])
 
In [109]: key = countries[np.random.randint(0, 4, 1000)]
 
In [110]: grouped = data_df.groupby(key)
 
# Non-NA count in each group
In [111]: grouped.count()
Out[111]: 
      A    B    C
GR  209  217  189
JP  240  255  217
UK  216  231  193
US  239  250  217
 
In [112]: transformed = grouped.transform(lambda x: x.fillna(x.mean()))

We can verify that the group means have not changed in the transformed dataand that the transformed data contains no NAs.

In [113]: grouped_trans = transformed.groupby(key)
 
In [114]: grouped.mean()  # original group means
Out[114]: 
           A         B         C
GR -0.098371 -0.015420  0.068053
JP  0.069025  0.023100 -0.077324
UK  0.034069 -0.052580 -0.116525
US  0.058664 -0.020399  0.028603
 
In [115]: grouped_trans.mean()  # transformation did not change group means
Out[115]: 
           A         B         C
GR -0.098371 -0.015420  0.068053
JP  0.069025  0.023100 -0.077324
UK  0.034069 -0.052580 -0.116525
US  0.058664 -0.020399  0.028603
 
In [116]: grouped.count()  # original has some missing data points
Out[116]: 
      A    B    C
GR  209  217  189
JP  240  255  217
UK  216  231  193
US  239  250  217
 
In [117]: grouped_trans.count()  # counts after transformation
Out[117]: 
      A    B    C
GR  228  228  228
JP  267  267  267
UK  247  247  247
US  258  258  258
 
In [118]: grouped_trans.size()  # Verify non-NA count equals group size
Out[118]: 
GR    228
JP    267
UK    247
US    258
dtype: int64

Note

Some functions will automatically transform the input when applied to aGroupBy object, but returning an object of the same shape as the original.Passing as_index=False will not affect these transformation methods.

For example: fillna, ffill, bfill, shift..

In [119]: grouped.ffill()
Out[119]: 
            A         B         C
0    1.539708 -1.166480  0.533026
1    1.302092 -0.505754  0.533026
2   -0.371983  1.104803 -0.651520
3   -1.309622  1.118697 -1.161657
4   -1.924296  0.396437  0.812436
..        ...       ...       ...
995 -0.093110  0.683847 -0.774753
996 -0.185043  1.438572 -0.774753
997 -0.394469 -0.642343  0.011374
998 -1.174126  1.857148 -0.774753
999  0.234564  0.517098  0.393534
 
[1000 rows x 3 columns]

New syntax to window and resample operations

New in version 0.18.1.

Working with the resample, expanding or rolling operations on the groupbylevel used to require the application of helper functions. However,now it is possible to use resample(), expanding() androlling() as methods on groupbys.

The example below will apply the rolling() method on the samples ofthe column B based on the groups of column A.

In [120]: df_re = pd.DataFrame({'A': [1] * 10 + [5] * 10,
   .....:                       'B': np.arange(20)})
   .....: 
 
In [121]: df_re
Out[121]: 
    A   B
0   1   0
1   1   1
2   1   2
3   1   3
4   1   4
.. ..  ..
15  5  15
16  5  16
17  5  17
18  5  18
19  5  19
 
[20 rows x 2 columns]
 
In [122]: df_re.groupby('A').rolling(4).B.mean()
Out[122]: 
A    
1  0      NaN
   1      NaN
   2      NaN
   3      1.5
   4      2.5
         ... 
5  15    13.5
   16    14.5
   17    15.5
   18    16.5
   19    17.5
Name: B, Length: 20, dtype: float64

The expanding() method will accumulate a given operation(sum() in the example) for all the members of each particulargroup.

In [123]: df_re.groupby('A').expanding().sum()
Out[123]: 
         A      B
A                
1 0    1.0    0.0
  1    2.0    1.0
  2    3.0    3.0
  3    4.0    6.0
  4    5.0   10.0
...    ...    ...
5 15  30.0   75.0
  16  35.0   91.0
  17  40.0  108.0
  18  45.0  126.0
  19  50.0  145.0
 
[20 rows x 2 columns]

Suppose you want to use the resample() method to get a dailyfrequency in each group of your dataframe and wish to complete themissing values with the ffill() method.

In [124]: df_re = pd.DataFrame({'date': pd.date_range(start='2016-01-01', periods=4,
   .....:                                             freq='W'),
   .....:                       'group': [1, 1, 2, 2],
   .....:                       'val': [5, 6, 7, 8]}).set_index('date')
   .....: 
 
In [125]: df_re
Out[125]: 
            group  val
date                  
2016-01-03      1    5
2016-01-10      1    6
2016-01-17      2    7
2016-01-24      2    8
 
In [126]: df_re.groupby('group').resample('1D').ffill()
Out[126]: 
                  group  val
group date                  
1     2016-01-03      1    5
      2016-01-04      1    5
      2016-01-05      1    5
      2016-01-06      1    5
      2016-01-07      1    5
...                 ...  ...
2     2016-01-20      2    7
      2016-01-21      2    7
      2016-01-22      2    7
      2016-01-23      2    7
      2016-01-24      2    8
 
[16 rows x 2 columns]

Filtration

The filter method returns a subset of the original object. Suppose wewant to take only elements that belong to groups with a group sum greaterthan 2.

In [127]: sf = pd.Series([1, 1, 2, 3, 3, 3])
 
In [128]: sf.groupby(sf).filter(lambda x: x.sum() > 2)
Out[128]: 
3    3
4    3
5    3
dtype: int64

The argument of filter must be a function that, applied to the group as awhole, returns True or False.

Another useful operation is filtering out elements that belong to groupswith only a couple members.

In [129]: dff = pd.DataFrame({'A': np.arange(8), 'B': list('aabbbbcc')})
 
In [130]: dff.groupby('B').filter(lambda x: len(x) > 2)
Out[130]: 
   A  B
2  2  b
3  3  b
4  4  b
5  5  b

Alternatively, instead of dropping the offending groups, we can return alike-indexed objects where the groups that do not pass the filter are filledwith NaNs.

In [131]: dff.groupby('B').filter(lambda x: len(x) > 2, dropna=False)
Out[131]: 
     A    B
0  NaN  NaN
1  NaN  NaN
2  2.0    b
3  3.0    b
4  4.0    b
5  5.0    b
6  NaN  NaN
7  NaN  NaN

For DataFrames with multiple columns, filters should explicitly specify a column as the filter criterion.

In [132]: dff['C'] = np.arange(8)
 
In [133]: dff.groupby('B').filter(lambda x: len(x['C']) > 2)
Out[133]: 
   A  B  C
2  2  b  2
3  3  b  3
4  4  b  4
5  5  b  5

Note

Some functions when applied to a groupby object will act as a filter on the input, returninga reduced shape of the original (and potentially eliminating groups), but with the index unchanged.Passing as_index=False will not affect these transformation methods.

For example: head, tail.

In [134]: dff.groupby('B').head(2)
Out[134]: 
   A  B  C
0  0  a  0
1  1  a  1
2  2  b  2
3  3  b  3
6  6  c  6
7  7  c  7

Dispatching to instance methods

When doing an aggregation or transformation, you might just want to call aninstance method on each data group. This is pretty easy to do by passing lambdafunctions:

In [135]: grouped = df.groupby('A')
 
In [136]: grouped.agg(lambda x: x.std())
Out[136]: 
            C         D
A                      
bar  0.181231  1.366330
foo  0.912265  0.884785

But, it’s rather verbose and can be untidy if you need to pass additionalarguments. Using a bit of metaprogramming cleverness, GroupBy now has theability to “dispatch” method calls to the groups:

In [137]: grouped.std()
Out[137]: 
            C         D
A                      
bar  0.181231  1.366330
foo  0.912265  0.884785

What is actually happening here is that a function wrapper is beinggenerated. When invoked, it takes any passed arguments and invokes the functionwith any arguments on each group (in the above example, the stdfunction). The results are then combined together much in the style of aggand transform (it actually uses apply to infer the gluing, documentednext). This enables some operations to be carried out rather succinctly:

In [138]: tsdf = pd.DataFrame(np.random.randn(1000, 3),
   .....:                     index=pd.date_range('1/1/2000', periods=1000),
   .....:                     columns=['A', 'B', 'C'])
   .....: 
 
In [139]: tsdf.iloc[::2] = np.nan
 
In [140]: grouped = tsdf.groupby(lambda x: x.year)
 
In [141]: grouped.fillna(method='pad')
Out[141]: 
                   A         B         C
2000-01-01       NaN       NaN       NaN
2000-01-02 -0.353501 -0.080957 -0.876864
2000-01-03 -0.353501 -0.080957 -0.876864
2000-01-04  0.050976  0.044273 -0.559849
2000-01-05  0.050976  0.044273 -0.559849
...              ...       ...       ...
2002-09-22  0.005011  0.053897 -1.026922
2002-09-23  0.005011  0.053897 -1.026922
2002-09-24 -0.456542 -1.849051  1.559856
2002-09-25 -0.456542 -1.849051  1.559856
2002-09-26  1.123162  0.354660  1.128135
 
[1000 rows x 3 columns]

In this example, we chopped the collection of time series into yearly chunksthen independently called fillna on thegroups.

The nlargest and nsmallest methods work on Series style groupbys:

In [142]: s = pd.Series([9, 8, 7, 5, 19, 1, 4.2, 3.3])
 
In [143]: g = pd.Series(list('abababab'))
 
In [144]: gb = s.groupby(g)
 
In [145]: gb.nlargest(3)
Out[145]: 
a  4    19.0
   0     9.0
   2     7.0
b  1     8.0
   3     5.0
   7     3.3
dtype: float64
 
In [146]: gb.nsmallest(3)
Out[146]: 
a  6    4.2
   2    7.0
   0    9.0
b  5    1.0
   7    3.3
   3    5.0
dtype: float64