pandas 0.7.0 documentation

Group By: split-apply-combine

By “group by” we are refer to a process involving one or more of the following steps

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

Of these, the split step is the most straightforward. In fact, in many situations you may wish to split the data set into groups and do something with those groups yourself. In the apply step, we might wish to one of the following:

  • Aggregation: computing a summary statistic (or statistics) about each group. Some examples:

    • Compute group sums or means
    • Compute group sizes / counts
  • Transformation: perform some group-specific computations and return a like-indexed. Some examples:

    • Standardizing data (zscore) within group
    • Filling NAs within groups with a value derived from each group
  • Some combination of the above: GroupBy will examine the results of the apply step and try to return a sensibly combined result if it doesn’t fit into either of the above two categories

Since the set of object instance method on pandas data structures are generally rich and expressive, we often simply want to invoke, say, a DataFrame function on each group. The name GroupBy should be quite familiar to those who have used a 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 using pandas. We’ll address each area of GroupBy functionality then provide some non-trivial examples / use cases.

Splitting an object into groups

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

>>> grouped = obj.groupby(key)
>>> grouped = obj.groupby(key, axis=1)
>>> grouped = obj.groupby([key1, key2])

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 for df.groupby(df['A']), but it makes life simpler
  • A list of any of the above things

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

In [357]: df = DataFrame({'A' : ['foo', 'bar', 'foo', 'bar',
   .....:                        'foo', 'bar', 'foo', 'foo'],
   .....:                 'B' : ['one', 'one', 'two', 'three',
   .....:                        'two', 'two', 'one', 'three'],
   .....:                 'C' : randn(8), 'D' : randn(8)})

In [358]: df
Out[358]: 
     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

We could naturally group by either the A or B columns or both:

In [359]: grouped = df.groupby('A')

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

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

In [361]: def get_letter_type(letter):
   .....:     if letter.lower() in 'aeiou':
   .....:         return 'vowel'
   .....:     else:
   .....:         return 'consonant'
   .....:

In [362]: grouped = df.groupby(get_letter_type, axis=1)

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

Note

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

GroupBy object attributes

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

In [363]: df.groupby('A').groups
Out[363]: {'bar': [1, 3, 5], 'foo': [0, 2, 4, 6, 7]}

In [364]: df.groupby(get_letter_type, axis=1).groups
Out[364]: {'consonant': ['B', 'C', 'D'], 'vowel': ['A']}

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

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

In [366]: grouped.groups
Out[366]: 
{('bar', 'one'): [1],
 ('bar', 'three'): [3],
 ('bar', 'two'): [5],
 ('foo', 'one'): [0, 6],
 ('foo', 'three'): [7],
 ('foo', 'two'): [2, 4]}

In [367]: len(grouped)
Out[367]: 6

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

In [368]: df2 = DataFrame({'X' : ['B', 'B', 'A', 'A'], 'Y' : [1, 2, 3, 4]})

In [369]: df2.groupby(['X'], sort=True).sum()
Out[369]: 
   Y
X   
A  7
B  3

In [370]: df2.groupby(['X'], sort=False).sum()
Out[370]: 
   Y
X   
B  3
A  7

GroupBy with MultiIndex

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

In [371]: s
Out[371]: 
first  second
bar    one      -0.424972
       two       0.567020
baz    one       0.276232
       two      -1.087401
foo    one      -0.673690
       two       0.113648
qux    one      -1.478427
       two       0.524988

In [372]: grouped = s.groupby(level=0)

In [373]: grouped.sum()
Out[373]: 
first
bar      0.142048
baz     -0.811169
foo     -0.560041
qux     -0.953439

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

In [374]: s.groupby(level='second').sum()
Out[374]: 
second
one      -2.300857
two       0.118256

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

In [375]: s.sum(level='second')
Out[375]: 
second
one      -2.300857
two       0.118256

Also as of v0.6, grouping with multiple levels is supported.

In [376]: s
Out[376]: 
first  second  third
bar    doo     one      0.404705
               two      0.577046
baz    bee     one     -1.715002
               two     -1.039268
foo    bop     one     -0.370647
               two     -1.157892
qux            one     -1.344312
               two      0.844885

In [377]: s.groupby(level=['first','second']).sum()
Out[377]: 
first  second
bar    doo       0.981751
baz    bee      -2.754270
foo    bop      -1.528539
qux    bop      -0.499427

More on the sum function and aggregation later.

DataFrame column selection in GroupBy

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

In [378]: grouped = df.groupby(['A'])

In [379]: grouped_C = grouped['C']

In [380]: grouped_D = grouped['D']

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

In [381]: df['C'].groupby(df['A'])
Out[381]: <pandas.core.groupby.SeriesGroupBy at 0x1132bc890>

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

Iterating through groups

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

In [382]: grouped = df.groupby('A')

