You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> `plotly_resampler`: visualize large sequential data by **adding resampling functionality to Plotly figures**
20
20
21
-
[Plotly](https://github.com/plotly/plotly.py) 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.
21
+
[Plotly](https://github.com/plotly/plotly.py) 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.
22
+
23
+
In [this Plotly-Resampler demo](https://github.com/predict-idlab/plotly-resampler/blob/main/examples/basic_example.ipynb) over `110,000,000` data points are visualized!
26
+
In [this Plotly-Resampler demo](https://github.com/predict-idlab/plotly-resampler/blob/main/examples/basic_example.ipynb) over `110,000,000` data points are visualized!
30
27
31
28
<!-- These dynamic aggregation callbacks are realized with: -->
32
29
<!-- * [Dash](https://github.com/plotly/dash) when a `go.Figure` object is wrapped with dynamic aggregation functionality, see example ⬆️. -->
@@ -39,96 +36,144 @@ In [this Plotly-Resampler demo](https://github.com/predict-idlab/plotly-resample
> For significant faster initial loading of the Figure, we advise to wrap the
131
+
> constructor of the plotly Figure and add the trace data as`hf_x`and`hf_y`
98
132
99
-
> **Note**:
100
-
> Any plotly Figure can be wrapped with `FigureResampler` and `FigureWidgetResampler`! 🎉
101
-
> But, (obviously) only the scatter traces will be resampled.
133
+
<br>
102
134
103
-
> **Tip** 💡:
104
-
> 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`
135
+
>**Note**:
136
+
> Any plotly Figure can be wrapped with`FigureResampler`and`FigureWidgetResampler`! 🎉
137
+
> But, (obviously) only the scatter traces will be resampled.
105
138
106
139
107
-
### Features
108
140
109
-
***Convenient** to use:
110
-
* just add either
111
-
*`FigureResampler` decorator around a plotly Figure and call `.show_dash()`
112
-
*`FigureWidgetResampler` decorator around a plotly Figure and output the instance in a cell
113
-
* allows all other plotly figure construction flexibility to be used!
114
-
***Environment-independent**
115
-
* can be used in Jupyter, vscode-notebooks, Pycharm-notebooks, Google Colab, and even as application (on a server)
116
-
* Interface for **various aggregation algorithms**:
117
-
* ability to develop or select your preferred sequence aggregation method
118
141
142
+
<br>
143
+
<details><summary>Features</summary>
144
+
145
+
***Convenient** to use:
146
+
* just add either
147
+
*`register_plotly_resampler` function to your notebook with the best suited `mode` argument.
148
+
*`FigureResampler` decorator around a plotly Figure and call `.show_dash()`
149
+
*`FigureWidgetResampler` decorator around a plotly Figure and output the instance in a cell
150
+
* allows all other plotly figure construction flexibility to be used!
151
+
***Environment-independent**
152
+
* can be used in Jupyter, vscode-notebooks, Pycharm-notebooks, Google Colab, and even as application (on a server)
* ability to develop or select your preferred sequence aggregation method
155
+
</details>
119
156
120
157
### Important considerations & tips
121
158
122
159
* When running the code on a server, you should forward the port of the `FigureResampler.show_dash()` method to your local machine.<br>
123
160
**Note** that you can add dynamic aggregation to plotly figures with the `FigureWidgetResampler` wrapper without needing to forward a port!
124
-
* In general, when using downsampling one should be aware of (possible) [aliasing](https://en.wikipedia.org/wiki/Aliasing) effects.
161
+
* In general, when using downsampling one should be aware of (possible) [aliasing](https://en.wikipedia.org/wiki/Aliasing) effects.
125
162
The <b><a style="color:orange">[R]</a></b>in the legend indicates when the corresponding trace is being resampled (and thus possibly distorted) ornot. Additionally, the `~<range>` suffix represent the mean aggregation bin size in terms of the sequence index.
126
163
* 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](https://github.com/predict-idlab/plotly-resampler/issues/49).
127
164
165
+
<!--## Cite
166
+
167
+
```latex
168
+
{
169
+
}
170
+
``` -->
128
171
129
172
## Future work 🔨
130
173
131
174
- [x] Support `.add_traces()` (currently only `.add_trace`is supported)
175
+
- [ ] Support `hf_color`and`hf_markersize`, see [#50](https://github.com/predict-idlab/plotly-resampler/pull/50)
176
+
- [ ] Create C bindings for our EfficientLTTB algorithm.
Copy file name to clipboardExpand all lines: docs/sphinx/getting_started.rst
+59-18Lines changed: 59 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,40 +21,79 @@ Install via `pip <https://pypi.org/project/plotly-resampler>`_:
21
21
How to use 📈
22
22
-------------
23
23
24
-
Dynamic resampling callbacks are realized with either:
24
+
Dynamic resampling callbacks are realized:
25
25
26
-
* `Dash <https://github.com/plotly/dash>`_ callbacks, when a ``go.Figure`` object is wrapped with dynamic aggregation functionality.
26
+
* **Automatically** (low code overhead):
27
27
28
-
.. note::
28
+
* using the :func:`register_plotly_resampler <plotly_resampler.registering.register_plotly_resampler>` function
29
29
30
-
This is especially useful when working with **dash functionality** or when you do **not want to solely operate in jupyter environments**.
30
+
**To add dynamic resampling using a FigureWidget, you should**:
31
+
1. Import and call the :func:`register_plotly_resampler <plotly_resampler.registering.register_plotly_resampler>` method
32
+
2. Just use your regular graph construction code
31
33
32
-
To **add dynamic resampling**, you should:
33
-
1. wrap the plotly Figure with :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>`
34
-
2. call :func:`.show_dash() <plotly_resampler.figure_resampler.FigureResampler.show_dash>` on the Figure
34
+
Once this method is called, it will automatically convert all new defined plotly
35
+
graph objects into a :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>` or :class:`FigureWidgetResampler <plotly_resampler.figure_resampler.FigureWidgetResampler>` object.
36
+
The ``mode`` parameter of this method allows to define which type of the aforementioned resampling objects is used.
35
37
36
-
* `FigureWidget.layout.on_change <https://plotly.com/python-api-reference/generated/plotly.html?highlight=on_change#plotly.basedatatypes.BasePlotlyType.on_change>`_ , when a ``go.FigureWidget`` is used within a ``.ipynb`` environment.
38
+
* **Manually** (data aggregation configurability, graph construction speedups):
37
39
38
-
.. note::
40
+
* `Dash <https://github.com/plotly/dash>`_ callbacks, when a ``go.Figure`` object is wrapped with dynamic aggregation functionality.
39
41
40
-
This is especially useful when developing in ``jupyter`` environments and when **you cannot open/forward a network-port**.
42
+
.. note::
41
43
44
+
This is especially useful when working with **dash functionality** or when you do **not want to solely operate in jupyter environments**.
42
45
43
-
To **add dynamic resampling** using a **FigureWidget**, you should:
44
-
1. wrap your plotly Figure (can be a ``go.Figure``) with :class:`FigureWidgetResampler <plotly_resampler.figure_resampler.FigureWidgetResampler>`
45
-
2. output the ```FigureWidgetResampler`` instance in a cell
46
+
**To add dynamic resampling, you should**:
47
+
1. wrap the plotly Figure with :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>`
48
+
2. call :func:`.show_dash() <plotly_resampler.figure_resampler.FigureResampler.show_dash>` on the Figure
46
49
47
-
.. tip::
50
+
* `FigureWidget.layout.on_change <https://plotly.com/python-api-reference/generated/plotly.html?highlight=on_change#plotly.basedatatypes.BasePlotlyType.on_change>`_ , when a ``go.FigureWidget`` is used within a ``.ipynb`` environment.
51
+
52
+
.. note::
53
+
54
+
This is especially useful when developing in ``jupyter`` environments and when **you cannot open/forward a network-port**.
48
55
49
-
For **significant faster initial loading** of the Figure, we advise to wrap the constructor of the plotly Figure with either :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>` or :class:`FigureWidgetResampler <plotly_resampler.figure_resampler.FigureWidgetResampler>` and add the trace data as ``hf_x`` and ``hf_y``
50
56
51
-
.. note::
57
+
**To add dynamic resampling using a FigureWidget, you should**:
58
+
1. wrap your plotly Figure (can be a ``go.Figure``) with :class:`FigureWidgetResampler <plotly_resampler.figure_resampler.FigureWidgetResampler>`
59
+
2. output the ```FigureWidgetResampler`` instance in a cell
52
60
53
-
Any plotly Figure can be wrapped with dynamic aggregation functionality! 🎉 :raw-html:`<br>`
54
-
But, (obviously) only the scatter traces will be resampled.
61
+
.. tip::
62
+
63
+
For **significant faster initial loading** of the Figure, we advise to wrap the constructor of the plotly Figure with either :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>` or :class:`FigureWidgetResampler <plotly_resampler.figure_resampler.FigureWidgetResampler>` and add the trace data as ``hf_x`` and ``hf_y``
64
+
65
+
.. note::
66
+
67
+
Any plotly Figure can be wrapped with dynamic aggregation functionality! 🎉 :raw-html:`<br>`
68
+
But, (obviously) only the scatter traces will be resampled.
55
69
56
70
Working examples ✅
57
71
-------------------
72
+
register_plotly_resampler
73
+
^^^^^^^^^^^^^^^^^^^^^^^^^
74
+
75
+
.. code:: py
76
+
77
+
import plotly.graph_objects as go; import numpy as np
78
+
from plotly_resampler import register_plotly_resampler
79
+
80
+
# Call the register function once and all Figures/FigureWidgets will be wrapped
81
+
# according to the register_plotly_resampler its `mode` argument
# when working in an IPython environment, this will automatically be a
89
+
# FigureWidgetResampler else, this will be an FigureResampler
90
+
f = go.Figure()
91
+
f.add_trace({"y": noisy_sin +2, "name": "yp2"})
92
+
f
93
+
94
+
95
+
FigureResampler
96
+
^^^^^^^^^^^^^^^
58
97
59
98
.. code:: py
60
99
@@ -69,6 +108,8 @@ Working examples ✅
69
108
70
109
fig.show_dash(mode='inline')
71
110
111
+
FigureWidget
112
+
^^^^^^^^^^^^
72
113
The gif below demonstrates the example usage of of :class:`FigureWidgetResampler <plotly_resampler.figure_resampler.FigureWidgetResampler>`, where ``JupyterLab`` is used as environment and the ``FigureWidgetResampler`` instance it's output is redirected into a new view. Also note how you are able to dynamically add traces!
0 commit comments