tsfresh-rs

Fast, drop-in time series feature extraction for Python, powered by Rust.

- import tsfresh
+ import tsfresh_rs as tsfresh

That is the whole migration. Same functions, same arguments, same 783 feature columns, same column names in the same order — verified by 478 tests that run both libraries on the same input and compare every value, including which inputs each one refuses.

pip install tsfresh-rs

Supports Python 3.10 through 3.14 from a single abi3 wheel per platform.

Why it is faster

tsfresh has two separate performance problems, and fixing only the obvious one gets you a fraction of the win.

The obvious one is that the calculators are slow. approximate_entropy materialises an (N−m+1)²×m boolean array to count Chebyshev neighbours; lempel_ziv_complexity hashes a fresh Python tuple for every substring probe; sample_entropy builds full distance matrices. Rewriting those in Rust is worth about 17x.

The less obvious one is everything around them. Per series and per feature, the reference pays a Python function call, a pandas groupby/apply step, and the assembly of a wide DataFrame from hundreds of small pieces. That cost does not shrink when the calculators get faster — and on a comprehensive extraction it is most of the wall clock.

So this package does not call calculators one at a time. It flattens every series into one contiguous float64 buffer, compiles the whole feature plan once, and makes a single call into Rust that fills the entire output matrix with the GIL released and Rayon over series.

Owning the loop is what turns 17x into 120x.

Benchmarks

AMD Ryzen 5 5600G (6 cores / 12 threads), Python 3.14, tsfresh 0.21.2, pandas 3.0.5. Every row was checked for agreement before it was timed, so a fast wrong answer cannot appear in these tables. python bench/bench.py reproduces them.

End to end, ComprehensiveFCParameters (783 columns per series)

The reference costs about 290 ms per series on the 500-point workload. That is the number behind issue #973 — open since 2022 — where users report 3-hour and 16-hour waits and a maintainer replies that he lacks the bandwidth to fix it.

The preset that exists to avoid the cost

EfficientFCParameters drops approximate_entropy and sample_entropy because they are 62% of a comprehensive run. Here you do not have to choose:

The full feature set here is 40x faster than the reduced one there.

Longer series

4 series, tsfresh serial against tsfresh-rs on all cores — only four series means threading has little to work with, which is why these ratios are the lowest in this README rather than the highest:

Per calculator

20 series × 500 points, single-threaded, the twelve most expensive in the reference:

All 74 agree with the reference to within 1e-9 relative on this data — the benchmark checks each one before it times it, so a fast wrong answer cannot reach this table.

The gap between this table's 17x and the end-to-end 120x is the whole argument of the section above: most of a comprehensive extraction is not the features.

n_jobs

tsfresh parallelises with processes, so every chunk is pickled and every worker re-imports the library. Below a few dozen series that costs more than it saves:

On 20 series, asking tsfresh for six processes makes it slower than running serially; on 100 series, asking for every core makes it slower than asking for six. This package uses threads inside one process: nothing is pickled, there is no if __name__ == "__main__" requirement, threading pays off at every size, and the output is bit-identical whatever you pass.

One deliberate difference: n_jobs=0 means one thread per core here, where the reference means no parallelism at all. With threads there is nothing to trade off, so the default should be the fast one. Pass n_jobs=1 for a genuinely single-threaded run.

What it adds: feature_timings

EfficientFCParameters is a guess — a judgement the maintainers made once, on their data, about which features are expensive. On a 500-point series those two features really are 62% of the run. On a 50-point series they are nearly free. On a 20,000-point series something else dominates entirely.

feature_timings measures it on your data:

import tsfresh_rs as tsfresh

timings = tsfresh.feature_timings(df, column_id="id", column_sort="time")
print(timings.head(6)[["feature", "columns", "seconds", "pct_of_total"]])
#                 feature  columns   seconds  pct_of_total
#     approximate_entropy        5  0.139937     60.287962
# augmented_dickey_fuller        3  0.032445     13.977916
#          sample_entropy        1  0.018846      8.119415
#        change_quantiles       60  0.007768      3.346718
#        number_cwt_peaks        2  0.007093      3.055826
#          ar_coefficient       11  0.006635      2.858552

The shares are exhaustive — all 74 features, summing to 100% — so nothing is hiding outside the report.

and drop_slowest turns that into a feature set:

from tsfresh_rs.profiling import drop_slowest

cheap = drop_slowest(tsfresh.ComprehensiveFCParameters(), timings, budget_pct=90)
X = tsfresh.extract_features(df, default_fc_parameters=cheap, ...)

tsfresh has no equivalent. The question "which of these 783 columns am I paying for?" currently has no answer other than deleting features and re-timing by hand.

