A couple of weeks ago in my inaugural blog post I wrote about the state of GroupBy in pandas and gave an example application. However, I was dissatisfied with the limited expressiveness (see the end of the article), so I decided to invest some serious time in the groupby functionality in pandas over the last 2 weeks in beefing up what you can do. So this article is a part show-and-tell, part quick tutorial on the new features. Note that I haven't added a lot of this to the official documentation yet.
GroupBy primer
GroupBy may be one of the least well-understood features in pandas. Let's consider a DataFrame (basically a labeled 2D array):
In [18]: df
Out[18]:
A B C D
2000-03-31 00:00:00 0.6304 -1.493 0.2082 0.3378
2000-06-30 00:00:00 -0.1041 1.093 0.1227 -0.2362
2000-09-29 00:00:00 -1.822 0.7325 -0.4964 -1.707
2000-12-29 00:00:00 0.3325 -0.2213 0.5465 1.265
2001-03-30 00:00:00 0.8422 -0.1265 0.1234 0.7743
2001-06-29 00:00:00 -0.07774 -0.3906 -0.6328 -1.259
2001-09-28 00:00:00 -0.3417 -0.4209 1.724 0.3069
2001-12-31 00:00:00 0.493 -0.2815 1.314 1.004
2002-03-29 00:00:00 1.003 -0.4807 0.7232 1.079
2002-06-28 00:00:00 0.1415 -2.275 0.6178 0.8817
2002-09-30 00:00:00 -0.6855 0.3921 -1.468 1.522
2002-12-31 00:00:00 -1.635 0.3083 0.1209 -0.5606
2003-03-31 00:00:00 0.5707 -0.7125 -0.07677 0.5154
2003-06-30 00:00:00 0.3646 -0.8574 -0.562 0.2176
2003-09-30 00:00:00 1.024 -0.8113 0.6771 -1.261
Here, the index (row labels) contains dates and the columns are names for each time series. When performing a groupby operation, we may different goals:
- Perform an aggregation, like computing the sum of mean of each group. Functionally this means applying a function to each group and putting the aggregated results into a DataFrame
- Slicing the DataFrame into chunks (groups) and then doing something with the slices
- Performing a transformation, like standardizing each group (computing the zscore)
So there are two tasks: first, grouping the data; second, doing something with the grouped data. As far as grouping, in a totally abstract sense we have to define some kind of mapping that assigns labels (one of the axes) into group buckets. A mapping could be one of many things:
- A Python function, to be called on each label
- A dict, containing {label : group_name} mappings
- An array the same length as the axis containing the group correspondences. This may often be one of the columns in a DataFrame, but need not be. Every other mapping type gets rendered to this form eventually.
So in the above data, let's say we wanted to group the data by year. Since the row labels are Python datetime objects, we can access the year attribute when calling groupby
In [21]: grouped = df.groupby(lambda x: x.year)
This returns an object of type GroupBy. With this object, you can do a lot of things including: iteration, aggregation, or transformation. So we could iterate like so:
In [20]: for year, group in grouped: ....: print year ....: print group ....: 2000 A B C D 2000-03-31 00:00:00 0.6304 -1.493 0.2082 0.3378 2000-06-30 00:00:00 -0.1041 1.093 0.1227 -0.2362 2000-09-29 00:00:00 -1.822 0.7325 -0.4964 -1.707 2000-12-29 00:00:00 0.3325 -0.2213 0.5465 1.265 2001 A B C D 2001-03-30 00:00:00 0.8422 -0.1265 0.1234 0.7743 2001-06-29 00:00:00 -0.07774 -0.3906 -0.6328 -1.259 2001-09-28 00:00:00 -0.3417 -0.4209 1.724 0.3069 2001-12-31 00:00:00 0.493 -0.2815 1.314 1.004 2002 A B C D 2002-03-29 00:00:00 1.003 -0.4807 0.7232 1.079 2002-06-28 00:00:00 0.1415 -2.275 0.6178 0.8817 2002-09-30 00:00:00 -0.6855 0.3921 -1.468 1.522 2002-12-31 00:00:00 -1.635 0.3083 0.1209 -0.5606 2003 A B C D 2003-03-31 00:00:00 0.5707 -0.7125 -0.07677 0.5154 2003-06-30 00:00:00 0.3646 -0.8574 -0.562 0.2176 2003-09-30 00:00:00 1.024 -0.8113 0.6771 -1.261
Or aggregate like so:
In [21]: grouped.aggregate(np.sum) Out[21]: A B C D 2000 -0.9629 0.1108 0.3811 -0.3405 2001 0.9159 -1.219 2.529 0.8268 2002 -1.176 -2.055 -0.006253 2.921 2003 1.959 -2.381 0.03838 -0.528
Or transform groups like so (here I standardize each group):
In [22]: zscore = lambda x: (x - x.mean()) / x.std() In [23]: transformed = grouped.transform(zscore) Out[23]: A B C D 2000-03-31 00:00:00 0.7946 -1.316 0.2598 0.3396 2000-06-30 00:00:00 0.1246 0.9216 0.06319 -0.1213 2000-09-29 00:00:00 -1.442 0.61 -1.361 -1.302 2000-12-29 00:00:00 0.5228 -0.2155 1.038 1.084 2001-03-30 00:00:00 1.142 1.34 -0.47 0.5569 2001-06-29 00:00:00 -0.571 -0.644 -1.168 -1.438 2001-09-28 00:00:00 -1.062 -0.8715 1.009 0.0983 2001-12-31 00:00:00 0.4917 0.1758 0.6299 0.7827 2002-03-29 00:00:00 1.149 0.02675 0.7159 0.3864 2002-06-28 00:00:00 0.3857 -1.422 0.6118 0.168 2002-09-30 00:00:00 -0.3469 0.7316 -1.449 0.878 2002-12-31 00:00:00 -1.188 0.664 0.1209 -1.432 2003-03-31 00:00:00 -0.2443 1.097 -0.1434 0.7267 2003-06-30 00:00:00 -0.8552 -0.8598 -0.9205 0.4138 2003-09-30 00:00:00 1.099 -0.2376 1.064 -1.14
Some aggregations are so common that they're provided as instance methods on the GroupBy object:
In [24]: grouped.sum()
Out[24]:
A B C D
2000 -0.9629 0.1108 0.3811 -0.3405
2001 0.9159 -1.219 2.529 0.8268
2002 -1.176 -2.055 -0.006253 2.921
2003 1.959 -2.381 0.03838 -0.528
In [25]: grouped.mean()
Out[25]:
A B C D
2000 -0.2407 0.02769 0.09526 -0.08512
2001 0.229 -0.3049 0.6324 0.2067
2002 -0.2939 -0.5138 -0.001563 0.7303
2003 0.6531 -0.7938 0.01279 -0.176
For those with SQL experience, a DataFrame can be treated like an SQL table. As such, grouping 'by columns" is quite natural:
In [27]: df2
Out[27]:
A B C D
0 foo one -0.7883 0.7743
1 bar one -0.5866 0.06009
2 foo two 0.9312 1.2
3 bar three -0.6417 0.3444
4 foo two -0.8841 -0.08126
5 bar two 1.194 -0.7933
6 foo one -1.624 -0.1403
7 foo three 0.5046 0.5833
In [28]: for name, group in df2.groupby('A'):
....: print name
....: print group
....:
bar
A B C D
1 bar one -0.5866 0.06009
3 bar three -0.6417 0.3444
5 bar two 1.194 -0.7933
foo
A B C D
0 foo one -0.7883 0.7743
2 foo two 0.9312 1.2
4 foo two -0.8841 -0.08126
6 foo one -1.624 -0.1403
7 foo three 0.5046 0.5833
Note the presence of the "nuisance" B column when we group by A. I want this to work:
In [30]: df2.groupby('A').mean() Out[30]: C D bar -0.01137 -0.1296 foo -0.3722 0.4671
More on dealing with this below.
New: Column selection
In my last post I mentioned wanting to be able to do a groupby-operation on a single column of a DataFrame using another column or set of columns as the groupers. So in the above example, what I want is:
grouped = df['C'].groupby(df['A']) # or grouped = df['C'].groupby([df['A'], df['B']])
This is too verbose / awkward for my tastes. So now you can do:
In [111]: df2.groupby('A')['C'].mean() Out[111]: bar -0.447919901908 foo -0.158016186685
Behind the scenes, this simply passes the C column to a Series GroupBy object along with the already-computed grouping(s).
New: Group by multiple columns / key functions
The ability to group by multiple criteria (just like SQL) has been one of my most desired GroupBy features for a long time. It's also very hard to implement efficiently. So I bit the bullet and carefully crafted Cython code to speedily do aggregations on data grouped by multiple columns. So now you can do:
In [113]: df2.groupby(['A', 'B']).mean() Out[113]: A B C D 0 foo one 0.3558 -0.4818 1 foo two -0.2758 -1.271 2 foo three -0.95 1.709 3 bar one 1.916 -0.5093 4 bar two -2.315 0.1177 5 bar three -0.9447 0.2519
Iteration with multiple groups flattens the key pairs:
In [114]: for k1, k2, group in df2.groupby(['A', 'B']): .....: print k1, k2 .....: print group .....: foo one A B C D 0 foo one 0.8248 0.3856 6 foo one -0.1133 -1.349 foo two A B C D 2 foo two -1.175 -1.036 4 foo two 0.6239 -1.506 foo three A B C D 7 foo three -0.95 1.709 bar one A B C D 1 bar one 1.916 -0.5093 bar two A B C D 5 bar two -2.315 0.1177 bar three A B C D 3 bar three -0.9447 0.2519
As a less trivial example, I loaded some data from the Bureau of Labor Statistics, which I'll write more about another time:
In [126]: df = read_table('ce.data.44.FinActOtherCurr.txt', sep='\s+', index_col=None) In [127]: df Out[127]: <class 'pandas.core.frame.DataFrame'> Index: 32806 entries, 0 to 32805 Data columns: series_id 32806 non-null values year 32806 non-null values period 32806 non-null values value 32806 non-null values dtypes: int64(1), float64(1), object(2) In [128]: df[:15] Out[128]: series_id year period value 0 CEU5500000034 1990 M01 83 1 CEU5500000034 1990 M02 83.6 2 CEU5500000034 1990 M03 83.4 3 CEU5500000034 1990 M04 84.9 4 CEU5500000034 1990 M05 84.1 5 CEU5500000034 1990 M06 85.4 6 CEU5500000034 1990 M07 86.5 7 CEU5500000034 1990 M08 86 8 CEU5500000034 1990 M09 85.5 9 CEU5500000034 1990 M10 83.6 10 CEU5500000034 1990 M11 83.6 11 CEU5500000034 1990 M12 84.7 12 CEU5500000034 1990 M13 84.5 13 CEU5500000034 1991 M01 82.9 14 CEU5500000034 1991 M02 83.1
This data set has 118 unique series_id's and spans 22 years (the period column gives the month of observation), so we're talking about 2596 unique groups. Let's say we wanted to compute the mean value for each year, it's pretty simple with the improved groupby:
In [129]: df.groupby(['series_id', 'year']).mean() Out[129]: <class 'pandas.core.frame.DataFrame'> Index: 2596 entries, 0 to 2595 Data columns: series_id 2596 non-null values value 2596 non-null values year 2596 non-null values dtypes: int64(1), float64(1), object(1)
I was also pretty impressed with how fast this operation is (the power of Cython!):
In [130]: timeit df.groupby(['series_id', 'year']).mean() 10 loops, best of 3: 22.9 ms per loop
I haven't compared this with an SQL engine (SQLite, MySQL, Postgres, ...) but I hope that it's competitive. If you call a non-Cythonized function, the speed goes down considerably:
In [132]: timeit df.groupby(['series_id', 'year'])['value'].std() 1 loops, best of 3: 232 ms per loop
Edit: It's also possible to pass multiple functions instead of column names or to mix and match column names with functions:
In [22]: df.groupby([lambda x: x.year, lambda x: x.month]).mean() Out[22]: A B C D key_0 key_1 0 0.09433 0.06146 0.1891 0.2079 2000 1 1 0.02674 -0.09411 0.1557 -0.07926 2000 2 2 0.07089 0.3938 -0.08026 -0.416 2000 3 3 0.133 -0.04532 0.03341 -0.2866 2000 4 4 0.1301 0.1803 -0.4241 0.1482 2000 5 5 -0.3804 -0.08935 0.04791 0.08268 2000 6 6 0.2211 0.2483 -0.3559 -0.06205 2000 7 7 -0.2908 0.07606 -0.2001 -0.05225 2000 8 8 -0.07888 -0.3915 0.06442 0.5109 2000 9 9 0.3809 0.4037 -0.2431 -0.2892 2000 10 10 -0.2765 0.01461 -0.2653 0.1335 2000 11 11 0.6983 -0.1167 0.3964 0.03776 2000 12 12 -0.2347 0.2333 -0.06508 0.3 2001 1 13 0.1751 0.05545 -0.004038 0.06194 2001 2 14 0.08792 0.03517 0.05583 -0.4356 2001 3 15 -0.08408 0.05567 -0.1705 0.1914 2001 4 16 0.008912 0.2317 0.08875 0.08637 2001 5 17 0.3304 0.3635 0.005158 0.3588 2001 6 18 -0.1324 0.3419 -0.2527 -0.2249 2001 7 19 0.0472 0.2552 -0.07589 -0.07992 2001 8 20 0.07582 -0.2295 0.1002 0.1077 2001 9 21 0.2368 0.02214 -0.3866 -0.2671 2001 10 22 0.2116 -0.07872 -0.06399 0.2309 2001 11
New: Omitting "nuisance" columns
It's pretty common to group by a column and ignore other columns containing non-floating point data. It used to be that you'd get an error, forcing you to first drop the "nuisance" columns, e.g. suppose we only want to group by the A column here:
In [133]: df2 Out[133]: A B C D 0 foo one 0.8248 0.3856 1 bar one 1.916 -0.5093 2 foo two -1.175 -1.036 3 bar three -0.9447 0.2519 4 foo two 0.6239 -1.506 5 bar two -2.315 0.1177 6 foo one -0.1133 -1.349 7 foo three -0.95 1.709
If you try to compute the mean of the B column, things won't quite work out:
In [134]: grouped = df2.groupby('A')['B'].mean() TypeError: unsupported operand type(s) for /: 'str' and 'float'
To cope with this, so-called "nuisance" columns are now automatically dropped. While I don't like discarding information, I think "practicality beats purity" in this case:
In [135]: df2.groupby('A').mean() Out[135]: C D bar -0.4479 -0.0466 foo -0.158 -0.3593
New: “auto-dispatching” to DataFrame / Series
Since very few functions in DataFrame and Series/TimeSeries are implemented on the GroupBy classes, you may wish to simply invoke a Series instance method on each group, let's say:
In [140]: df.groupby('series_id')['value'].agg(Series.skew) Out[140]: CEU5500000034 -0.253887792525 CEU5500000035 0.0938252241898 CEU5552200034 0.387563548587 CEU5552200035 0.0868489117242 CEU5552210034 0.74506367536 CEU5552210035 0.551290226183 <snip>
But since we're got Python at our disposal, it's relatively straightforward to override __getattribute__ to wrap and dispatch calls to Series/DataFrame instance methods so you can do this:
In [141]: df.groupby('series_id')['value'].skew()
Out[141]:
CEU5500000034 -0.253887792525
CEU5500000035 0.0938252241898
CEU5552200034 0.387563548587
CEU5552200035 0.0868489117242
CEU5552210034 0.74506367536
<snip>
Some of the more complicated methods, like the super-useful describe method can be used in fact:
In [142]: df.groupby('series_id')['value'].describe() Out[142]: count mean std min 10% 50% 90% max CEU5500000034 279 96.54 8.317 81.7 84 98.6 107.2 112 CEU5500000035 279 93.88 28.9 50.4 55.28 91.9 134.5 140.2 CEU5552200034 278 97.95 6.839 86.9 89.47 97.15 108.2 113.9 CEU5552200035 278 93.58 26.18 58 60.34 89.2 127.4 137.3 CEU5552210034 278 100.7 3.95 94.1 95.87 99.8 106 113.1 CEU5552210035 278 98.84 23.86 71.6 73.77 92.6 137.2 145.8 ...
For those interested, the internal code to do this dispatching is short and simple, by the way:
def __getattribute__(self, attr): try: return object.__getattribute__(self, attr) except AttributeError: if hasattr(self.obj, attr): return self._make_wrapper(attr) raise def _make_wrapper(self, name): f = getattr(self.obj, name) if not isinstance(f, types.MethodType): return self.aggregate(lambda self: getattr(self, name)) # return the class reference f = getattr(type(self.obj), name) def wrapper(*args, **kwargs): curried = lambda self: f(self, *args, **kwargs) return self.aggregate(curried) return wrapper
Old but not well known: apply multiple functions
This has always been around but not well-known by many people. Suppose you want to apply multiple functions to a group and collect all the results. You can pass a dict of functions:
In [144]: grouped.agg({'mean' : np.mean, 'variance' : np.var}) Out[144]: mean variance CEU5500000034 96.54 68.92 CEU5500000035 93.88 832.3 CEU5552200034 97.95 46.6 CEU5552200035 93.58 683.1 CEU5552210034 100.7 15.54 CEU5552210035 98.84 567.1 CEU5552211034 100.9 13.73 CEU5552211035 99.34 622 <snip>
I have a mind to expand on this idea for DataFrame objects to get us closer to the full flexibility of SQL with Pythonic syntax. If anyone has ideas or suggestions please let me know.
Conclusions
GroupBy is certainly not done. If you use these tools and find them useful, please let me know. If you can think of ways to make them better, that would be nice information too. I think it would be great to implement a full SQL engine on top of pandas (similar to the SAS "proc sql"), and this new GroupBy functionality gets us closer to that goal.