plotly-resampler: A Python repository from bbradbury

plotly_resampler: visualize large sequential data by adding resampling functionality to Plotly figures

Plotly is an awesome interactive visualization library, however it can get pretty slow when a lot of data points are visualized (100 000+ datapoints). This library solves this by downsampling (aggregating) the data respective to the view and then plotting the aggregated points. When you interact with the plot (panning, zooming, ...), callbacks are used to aggregate data and update the figure.

In this Plotly-Resampler demo over 110,000,000 data points are visualized!

Installation

pip	`pip install plotly-resampler`

Usage

To add dynamic resampling to your plotly Figure

using a web application with Dash callbacks, you should;
1. wrap the plotly Figure with FigureResampler
2. call .show_dash() on the Figure
within a jupyter environment and without creating a web application, you should:
1. wrap the plotly Figure with FigureWidgetResampler
2. output the FigureWidgetResampler instance in a cell

Note:
Any plotly Figure can be wrapped with FigureResampler and FigureWidgetResampler! 🎉
But, (obviously) only the scatter traces will be resampled.

Tip 💡:
For significant faster initial loading of the Figure, we advise to wrap the constructor of the plotly Figure and add the trace data as hf_x and hf_y

Minimal example

import plotly.graph_objects as go; import numpy as np
from plotly_resampler import FigureResampler, FigureWidgetResampler

x = np.arange(1_000_000)
noisy_sin = (3 + np.sin(x / 200) + np.random.randn(len(x)) / 10) * x / 1_000

# OPTION 1 - FigureResampler: dynamic aggregation via a Dash web-app
fig = FigureResampler(go.Figure())
fig.add_trace(go.Scattergl(name='noisy sine', showlegend=True), hf_x=x, hf_y=noisy_sin)

fig.show_dash(mode='inline')

FigureWidgetResampler: dynamic aggregation via `FigureWidget.layout.on_change`

... 
# OPTION 2 - FigureWidgetResampler: dynamic aggregation via `FigureWidget.layout.on_change`
fig = FigureWidgetResampler(go.Figure())
fig.add_trace(go.Scattergl(name='noisy sine', showlegend=True), hf_x=x, hf_y=noisy_sin)

fig

Features

Convenient to use:
- just add either
  - FigureResampler decorator around a plotly Figure and call .show_dash()
  - FigureWidgetResampler decorator around a plotly Figure and output the instance in a cell
- allows all other plotly figure construction flexibility to be used!
Environment-independent
- can be used in Jupyter, vscode-notebooks, Pycharm-notebooks, Google Colab, and even as application (on a server)
Interface for various aggregation algorithms:
- ability to develop or select your preferred sequence aggregation method

Important considerations & tips

When running the code on a server, you should forward the port of the FigureResampler.show_dash() method to your local machine.
Note that you can add dynamic aggregation to plotly figures with the FigureWidgetResampler wrapper without needing to forward a port!
In general, when using downsampling one should be aware of (possible) aliasing effects.
The [R] in the legend indicates when the corresponding trace is being resampled (and thus possibly distorted) or not. Additionally, the ~<range> suffix represent the mean aggregation bin size in terms of the sequence index.
The plotly autoscale event (triggered by the autoscale button or a double-click within the graph), does not reset the axes but autoscales the current graph-view of plotly-resampler figures. This design choice was made as it seemed more intuitive for the developers to support this behavior with double-click than the default axes-reset behavior. The graph axes can ofcourse be resetted by using the reset_axis button. If you want to give feedback and discuss this further with the developers, see issue #49.

Future work 🔨

Support .add_traces() (currently only .add_trace is supported)

👤 Jonas Van Der Donckt, Jeroen Van Der Donckt, Emiel Deprost

bbradbury/plotly-resampler