In [383]: for name, group in grouped:
   .....:        print name
   .....:        print group
   .....:
bar
     A      B         C         D
1  bar    one -0.282863 -2.104569
3  bar  three -1.135632  1.071804
5  bar    two -0.173215 -0.706771
foo
     A      B         C         D
0  foo    one  0.469112 -0.861849
2  foo    two -1.509059 -0.494929
4  foo    two  1.212112  0.721555
6  foo    one  0.119209 -1.039575
7  foo  three -1.044236  0.271860

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

In [384]: for name, group in df.groupby(['A', 'B']):
   .....:        print name
   .....:        print group
   .....:
('bar', 'one')
     A    B         C         D
1  bar  one -0.282863 -2.104569
('bar', 'three')
     A      B         C         D
3  bar  three -1.135632  1.071804
('bar', 'two')
     A    B         C         D
5  bar  two -0.173215 -0.706771
('foo', 'one')
     A    B         C         D
0  foo  one  0.469112 -0.861849
6  foo  one  0.119209 -1.039575
('foo', 'three')
     A      B         C        D
7  foo  three -1.044236  0.27186
('foo', 'two')
     A    B         C         D
2  foo  two -1.509059 -0.494929
4  foo  two  1.212112  0.721555

It’s standard Python-fu but remember you can unpack the tuple in the for loop statement if you wish: for (k1, k2), group in grouped:.

Aggregation

Once the GroupBy object has been created, several methods are available to perform a computation on the grouped data. An obvious one is aggregation via the aggregate or equivalently agg method:

In [385]: grouped = df.groupby('A')

In [386]: grouped.aggregate(np.sum)
Out[386]: 
                     B         C         D
A                                         
bar        onethreetwo -1.591710 -1.739537
foo  onetwotwoonethree -0.752861 -1.402938

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

In [388]: grouped.aggregate(np.sum)
Out[388]: 
                  C         D
A   B                        
bar one   -0.282863 -2.104569
    three -1.135632  1.071804
    two   -0.173215 -0.706771
foo one    0.588321 -1.901424
    three -1.044236  0.271860
    two   -0.296946  0.226626

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

In [389]: grouped = df.groupby(['A', 'B'], as_index=False)

In [390]: grouped.aggregate(np.sum)
Out[390]: 
     A      B         C         D
0  bar    one -0.282863 -2.104569
1  bar  three -1.135632  1.071804
2  bar    two -0.173215 -0.706771
3  foo    one  0.588321 -1.901424
4  foo  three -1.044236  0.271860
5  foo    two -0.296946  0.226626

In [391]: df.groupby('A', as_index=False).sum()
Out[391]: 
     A         C         D
0  bar -1.591710 -1.739537
1  foo -0.752861 -1.402938

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

In [392]: df.groupby(['A', 'B']).sum().reset_index()
Out[392]: 
     A      B         C         D
0  bar    one -0.282863 -2.104569
1  bar  three -1.135632  1.071804
2  bar    two -0.173215 -0.706771
3  foo    one  0.588321 -1.901424
4  foo  three -1.044236  0.271860
5  foo    two -0.296946  0.226626

Applying multiple functions at once

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

In [393]: grouped = df.groupby('A')

In [394]: grouped['C'].agg([np.sum, np.mean, np.std])
Out[394]: 
         mean       std       sum
A                                
bar -0.530570  0.526860 -1.591710
foo -0.150572  1.113308 -0.752861

If a dict is passed, the keys will be used to name the columns. Otherwise the function’s name (stored in the function object) will be used.

In [395]: grouped['D'].agg({'result1' : np.sum,
   .....:                   'result2' : np.mean})
Out[395]: 
      result1   result2
A                      
bar -1.739537 -0.579846
foo -1.402938 -0.280588

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

In [396]: grouped.agg([np.sum, np.mean, np.std])
Out[396]: 
            C                             D                    
         mean       std       sum      mean       std       sum
A                                                              
bar -0.530570  0.526860 -1.591710 -0.579846  1.591986 -1.739537
foo -0.150572  1.113308 -0.752861 -0.280588  0.753219 -1.402938

Passing a dict of functions has different behavior by default, see the next section.

Applying different functions to DataFrame columns

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

In [397]: grouped.agg({'C' : np.sum,
   .....:              'D' : lambda x: np.std(x, ddof=1)})
Out[397]: 
            C         D
A                      
bar -1.591710  1.591986
foo -0.752861  0.753219

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

In [398]: grouped.agg({'C' : 'sum', 'D' : 'std'})
Out[398]: 
            C         D
A                      
bar -1.591710  1.591986
foo -0.752861  0.753219

Cython-optimized aggregation functions

Some common aggregations, currently only sum, mean, and std, have optimized Cython implementations:

In [399]: df.groupby('A').sum()
Out[399]: 
            C         D
A                      
bar -1.591710 -1.739537
foo -0.752861 -1.402938

