Registry / data / tsdownsample

tsdownsample

library0.1.5.1pypypi✓ verified 23d ago

tsdownsample is an extremely fast Python library for time series downsampling, leveraging Rust for its core implementation. It utilizes SIMD instructions and multithreading (via Rayon in Rust) to provide highly optimized, memory-efficient, and flexible algorithms for visualization and analysis of large time series datasets. The library is actively maintained, with its current version being 0.1.4.1.

data database

pip install tsdownsample

github ↗package ↗

INSTALL

IMPORT

SIG · TSDOWNSAMPLE

tsdownsample

datapythonv0.1.5.1

Install

4.7s avg

Import

244ms

Disk

99MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.5.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.240s · 99.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.7s · import 0.248s · 95MB

99MB installed

● package 99MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MinMaxLTTBDownsampler

✓ from tsdownsample import MinMaxLTTBDownsampler

LTTBDownsampler

✓ from tsdownsample import LTTBDownsampler

MinMaxDownsampler

✓ from tsdownsample import MinMaxDownsampler

And other downsamplers like EveryNthDownsampler, M4Downsampler, and their NaN-handling variants (e.g., NaNMinMaxDownsampler).

This quickstart demonstrates how to use `MinMaxLTTBDownsampler` to reduce a large time series dataset to a smaller, representative subset of points for visualization or analysis. It shows how to initialize a downsampler and use the `downsample` method with both `x` (optional time/index) and `y` (values) arrays, specifying the desired output size `n_out` and enabling parallel processing.

import numpy as np from tsdownsample import MinMaxLTTBDownsampler # Create a time series with x and y values x = np.arange(10_000_000, dtype=np.float64) y = np.random.randn(10_000_000).astype(np.float64) # Initialize the downsampler downsampler = MinMaxLTTBDownsampler() # Downsample the time series to 1000 points # The 'parallel=True' argument enables multi-threading for performance. # The 'n_out' argument is mandatory. selected_indices = downsampler.downsample(x, y, n_out=1000, parallel=True) # Retrieve the downsampled data points x_downsampled = x[selected_indices] y_downsampled = y[selected_indices] print(f"Original data points: {len(x)}") print(f"Downsampled data points: {len(x_downsampled)}") print(f"First 5 downsampled x: {x_downsampled[:5]}") print(f"First 5 downsampled y: {y_downsampled[:5]}")

Debug

Known issues

gotchaThe `x` (index) data must be non-strictly monotonic increasing (i.e., sorted) and should not contain NaN values. If not provided, it's assumed to be equally sampled without gaps.

fix

Ensure `x` arrays are sorted and free of NaNs before passing them to downsampling functions. The library offers specific `NaN...Downsampler` classes (e.g., `NaNMinMaxDownsampler`) for handling NaNs in `y` data.

affects: >=0.1.0

gotchaWhen `x` data contains gaps (i.e., non-equidistant sampling), the number of returned downsampled indices might be less than the specified `n_out`. This is because no data points can be selected for empty bins.

fix

Be aware that the actual output length may vary. If a fixed output length is critical, consider pre-processing or handling the output length post-downsampling.

affects: >=0.1.1

gotchaTo leverage multi-threading for performance, the `parallel=True` argument must be explicitly passed to the `downsample` method. The maximum number of threads can be configured via the `TSDOWNSAMPLE_MAX_THREADS` environment variable.

fix

Set `parallel=True` in your `downsample` calls. For fine-grained control, use `os.environ["TSDOWNSAMPLE_MAX_THREADS"] = "4"` before downsampling to limit or specify thread count.

affects: >=0.1.0

gotchaA precision error in the `sequential_add_mul` update logic was fixed in version 0.1.4.1. While a bug fix, users relying on the previous (incorrect) numerical behavior might observe different outputs after upgrading.

fix

Upgrade to version 0.1.4.1 or later to ensure correct numerical precision. If comparing results with older versions, be aware of potential minor numerical differences due to this fix.

affects: <0.1.4.1

gotchaThe `downsample` method's signature is `downsample(x, y, n_out=..., **kwargs)`. `x` and `y` are positional arguments, while `n_out` is a mandatory keyword argument.

fix

Always pass `n_out` as a keyword argument (e.g., `n_out=1000`) to avoid `TypeError`.

affects: >=0.1.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tsdownsample'

The 'tsdownsample' package is not installed in the Python environment.

fix

Install the package using 'pip install tsdownsample'.

ImportError: cannot import name 'MinMaxLTTBDownsampler' from 'tsdownsample'

The class 'MinMaxLTTBDownsampler' does not exist in the 'tsdownsample' module.

fix

Use 'from tsdownsample import MinMaxDownsampler' instead.

ValueError: x-data must be (non-strictly) monotonic increasing

The 'x' array provided to the downsampling function is not sorted in non-decreasing order.

fix

Ensure that the 'x' array is sorted before passing it to the downsampling function.

TypeError: downsample() missing 1 required positional argument: 'y'

The 'y' argument, representing the data to be downsampled, was not provided to the 'downsample' method.

fix

Provide the 'y' argument when calling the 'downsample' method, e.g., 'downsampler.downsample(y, n_out=1000)'.

AttributeError: module 'tsdownsample' has no attribute 'downsample'

Attempting to call 'downsample' directly from the 'tsdownsample' module, which does not have such an attribute.

fix

Instantiate a downsampler class and call its 'downsample' method, e.g., 'downsampler = MinMaxDownsampler(); downsampler.downsample(y, n_out=1000)'.

Upgrade

Version history

0.1.5.1latest on PyPI · released Jun 1, 2026

Audit

Dependencies

numpyrequiredUsed for input/output data arrays, fundamental for numerical operations.

Agent activity

21 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/predict-idlab/tsdownsample ↗

packagehttps://pypi.org/project/tsdownsample/ ↗