Accuracy

Prefix-summing and compensating is where the speed comes from, and it is also where a careless port silently disagrees. Three places where this package is measurably more accurate than the reference, each pinned by a test against exact arithmetic rather than against tsfresh:

Fourier coefficients on offset data. A signal with a large DC offset makes every non-DC coefficient a difference of large, nearly-cancelling terms. The DFT is linear, so this package transforms the mean-centred signal and restores bin 0 exactly — mathematically identical, far better conditioned. Judged against a 50-digit exact DFT on a signal offset by 1e6:

Variance and sums. Neumaier-compensated accumulation, and a double-double mean in every regression, so that deviations survive on a series whose spread is twelve orders of magnitude below its level.

Histogram binning. binned_entropy on a near-constant series — values around 5.0 spanning 0.01 — bins correctly here. The naive floor((v − lo) / width) that looks equivalent to NumPy's index computation loses the whole signal to cancellation; matching NumPy's scale-then-correct algorithm was worth a 25% difference in the entropy.

A scale-invariant Dickey-Fuller statistic. Multiplying a series by a constant cannot change whether it has a unit root, so the ADF test statistic is invariant by construction. The reference's is not, because its design matrix pairs a constant column of 1.0 with level and difference columns that shrink with the data and statsmodels factorises that without equilibrating. Rescaling a series to 1e-9 moves its answer:

Each column is normalised before the factorisation here, which is the standard fix and costs nothing.

Dependency footprint

tsfresh imports scipy, statsmodels, scikit-learn, pywt, stumpy, dask, distributed, tqdm, cloudpickle and matplotlib to compute its features. The numerics those provide are reimplemented here in Rust — pywt's Mexican-hat CWT, SciPy's Welch PSD and ridge-line peak finder, statsmodels' AutoReg, acf, pacf and the ADF test with MacKinnon p-values — so extraction itself loads numpy and pandas, and nothing else:

>>> import tsfresh_rs, sys
>>> tsfresh_rs.extract_features(df, column_id="id", column_sort="time")
>>> [m for m in sys.modules if m.split(".")[0] in ("scipy", "statsmodels",
...                                                "sklearn", "pywt", "stumpy")]
[]

scipy is still declared as a dependency because select_features needs its hypothesis tests, but it is imported lazily and never touched by extraction.

Correctness

The package is only worth anything if the answers match, so that is what the suite tests.

• 478 tests, almost all differential against tsfresh on the same input.
• 250 randomised fuzz cases over length, scale, offset, tie density and degeneracy, comparing every calculator value by value; plus 40 fuzzed end-to-end pipelines. This found four real defects during development, including a wrong Mexican-hat amplitude that scaled all 60 cwt_coefficients columns by 1.3025 — a uniform error that looks entirely plausible in isolation.
• API coverage is asserted mechanically: every calculator in dir(tsfresh...feature_calculators) must exist here with the same fctype, minimal, high_comp_cost, input and index_type attributes, because those attributes are what define the presets.
• All five presets must select exactly the same features with exactly the same parameters.
• Whole-frame equality across all four input shapes — long with a kind column, long without, wide, and a dict of frames — including column order and index.

Reference quirks are reproduced deliberately, not accidentally. fft_aggregated's kurtosis has a - 3 * centroid term where the standardised fourth moment wants 3 * centroid⁴; ComprehensiveFCParameters builds mean_n_absolute_max from a dict literal with three copies of the same key, so two of its three intended features have never existed. Both are matched bug-for-bug, because a drop-in that quietly "fixes" a feature changes numbers people have already trained on.

Where it deliberately differs

Each documented in tests/test_equivalence.py::KNOWN_DIVERGENCES with a test asserting the divergence is still real.

• fft_coefficient(attr="angle") on a constant series. Every non-DC coefficient is zero, so its argument is undefined. The reference reports the argument of its own rounding noise; this reports 0.
• fft_coefficient on a series containing an infinity. An infinity has no Fourier transform. Both libraries propagate it through their own FFT decomposition, and which bins emerge as NaN and which as infinite is an artefact of the radix each chose — NumPy's pocketfft yields 38 NaN and 3 infinities where this package yields 34 and 7. Neither pattern carries information.
• linear_trend and friends on a constant series. The correlation of a constant is undefined and this returns NaN. The reference returns NaN for a constant 2.5 and 0.0 for a constant 0.001 — the difference being whether np.cov's mean happens to be exactly representable, which leaves a spurious 4.7 × 10⁻³⁸ variance in one case and not the other.
• Conditioning-limited fits — friedrich_coefficients, max_langevin_fixed_point, ar_coefficient, cwt_coefficients on a signal offset by 1e6. Both implementations solve a numerically rank-deficient problem; the coefficients differ in the 4th digit while the residuals they describe agree to 10.

