parallel-pandas 0.8

Parallel-pandas

Makes it easy to parallelize your calculations in pandas on all your CPUs.

Installation

pip install --upgrade parallel-pandas

Quickstart

import pandas as pd
import numpy as np
from parallel_pandas import ParallelPandas

#initialize parallel-pandas
ParallelPandas.initialize(n_cpu=16, split_factor=4, disable_pr_bar=True)

# create big DataFrame
df = pd.DataFrame(np.random.random((1_000_000, 100)))

# calculate multiple quantiles. Pandas only uses one core of CPU
%%timeit
res = df.quantile(q=[.25, .5, .95], axis=1)

3.66 s ± 31.6 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

#p_quantile is parallel analogue of quantile methods. Can use all cores of your CPU.
%%timeit
res = df.p_quantile(q=[.25, .5, .95], axis=1)

679 ms ± 10.4 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

As you can see the p_quantile method is 5 times faster!

The .parallel accessor

Every p_* method is also reachable through the .parallel accessor, so you can drop the prefix and write the call the way you would spell the pandas method:

df.parallel.quantile(q=[.25, .5, .95], axis=1)   # same as df.p_quantile(...)
df.parallel.mean()                                # same as df.p_mean()
df.parallel.apply(my_func, axis=1)                # same as df.p_apply(my_func, axis=1)

The accessor simply forwards df.parallel.<name>() to df.p_<name>(), so it automatically exposes whatever ParallelPandas.initialize registered.

Parallel .str and .dt

On a Series the .parallel namespace also exposes the string and datetime accessors, so element-wise text/date preprocessing runs across a worker pool. The API mirrors pandas exactly — methods return a callable, accessor properties (dt.year, dt.month, ...) are evaluated eagerly:

s.parallel.str.lower()
s.parallel.str.extract(r'(\d+)-(\w+)')      # returns a DataFrame, like pandas
s.parallel.str.replace('foo', 'bar', regex=False)

s.parallel.dt.year                          # property -> Series
s.parallel.dt.floor('D')
s.parallel.dt.strftime('%Y-%m-%d')

Each op is element-wise, so the Series is split into row-chunks, the real pandas accessor runs on every chunk and the results are concatenated — the output is identical to the serial version.

When it pays off: reach for it on CPU-heavy per-element ops (regex extract/replace, strftime, custom-format parsing). The built-in light ops (str.upper, str.contains, dt.year, ...) already run in vectorized C, and shipping millions of Python strings to worker processes costs more than the op itself, so the serial version is faster there. On a 5M-row string Series str.extract with a regex is ~3.5x faster; str.upper is slower. Series shorter than the worker count fall back to the serial call automatically.

Usage

Under the hood, parallel-pandas works very simply. The Dataframe or Series is split into chunks along the first or second axis. Then these chunks are passed to a pool of processes or threads where the desired method is executed on each part. At the end, the parts are concatenated to get the final result.

When initializing parallel-pandas you can specify the following options:

1. n_cpu - the number of cores of your CPU that you want to use (default None - use all cores of CPU)
2. split_factor - Affects the number of chunks into which the DataFrame/Series is split according to the formula chunks_number = split_factor*n_cpu. Default is None, which enables automatic chunking: for the process-transport methods (p_apply, p_map, p_applymap, chunk_apply) the chunk count is picked from the input's byte size (aiming for ~8 MB per chunk, bounded between n_cpu and 64*n_cpu chunks). This lets the data transfer to workers overlap with computation and noticeably speeds up large frames (e.g. ~1.9 GB frame: ~1.9x in local benchmarks). Pass an explicit integer (e.g. split_factor=4) to force the classic split_factor*n_cpu number of chunks instead.
3. show_vmem - Shows a progress bar with available RAM (default False)
4. disable_pr_bar - Disable the progress bar for parallel tasks (default False)
5. logger - A logging.Logger the progress bar is redirected to instead of the terminal (default None). Optionally set the level with logger_level (default logging.INFO). To write the bar to an arbitrary file-like object instead, pass pbar_file.
6. reuse_pool - Keep the worker pool warm and reuse it across calls instead of spawning a new one every time (default True). This removes the per-call process-spawn overhead, which makes a big difference when you call process-based methods (p_apply, p_map, chunk_apply, p_pivot_table, groupby p_apply, ...) repeatedly. Set it to False to restore per-call pool creation.

For example

import pandas as pd
import numpy as np
from parallel_pandas import ParallelPandas

