High-Performance Time Series Downsampling

Warnings

• gotcha The `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.
• gotcha When `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.
• gotcha To 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.
• gotcha A 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.
• gotcha The `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`.

Install

• pip install tsdownsample Install with pip

Imports

• 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).

Quickstart

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]}")