Repository files navigation

plotly_resampler: visualize large sequential data byadding resampling functionality to Plotly figures

plotly-resampler improves the scalability ofPlotly for visualizing large time series datasets. Specifically, our librarydynamicallyaggregates time-series data respective to the current graph view, ensuring efficient and responsive updates during user interactions like panning or zooming via callbacks.

This core aggregation functionality is achieved by utilizing bytime-series data point selection algorithms, for whichplotly-resampler leverages the highly optimized implementations available intsdownsample. Our default data aggregation method isMinMaxLTTB (and selects 1000 data points for plotting). For a deeper understanding of this method, you can consult to the algorithm's dedicatedMinMaxLTTB repository and the associatedresearch paper.

Inthis Plotly-Resampler demo over110,000,000 data points are visualized!

• Convenient to use:
  • just add either
    • register_plotly_resampler function to your notebook with the best suitedmode argument.
    • 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, DataSpell, and even as application (on a server)
• Interface forvarious aggregation algorithms:
  • ability to develop or select your preferred sequence aggregation method

Add dynamic aggregation to your plotly Figure(unfold your fitting use case)

• 🤖Automatically(minimal code overhead):

  Use theregister_plotly_resampler function

  
  

  1. Import and call theregister_plotly_resampler method
  2. Just use your regular graph construction code

  • code example:

    importplotly.graph_objectsasgo;importnumpyasnpfromplotly_resamplerimportregister_plotly_resampler# Call the register function once and all Figures/FigureWidgets will be wrapped# according to the register_plotly_resampler its `mode` argumentregister_plotly_resampler(mode='auto')x=np.arange(1_000_000)noisy_sin= (3+np.sin(x/200)+np.random.randn(len(x))/10)*x/1_000# auto mode: when working in an IPython environment, this will automatically be a# FigureWidgetResampler else, this will be an FigureResamplerf=go.Figure()f.add_trace({"y":noisy_sin+2,"name":"yp2"})f

  Note: This wrapsall plotly graph object figures with aFigureResampler |FigureWidgetResampler. This can thus also beused for theplotly.express interface. 🎉

• 👷Manually(higher data aggregation configurability, more speedup possibilities):

  • Within ajupyter environment without creating aweb application
    1. wrap the plotly Figure withFigureWidgetResampler
    2. output theFigureWidgetResampler instance in a cell

    importplotly.graph_objectsasgo;importnumpyasnpfromplotly_resamplerimportFigureResampler,FigureWidgetResamplerx=np.arange(1_000_000)noisy_sin= (3+np.sin(x/200)+np.random.randn(len(x))/10)*x/1_000# OPTION 1 - 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

  • Using aweb-application withdash callbacks
    1. wrap the plotly Figure withFigureResampler
    2. call.show_dash() on theFigure

    importplotly.graph_objectsasgo;importnumpyasnpfromplotly_resamplerimportFigureResampler,FigureWidgetResamplerx=np.arange(1_000_000)noisy_sin= (3+np.sin(x/200)+np.random.randn(len(x))/10)*x/1_000# OPTION 2 - FigureResampler: dynamic aggregation via a Dash web-appfig=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')

  Tip 💡:For significant faster initial loading of the Figure, we advise to wrap theconstructor of the plotly Figure and add the trace data ashf_x andhf_y

Note:Any plotly Figure can be wrapped withFigureResampler andFigureWidgetResampler! 🎉Butonly thego.Scatter/go.Scattergltraces are resampled.

• When running the code on a server, you should forward the port of theFigureResampler.show_dash() method to your local machine.
  Note that you can add dynamic aggregation to plotly figures with theFigureWidgetResampler wrapper without needing to forward a port!
• TheFigureWidgetResampleruses the IPython main thread for its data aggregation functionality, so when this main thread is occupied, no resampling logic can be executed. For example; if you perform long computations within your notebook, the kernel will be occupied during these computations, and will only execute the resampling operations that take place during these computations after finishing that computation.
• 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 plotlyautoscale 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 thereset_axis button. If you want to give feedback and discuss this further with the developers, see issue#49.

The paper about the plotly-resampler toolkit itself (preprint):https://arxiv.org/abs/2206.08703

@inproceedings{van2022plotly,title={Plotly-resampler: Effective visual analytics for large time series},author={Van Der Donckt, Jonas and Van Der Donckt, Jeroen and Deprost, Emiel and Van Hoecke, Sofie},booktitle={2022 IEEE Visualization and Visual Analytics (VIS)},pages={21--25},year={2022},organization={IEEE}}

Related papers:

• Visual representativeness of time series data point selection algorithms (preprint):https://arxiv.org/abs/2304.00900
  code:https://github.com/predict-idlab/ts-datapoint-selection-vis
• MinMaxLTTB - an efficient data point selection algorithm (preprint):https://arxiv.org/abs/2305.00332
  code:https://github.com/predict-idlab/MinMaxLTTB

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