Key features

siuba dplython pandas
Column operations are pandas Series methods
Table verbs supports user defined functions
pipe syntax (>>)
concise, lazy expressions (_.a + _.b)
No more reset_index
unified API over (un)grouped data
generate fast grouped operations

generate SQL queries
Abstract syntax trees for
transforming operations
handles nested data ⚠️

Built on pandas

pandas is everywhere in python data analysis. The siuba library builds on this incredible work by using pandas Series methods as its reference implementation. This means that you use the pandas methods you’ve already learned!

import pandas as pd
from siuba import _, mutate

my_data = pd.DataFrame({
    'g': ['a', 'a', 'b'],
    'x': [1,2,3],
})

# pandas
my_data.assign(avg = lambda d: d.x.mean())

# siuba
mutate(my_data, avg = _.x.mean())
g x avg
0 a 1 2.0
1 a 2 2.0
2 b 3 2.0

Note how you can debug both pieces of code by running and inspecting df.a.mean().

While pandas is an incredibly powerful API, its syntax can get quite cumbersome.

(my_data
  .assign(avg = lambda d: d.x.mean())    # create new column
  .loc[lambda d: d.x != 3]               # filter out some rows
)
g x avg
0 a 1 2.0
1 a 2 2.0

Notice how much of this code is writing the word lambda.

Like other ports of the popular R library, dplyr–such as dplython–siuba offers a simple, flexible way to work on tables of data.

Pipe syntax

The pipe syntax allows you to import table functions (verbs), rather than having 300+ methods on your DataFrame.

# actions can be imported individually
from siuba import mutate, arrange

# they can be combined using a pipe
my_data >> mutate(y = _.x + 1) >> arrange(_.g, -_.x)
g x y
1 a 2 3
0 a 1 2
2 b 3 4

Lazy expressions

Using lazy expressions saves you from repeating the name of your DataFrame over and over.

# rather than repeat the name of your data, you can use lazy expressions ---
my_data_frame = pd.DataFrame({'a': [1,2,3]})


# bad
my_data_frame["b"] = my_data_frame["a"] + 1
my_data_frame["c"] = my_data_frame["b"] + 2

# good
my_data_frame >> mutate(b = _.a + 1, c = _.b + 2)
a b c
0 1 2 4
1 2 3 5
2 3 4 6

No reset_index

Notice how siuba mutate can take a DataFrame, and return a DataFrame. Moreover, it doesn’t stick columns onto the index. This means you don’t need to call reset_index all the time.

A common place where reset_index is called is after a pandas grouped aggregation.

from siuba.data import mtcars
from siuba import summarize

g_cyl = mtcars.groupby("cyl")

agg_res = g_cyl[["hp", "mpg"]].agg("mean")
agg_res
hp mpg
cyl
4 82.636364 26.663636
6 122.285714 19.742857
8 209.214286 15.100000
# bad
agg_res.reset_index()
cyl hp mpg
0 4 82.636364 26.663636
1 6 122.285714 19.742857
2 8 209.214286 15.100000
# good
summarize(g_cyl, hp = _.hp.mean(), mpg = _.mpg.mean())
cyl hp mpg
0 4 82.636364 26.663636
1 6 122.285714 19.742857
2 8 209.214286 15.100000

Unified (un)grouped API

In siuba it doesn’t matter whether your data is grouped or not.

g_cyl = mtcars.groupby("cyl")

mtcars >> mutate(demeaned = _.hp - _.hp.mean())    # uses ungrouped mean
g_cyl  >> mutate(demeaned = _.hp - _.hp.mean())    # uses grouped mean

(grouped data frame)

mpg cyl disp hp drat wt qsec vs am gear carb demeaned
0 21.0 6 160.0 110 3.90 2.620 16.46 0 1 4 4 -12.285714
1 21.0 6 160.0 110 3.90 2.875 17.02 0 1 4 4 -12.285714
... ... ... ... ... ... ... ... ... ... ... ... ...
30 15.0 8 301.0 335 3.54 3.570 14.60 0 1 5 8 125.785714
31 21.4 4 121.0 109 4.11 2.780 18.60 1 1 4 2 26.363636

32 rows × 12 columns

In pandas you have to change your code for grouped data.

g_cyl = mtcars.groupby("cyl")