#initialize parallel-pandas
ParallelPandas.initialize(n_cpu=16, split_factor=4, disable_pr_bar=False)

# create big DataFrame
df = pd.DataFrame(np.random.random((1_000_000, 100)))

During initialization, we specified split_factor=4 and n_cpu = 16, so the DataFrame will be split into 64 chunks (in the case of the describe method, axis = 1) and the progress bar shows the progress for each chunk

Redirecting the progress bar to a logger

By default the progress bar is written to the terminal. In non-interactive environments (log files, JSON logs, schedulers) you can redirect it to a logging.Logger — each bar refresh is emitted as a log record:

import logging
from parallel_pandas import ParallelPandas

logging.basicConfig(filename="progress.log", level=logging.INFO)
ParallelPandas.initialize(logger=logging.getLogger("pp"))
# df.p_apply(...) now writes the bar into progress.log instead of the terminal

You can parallelize any expression with pandas Dataframe. For example, let's do a z-score normalization of columns in a dataframe. Let's look at the execution time and memory consumption. Compare with synchronous execution and with Dask.DataFrame

import pandas as pd
import numpy as np
from parallel_pandas import ParallelPandas
import dask.dataframe as dd
from time import monotonic

#initialize parallel-pandas
ParallelPandas.initialize(n_cpu=16, split_factor=8, disable_pr_bar=True)

# create big DataFrame
df = pd.DataFrame(np.random.random((1_000_000, 1000)))

# create dask DataFrame
ddf = dd.from_pandas(df, npartitions=128)

start = monotonic()
res=(df-df.mean())/df.std()
print(f'synchronous z-score normalization time took: {monotonic()-start:.1f} s.')

synchronous z-score normalization time took: 21.7 s.

#parallel-pandas
start = monotonic()
res=(df-df.p_mean())/df.p_std()
print(f'parallel z-score normalization time took: {monotonic()-start:.1f} s.')

parallel z-score normalization time took: 11.7 s.

#dask dataframe
start = monotonic()
res=((ddf-ddf.mean())/ddf.std()).compute()
print(f'dask parallel z-score normalization time took: {monotonic()-start:.1f} s.')

dask parallel z-score normalization time took: 12.5 s.

Pay attention to memory consumption. parallel-pandas and dask use almost half as much RAM as pandas

For some methods parallel-pandas is faster than dask.DataFrame:

#dask
%%time
res = ddf.nunique().compute()
Wall time: 42.9 s

%%time
res = ddf.rolling(10).mean().compute()
Wall time: 19.1 s

#parallel-pandas
%%time
res = df.p_nunique()
Wall time: 12.9 s

%%time
res = df.rolling(10).p_mean()
Wall time: 12.5 s

Parallel groupby.transform

Group-wise feature engineering with a Python UDF is a classic CPU-bound workload. p_transform splits the groups across a worker pool and runs the real pandas transform on every chunk, so the result is identical to groupby.transform (column fast-path, broadcasting and string aggregations are all handled by pandas):

def robust_zscore(s):
    med = s.median()
    mad = (s - med).abs().median()
    return (s - med) / (mad + 1e-9)

# drop-in parallel replacement for df.groupby('user_id')[cols].transform(robust_zscore)
feats = df.groupby('user_id')[['x', 'y']].p_transform(robust_zscore)

On a 2M-row frame with 20k groups and a heavy UDF this runs ~5x faster than the serial transform on an 8-core machine. As with the other process methods, reach for it when the UDF is an expensive Python function; for the built-in aggregations ('mean', 'sum', ...) the native transform already runs in C.

p_agg is the reducing counterpart and mirrors groupby.agg, so callable, string, list, dict and named aggregations all work (the aggregation spec and resulting column layout are handled by pandas):

gb = df.groupby('user_id')
gb.p_agg(lambda s: s.max() - s.min())          # callable
gb.p_agg({'x': 'mean', 'y': my_udf})           # dict spec
gb.p_agg(rng=('x', my_udf), total=('y', 'sum'))  # named aggregation

API

Parallel counterparts for pandas Series methods

Parallel counterparts for pandas SeriesGroupBy methods

Parallel counterparts for pandas Dataframe methods

Parallel counterparts for pandas DataframeGroupBy methods

Parallel counterparts for pandas window methods

Rolling

Window

RollingGroupby

Expanding

ExpandingGroupby

ExponentialMovingWindow

ExponentialMovingWindowGroupby