In [400]: df.groupby(['A', 'B']).mean()
Out[400]: 
                  C         D
A   B                        
bar one   -0.282863 -2.104569
    three -1.135632  1.071804
    two   -0.173215 -0.706771
foo one    0.294161 -0.950712
    three -1.044236  0.271860
    two   -0.148473  0.113313

Of course sum and mean are implemented on pandas objects, so the above code 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. Thus, the passed transform function should return a result that is the same size as the group chunk. For example, suppose we wished to standardize a data set within a group:

In [401]: tsdf = DataFrame(randn(1000, 3),
   .....:                  index=DateRange('1/1/2000', periods=1000),
   .....:                  columns=['A', 'B', 'C'])

In [402]: tsdf
Out[402]: 
<class 'pandas.core.frame.DataFrame'>
DateRange: 1000 entries, 2000-01-03 00:00:00 to 2003-10-31 00:00:00
offset: <1 BusinessDay>
Data columns:
A    1000  non-null values
B    1000  non-null values
C    1000  non-null values
dtypes: float64(3)

In [403]: zscore = lambda x: (x - x.mean()) / x.std()

In [404]: transformed = tsdf.groupby(lambda x: x.year).transform(zscore)

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

In [405]: grouped = transformed.groupby(lambda x: x.year)

# OK, close enough to zero
In [406]: grouped.mean()
Out[406]: 
       A  B  C
key_0         
2000  -0 -0  0
2001  -0  0  0
2002   0 -0 -0
2003   0 -0 -0

In [407]: grouped.std()
Out[407]: 
       A  B  C
key_0         
2000   1  1  1
2001   1  1  1
2002   1  1  1
2003   1  1  1

Dispatching to instance methods

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

In [408]: grouped = df.groupby('A')

In [409]: grouped.agg(lambda x: x.std())
Out[409]: 
      B         C         D
A                          
bar NaN  0.526860  1.591986
foo NaN  1.113308  0.753219

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

In [410]: grouped.std()
Out[410]: 
            C         D
A                      
bar  0.526860  1.591986
foo  1.113308  0.753219

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

In [411]: tsdf.ix[::2] = np.nan

In [412]: grouped = tsdf.groupby(lambda x: x.year)

In [413]: grouped.fillna(method='pad')
Out[413]: 
<class 'pandas.core.frame.DataFrame'>
DateRange: 1000 entries, 2000-01-03 00:00:00 to 2003-10-31 00:00:00
offset: <1 BusinessDay>
Data columns:
A    997  non-null values
B    997  non-null values
C    997  non-null values
dtypes: float64(3)

In this example, we chopped the collection of time series into yearly chunks then independently called fillna on the groups.

Flexible apply

Some operations on the grouped data might not fit into either the aggregate or transform categories. Or, you may simply want GroupBy to infer how to combine the results. For these, use the apply function, which can be substituted for both aggregate and transform in many standard use cases. However, apply can handle some exceptional use cases, for example:

In [414]: df
Out[414]: 
     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

In [415]: grouped = df.groupby('A')

# could also just call .describe()
In [416]: grouped['C'].apply(lambda x: x.describe())
Out[416]: 
     count      mean       std       min       25%       50%       75%       max
A                                                                               
bar      3 -0.530570  0.526860 -1.135632 -0.709248 -0.282863 -0.228039 -0.173215
foo      5 -0.150572  1.113308 -1.509059 -1.044236  0.119209  0.469112  1.212112

The dimension of the returned result can also change:

In [417]: grouped = df.groupby('A')['C']

In [418]: def f(group):
   .....:     return DataFrame({'original' : group,
   .....:                       'demeaned' : group - group.mean()})
   .....:

In [419]: grouped.apply(f)
Out[419]: 
   demeaned  original
0  0.619685  0.469112
1  0.247707 -0.282863
2 -1.358486 -1.509059
3 -0.605062 -1.135632
4  1.362684  1.212112
5  0.357355 -0.173215
6  0.269781  0.119209
7 -0.893664 -1.044236

Other useful features

Automatic exclusion of “nuisance” columns

Again consider the example DataFrame we’ve been looking at:

In [420]: df
Out[420]: 
     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

Supposed we wished to compute the standard deviation grouped by the A column. There is a slight problem, namely that we don’t care about the data in column B. We refer to this as a “nuisance” column. If the passed aggregation function can’t be applied to some columns, the troublesome columns will be (silently) dropped. Thus, this does not pose any problems:

In [421]: df.groupby('A').std()
Out[421]: 
            C         D
A                      
bar  0.526860  1.591986
foo  1.113308  0.753219

NA group handling

If there are any NaN values in the grouping key, these will be automatically excluded. So there will never be an “NA group”. This was not the case in older versions of pandas, but users were generally discarding the NA group anyway (and supporting it was an implementation headache).