# ungrouped vs grouped mean
mtcars.assign(demeaned = lambda d: d.hp - d.hp.mean())
mtcars.assign(demeaned = g_cyl.obj.hp - g_cyl.hp.transform("mean"))
mpg cyl disp hp drat wt qsec vs am gear carb demeaned
0 21.0 6 160.0 110 3.90 2.620 16.46 0 1 4 4 -12.285714
1 21.0 6 160.0 110 3.90 2.875 17.02 0 1 4 4 -12.285714
... ... ... ... ... ... ... ... ... ... ... ... ...
30 15.0 8 301.0 335 3.54 3.570 14.60 0 1 5 8 125.785714
31 21.4 4 121.0 109 4.11 2.780 18.60 1 1 4 2 26.363636

32 rows × 12 columns

Note that g_cyl does not have an assign method, and requires passing what operation you want to do ("mean") as a string to .transform().

Fast and flexible

Fast grouped operations

Consider some data (students) where 2,000 students have each completed 10 courses, and received a score on each course.

# fast grouped operations (pull from dev docs)
# PLOT of timing
import numpy as np
import pandas as pd

np.random.seed(123)
students = pd.DataFrame({
    'student_id': np.repeat(np.arange(2000), 10),
    'course_id': np.random.randint(1, 20, 20000),
    'score': np.random.randint(1, 100, 20000)
})
g_students = students.groupby('student_id')
g_students

(grouped data frame)

student_id course_id score
0 0 14 38
1 0 3 40
... ... ... ...
19998 1999 11 32
19999 1999 17 10

20000 rows × 3 columns

Suppose that we want to get the courses each student scored lowest on.

In pandas we could use some complex, but fast code.

%%time
# pandas
is_student_min = g_students.obj.score == g_students.score.transform('min')
low_scores = students[is_student_min]
CPU times: user 1.14 ms, sys: 300 µs, total: 1.44 ms
Wall time: 1.37 ms

In siuba it is simpler, and comparable in speed.

from siuba.experimental.pd_groups import fast_filter
%%time
# siuba
low_scores = fast_filter(g_students, _.score == _.score.min())
CPU times: user 1.76 ms, sys: 199 µs, total: 1.96 ms
Wall time: 1.81 ms

This is because siuba’s lazy expressions let it optimize grouped operations.

However, dplython is over 100x slower in this case, because it uses the slower pandas DataFrame.apply() method under the hood.

# set up code for timing
from dplython import X, DplyFrame, sift, group_by as dply_group_by

g_students2 = DplyFrame(students) >> dply_group_by(X.student_id)
%%time
g_students2 >> sift(X.score == X.score.min())
CPU times: user 149 ms, sys: 1.23 ms, total: 150 ms
Wall time: 150 ms
student_id course_id score
2 0 3 17
10 1 10 1
... ... ... ...
19987 1998 17 31
19997 1999 3 1

2117 rows × 3 columns

SQL queries

# generate SQL queries
from siuba.data import cars_sql
from siuba import group_by, mutate, show_query

q = (cars_sql
  >> group_by("cyl")
  >> mutate(demeaned = _.hp - _.hp.mean())
  >> show_query()
)
SELECT cars.cyl, cars.mpg, cars.hp, cars.hp - avg(cars.hp) OVER (PARTITION BY cars.cyl) AS demeaned 
FROM cars

Abstract syntax trees

This is made possible because siuba represents lazy expressions with abstract syntax trees. Fast grouped operations and SQL queries are just the beginning. This allows people to produce a whole range of interesting tools!

Siuba’s lazy expressions consist of a Symbolic and Call class.

Symbolic is used to quickly create lazy expressions.

# ASTs for transforming
from siuba.siu import Symbolic, Call, strip_symbolic

_ = Symbolic()

sym = _.a.mean() + _["b"]
sym
█─+
├─█─'__call__'
│ └─█─.
│   ├─█─.
│   │ ├─_
│   │ └─'a'
│   └─'mean'
└─█─[
  ├─_
  └─█─'__siu_slice__'
    └─'b'

Each black box in the printout above is a Call. Calls are the pieces that represent the underlying operations. They have methods to inspect and transform them.

call = strip_symbolic(sym)

# get columns names used in lazy expression
call.op_vars(attr_calls = False)
{'a'}

Nested data

from siuba import _, mutate, unnest

tagged = pd.DataFrame({
    'id': [1,2,3],
    'tags': ['a,b,c', 'd,e', 'f']
})

(tagged
    >> mutate(split_tags = _.tags.str.split(','))
    >> unnest("split_tags")
)
id tags split_tags
0 1 a,b,c a
1 1 a,b,c b
... ... ... ...
4 2 d,e e
5 3 f f

6 rows × 3 columns

Learning more