Below a relative spread of about 1e-4, standardised statistics are not reproducible between any two implementations: the deviations being standardised are themselves rounding error. Measured against 60-digit arithmetic on the cases the fuzzer found, this package is closer to the true value in 4 of 6 and SciPy in 2 of 6. Neither is authoritative there.

A note on reference versions

Three tsfresh feature values are not decided by tsfresh. They are decided by whichever SciPy, NumPy and PyWavelets are installed next to it, and those libraries have changed their answers. Running the differential suite across three operating systems and three Python versions surfaced all three:

Each was confirmed by reproducing the older environment and matching its value exactly — pywt.cwt(..., precision=10) returns the old figure to the last digit, and pandas 2.3.3's qcut reproduces the old cubic. The permutation_entropy entry is the starkest of the four: it is not a version difference at all but a CPU difference, and there is no value this package could pick that would agree with the reference everywhere. It uses the stable order, which is at least the same everywhere.

This package computes all three in Rust, so it gives one fixed answer wherever it runs. It targets the current behaviour: PyWavelets ≥ 1.9's precision-12 grid, pandas ≥ 3.0's NumPy-consistent binning, and SciPy ≥ 1.16's NaN for an undefined correlation. On an older reference those specific columns will differ — which is a statement about the reference's environment, not about this package.

The test suite probes the installed reference at runtime and skips exactly those comparisons when it detects an older behaviour, rather than pinning dependency versions. Pinning would hide the effect; users do not pin.

Coverage

Everything in tsfresh 0.21.2:

For code you cannot edit

When a dependency deep in the stack imports tsfresh by name:

import tsfresh_rs
tsfresh_rs.install()   # before anything imports `tsfresh`

import tsfresh         # this is now tsfresh_rs

It refuses rather than half-patching the module graph if the real tsfresh has already been imported.

Limitations

Stated plainly, because a drop-in that hides its gaps is worse than one that does not have them.

• matrix_profile is unavailable, exactly as in the reference. The matrixprofile package is unmaintained and does not build on current Python, so tsfresh ships with this feature disabled and excluded from ComprehensiveFCParameters. This mirrors that, including the ImportError.
• select_features is not accelerated. It is linear in the number of features with one cheap hypothesis test each — not the bottleneck this package exists to fix — so it runs in Python. n_jobs and chunksize are accepted and ignored there.
• chunksize, distributor and the profile* arguments describe tsfresh's multiprocessing pipeline, which this implementation does not have. They are accepted for signature compatibility and ignored, with a warning. The utilities.distribution classes exist so that code importing them keeps working, but extract_features does not route through them.
• tsfresh.__version__ reports this package's version after install(), not a tsfresh one, so code gating on tsfresh.__version__ >= "0.20" will take the wrong branch. Claiming to be 0.21.2 would fix that one check and lie to every other; the API level being emulated is published separately as tsfresh_rs.__tsfresh_version__.
• profile=True no longer answers "which calculator is slow". A cProfile trace of an extraction here shows one opaque call into Rust. feature_timings is the replacement, and it measures what the profiler used to.
• augmented_dickey_fuller is only 4x faster. Its cost is a lag-selection search over many OLS fits, and the reference already spends that time inside compiled LAPACK.

Development

pip install maturin pytest numpy pandas scipy tsfresh mpmath statsmodels
maturin build --release --out dist && pip install --no-index --find-links dist tsfresh-rs
pytest tests/ -q
python bench/bench.py

To reproduce the older-reference environment the version table describes — the one where three feature columns legitimately differ — and check that the suite skips exactly those:

uv venv --python 3.10 /tmp/old && uv pip install --python /tmp/old/bin/python     pytest numpy pandas scipy tsfresh mpmath statsmodels
uv pip install --python /tmp/old/bin/python --no-deps --find-links dist tsfresh-rs
/tmp/old/bin/python -m pytest tests/ -q -rs

That resolves to numpy 2.2, pandas 2.3, SciPy 1.15 and PyWavelets 1.8, and gives 411 passed, 3 skipped.

Licence and credit

MIT, the same licence as tsfresh.

This is a reimplementation of tsfresh by Maximilian Christ and Blue Yonder GmbH, whose API, feature definitions and output semantics it deliberately reproduces. If you use this in research, cite their paper:

Christ, M., Braun, N., Neuffer, J. and Kempa-Liehr A.W. (2018). Time Series FeatuRe Extraction on basis of Scalable Hypothesis tests (tsfresh — A Python package). Neurocomputing 307 (2018) 72-77.