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**
19
20
20
-
[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 the data respective to the view and then plotting the downsampled points. When you interact with the plot (panning, zooming, ...), [dash](https://github.com/plotly/dash)callbacks are used to resample and redraw the figures.
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
22
22
23
<palign="center">
23
24
<a href="#readme">
@@ -27,6 +28,10 @@
27
28
28
29
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!
29
30
31
+
<!-- These dynamic aggregation callbacks are realized with: -->
32
+
<!-- * [Dash](https://github.com/plotly/dash) when a `go.Figure` object is wrapped with dynamic aggregation functionality, see example ⬆️. -->
33
+
<!-- * The [FigureWidget.layout.on_change](https://plotly.com/python-api-reference/generated/plotly.html?highlight=on_change#plotly.basedatatypes.BasePlotlyType.on_change) method, when a `go.FigureWidget` is used within a `.ipynb` environment. -->
34
+
30
35
<!-- #### Useful links -->
31
36
32
37
<!-- - [Documentation]() work in progress 🚧 -->
@@ -41,48 +46,66 @@ In [this Plotly-Resampler demo](https://github.com/predict-idlab/plotly-resample
41
46
42
47
## Usage
43
48
44
-
To **add dynamic resampling to your plotly Figure**, you should;
45
-
1. wrap the plotly Figure with `FigureResampler`
46
-
2. call `.show_dash()` on the Figure
49
+
To **add dynamic resampling** to your plotly Figure
50
+
* using a web application with *Dash* callbacks, you should;
51
+
1. wrap the plotly Figure with `FigureResampler`
52
+
2. call `.show_dash()` on the Figure
53
+
* within a *jupyter* environment and *without creating a web application*, you should:
54
+
1. wrap the plotly Figure with `FigureWidgetResampler`
55
+
2. output the `FigureWidgetResampler` instance in a cell
47
56
48
57
> **Note**:
49
-
> Any plotly Figure can be wrapped with FigureResampler! 🎉
58
+
> Any plotly Figure can be wrapped with `FigureResampler` and `FigureWidgetResampler`! 🎉
50
59
> But, (obviously) only the scatter traces will be resampled.
51
60
52
61
> **Tip** 💡:
53
-
> For significant faster initial loading of the Figure, we advise to wrap the constructor of the plotly Figure with `FigureResampler`and add the trace data as `hf_x` and `hf_y`
62
+
> 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`
54
63
55
64
### Minimal example
56
65
57
66
```python
58
67
import plotly.graph_objects as go; import numpy as np
59
-
from plotly_resampler import FigureResampler
68
+
from plotly_resampler import FigureResampler, FigureWidgetResampler
* just add the `FigureResampler` decorator around a plotly Figure and call `.show_dash()`
93
+
* just add either
94
+
*`FigureResampler` decorator around a plotly Figure and call `.show_dash()`
95
+
*`FigureWidgetResampler` decorator around a plotly Figure and output the instance in a cell
74
96
* allows all other plotly figure construction flexibility to be used!
75
97
***Environment-independent**
76
98
* can be used in Jupyter, vscode-notebooks, Pycharm-notebooks, Google Colab, and even as application (on a server)
77
-
* Interface for **various downsampling algorithms**:
78
-
* ability to define your preferred sequence aggregation method
99
+
* Interface for **various aggregation algorithms**:
100
+
* ability to develop or select your preferred sequence aggregation method
79
101
80
102
81
103
### Important considerations & tips
82
104
83
-
* When running the code on a server, you should forward the port of the `FigureResampler.show_dash()` method to your local machine.
105
+
* When running the code on a server, you should forward the port of the `FigureResampler.show_dash()` method to your local machine.<br>
106
+
**Note** that you can add dynamic aggregation to plotly figures with the `FigureWidgetResampler` wrapper without needing to forward a port!
84
107
* In general, when using downsampling one should be aware of (possible) [aliasing](https://en.wikipedia.org/wiki/Aliasing) effects.
85
-
The <b><astyle="color:orange">[R]</a></b> in the legend indicates when the corresponding trace is being resampled (and thus possibly distorted) or not.
108
+
The <b><astyle="color:orange">[R]</a></b> 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.
Copy file name to clipboardExpand all lines: docs/sphinx/getting_started.rst
+37-21Lines changed: 37 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,45 +4,57 @@
4
4
Getting started 🚀
5
5
==================
6
6
7
+
``plotly-resampler`` serves two main **modules**:
7
8
8
-
``plotly-resampler`` maintains its interactiveness on large data by applying front-end
9
-
**resampling**.
10
-
11
-
12
-
Users can interact with 2 components:
13
-
14
-
* :ref:`FigureResampler <FigureResampler>`: a wrapper for *plotly.graph\_objects* that serves the adaptive resampling functionality.
15
-
* :ref:`aggregation <aggregation>`: this module withholds various data aggregation methods.
9
+
* :py:mod:`figure_resampler <plotly_resampler.figure_resampler>`: a wrapper for *plotly.graph\_objects Figures*, coupling the dynamic resampling functionality to the *Figure*.
10
+
* :py:mod:`aggregation <plotly_resampler.aggregation>`: a module that withholds various data aggregation methods.
16
11
17
12
Installation ⚙️
18
13
---------------
19
14
20
-
Install via :raw-html:`<ahref="https://pypi.org/project/plotly-resampler/"><b>pip</b><a>`:
15
+
Install via `pip <https://pypi.org/project/plotly-resampler>`_:
21
16
22
17
.. code:: bash
23
18
24
19
pip install plotly-resampler
25
20
26
-
27
21
How to use 📈
28
22
-------------
29
23
30
-
To **add dynamic resampling to a plotly Figure**, you should;
24
+
Dynamic resampling callbacks are realized with either:
25
+
26
+
* `Dash <https://github.com/plotly/dash>`_ callbacks, when a ``go.Figure`` object is wrapped with dynamic aggregation functionality.
27
+
28
+
.. note::
29
+
30
+
This is especially useful when working with **dash functionality** or when you do **not want to solely operate in jupyter environments**.
31
+
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
31
35
32
-
1. wrap the plotly Figure with :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>`
33
-
2. call :func:`.show_dash() <plotly_resampler.figure_resampler.FigureResampler.show_dash>` on the Figure
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.
37
+
38
+
.. note::
39
+
40
+
This is especially useful when developing in ``jupyter`` environments and when **you cannot open/forward a network-port**.
41
+
42
+
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
34
46
35
47
.. tip::
36
48
37
-
For **significant faster initial loading** of the Figure, we advise to wrap the constructor of the plotly Figure with :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>` and add the trace data as ``hf_x`` and ``hf_y``
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``
38
50
39
51
.. note::
40
52
41
-
Any plotly Figure can be wrapped with :class:`FigureResampler <plotly_resampler.figure_resampler.FigureResampler>`! 🎉 :raw-html:`<br>`
42
-
But, (obviously) only the scatter traces will be resampled.
53
+
Any plotly Figure can be wrapped with dynamic aggregation functionality! 🎉 :raw-html:`<br>`
54
+
But, (obviously) only the scatter traces will be resampled.
43
55
44
-
Working example ✅
45
-
------------------
56
+
Working examples ✅
57
+
-------------------
46
58
47
59
.. code:: py
48
60
@@ -57,6 +69,10 @@ Working example ✅
57
69
58
70
fig.show_dash(mode='inline')
59
71
72
+
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!
@@ -99,7 +115,7 @@ Plotly-resampler & not high-frequency traces 🔍
99
115
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
100
116
101
117
.. Tip::
102
-
118
+
103
119
In the *Skin conductance example* of the :raw-html:`<ahref="https://github.com/predict-idlab/plotly-resampler/tree/main/examples"><b>basic_example.ipynb</b><a>`, we deal with such low-frequency traces.
104
120
105
121
The :func:`add_trace <plotly_resampler.figure_resampler.FigureResampler.add_trace>` method allows configuring argument which allows us to deal with low-frequency traces.
@@ -108,11 +124,11 @@ The :func:`add_trace <plotly_resampler.figure_resampler.FigureResampler.add_trac
108
124
Use-cases
109
125
"""""""""
110
126
111
-
* **not resampling** trace data: To achieve this, set:
127
+
* **not resampling** trace data: To achieve this, set:
112
128
113
129
* ``max_n_samples`` = len(hf_x)
114
130
115
-
* **not resampling** trace data, but **slicing to the view**: To achieve this, set:
131
+
* **not resampling** trace data, but **slicing to the view**: To achieve this, set:
As shown in the demo above, ``plotly-resampler`` maintains its interactiveness on large data by applying front-end **resampling respective to the view**.
Copy file name to clipboardExpand all lines: examples/README.md
+6-1Lines changed: 6 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,12 @@ plotly-resampler in various use cases.
7
7
8
8
The testing CI/CD of plotly resampler uses _selenium_ and _selenium-wire_ to test the
9
9
interactiveness of various figures. All these figures are shown in
10
-
the [basic-example notebook](basic_example.ipynb)
10
+
the [basic example notebook](basic_example.ipynb)
11
+
12
+
### 0.1 Figurewidget example
13
+
14
+
The [figurewidget example notebook](figurewidget_example.ipynb) utilizes the `FigureWidgetResampler` wrapper to
15
+
create a `go.FigureWidget` with dynamic aggregation functionality. A major advantage of this approach is that this does not create a web application, thus not needing to be able to create / forward a network port.
0 commit comments