Plotly Resampler

0.11.0 · active · verified Tue Apr 14

Plotly-resampler is a Python library designed for visualizing large time series datasets efficiently with Plotly. It extends Plotly's capabilities by dynamically resampling data based on the zoom level, ensuring smooth performance even with millions of data points. The current version is 0.11.0, and the project maintains an active development pace with frequent releases.

Warnings

breaking The `check_nans` argument was removed from the `FigureResampler` constructor and its `add_traces` method. NaN handling is now delegated entirely to the specific aggregators via their `nan_policy` argument.
Fix: Remove `check_nans` from your calls. Configure NaN handling via the `nan_policy` argument of your chosen aggregator (e.g., `MinMax(nan_policy='drop')`).
breaking The default aggregation backend was switched from a custom C implementation (and previously `lttbc`) to `tsdownsample`. This significantly changed the underlying resampling logic and dependencies.
Fix: Ensure `tsdownsample` is installed. Review custom aggregation logic if you were relying on internal details of previous backends. Most users will benefit from improved performance and reduced compilation issues.
gotcha The `register_plotly_resampler()` class method was introduced, allowing dynamic resampling to be applied automatically to all `plotly.graph_objects.Figure` instances globally. This changes the typical usage pattern from explicitly wrapping figures to a more 'set-and-forget' approach.
Fix: Decide whether to explicitly instantiate `FigureResampler` or use `FigureResampler.register_plotly_resampler()` at the start of your script/application for global effect. Be aware that global registration affects all `go.Figure` objects.
gotcha Optional dependencies `kaleido` (for static image export) and `flask-cors` (for web app integration) are no longer installed by default. If you need these functionalities, you must install them explicitly.
Fix: To get these dependencies, use `pip install plotly-resampler[full]` or `pip install 'plotly-resampler[kaleido]'` / `pip install 'plotly-resampler[flask-dash]'` as needed.

Install

pip install plotly-resampler Install core library
pip install plotly-resampler[full] Install with all optional dependencies

Imports

FigureResampler

from plotly_resampler import FigureResampler

FigureResampler.register_plotly_resampler
```
from plotly_resampler import FigureResampler
# ... later ...
FigureResampler.register_plotly_resampler()
```
Globally registers Plotly-Resampler for all plotly.graph_objects.Figure instances. Available since v0.7.0.

Quickstart

This quickstart demonstrates how to create a `FigureResampler` instance to visualize a large time series dataset. It wraps a standard `plotly.graph_objects.Figure` and uses the `add_trace` method with `hf_x` and `hf_y` arguments to enable dynamic resampling.

import pandas as pd
import numpy as np
from plotly_resampler import FigureResampler
import plotly.graph_objects as go

# Create some large time series data
n_points = 1_000_000
time_index = pd.date_range("2020-01-01", periods=n_points, freq="S")
data_y = np.cumsum(np.random.randn(n_points))

# Initialize FigureResampler, wrapping a Plotly figure
fig = FigureResampler(go.Figure())

# Add a trace with resampling enabled by providing hf_x and hf_y
fig.add_trace(go.Scattergl(name='High-Frequency Data'), hf_x=time_index, hf_y=data_y)

# Show the figure (opens in browser or displays in compatible environments)
fig.show()

view raw JSON →