🖊️ review code

Author: jvdd

README.md

@@ -8,6 +8,7 @@
 [![support-version](https://img.shields.io/pypi/pyversions/plotly-resampler)](https://img.shields.io/pypi/pyversions/plotly-resampler)
 [![codecov](https://img.shields.io/codecov/c/github/predict-idlab/plotly-resampler?logo=codecov)](https://codecov.io/gh/predict-idlab/plotly-resampler)
 [![Code quality](https://img.shields.io/lgtm/grade/python/github/predict-idlab/plotly-resampler?label=code%20quality&logo=lgtm)](https://lgtm.com/projects/g/predict-idlab/plotly-resampler/context:python)
+[![Downloads](https://pepy.tech/badge/plotly-resampler)](https://pepy.tech/project/plotly-resampler)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?)](http://makeapullrequest.com)
 [![Documentation](https://github.com/predict-idlab/plotly-resampler/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/predict-idlab/plotly-resampler/actions/workflows/deploy-docs.yml)
 [![Testing](https://github.com/predict-idlab/plotly-resampler/actions/workflows/test.yml/badge.svg)](https://github.com/predict-idlab/plotly-resampler/actions/workflows/test.yml)
@@ -17,7 +18,7 @@
 
 > `plotly_resampler`: visualize large sequential data by **adding resampling functionality to Plotly figures**
 
-[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 and update the figure. 
+[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. 
 
 <p align="center">
     <a href="#readme">
@@ -54,11 +55,11 @@ To **add dynamic resampling** to your plotly Figure
   2. output the `FigureWidgetResampler` instance in a cell
 
 > **Note**:  
-> Any plotly Figure can be wrapped with FigureResampler and FigureWidgetResampler! 🎉  
+> 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 with `FigureResampler` and add the trace data as `hf_x` and `hf_y`
+> 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
 
@@ -69,7 +70,7 @@ 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
 
-# FigureResampler: dynamic aggregation via a Dash web-app
+# 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)
 
@@ -79,7 +80,7 @@ fig.show_dash(mode='inline')
 #### FigureWidgetResampler: dynamic aggregation via `FigureWidget.layout.on_change`
 ```python
 ... 
-# 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)
 
@@ -89,7 +90,9 @@ fig
 ### Features
 
 * **Convenient** to use:
-  * just add the `FigureResampler` decorator around a plotly Figure and call `.show_dash()`
+  * 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)
@@ -100,9 +103,10 @@ fig
 ### 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.<br>
-  **note** that you can add dynamic aggregation to plotly figures with the `FigureWidgetResampler` wrapper.
+  **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](https://en.wikipedia.org/wiki/Aliasing) effects.  
   The <b><a style="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.
+
 ## Future work 🔨
 
 * Support `.add_traces()` (currently only `.add_trace` is supported)

docs/sphinx/getting_started.rst

@@ -7,7 +7,7 @@ Getting started 🚀
 ``plotly-resampler`` serves two main **modules**:
 
 * :py:mod:`figure_resampler <plotly_resampler.figure_resampler>`: a wrapper for *plotly.graph\_objects Figures*,  coupling the dynamic resampling functionality to the *Figure*.
-* :py:mod:`aggregation <plotly_resampler.aggregation>`: a module withholds various data aggregation methods.
+* :py:mod:`aggregation <plotly_resampler.aggregation>`: a module that withholds various data aggregation methods.
 
 Installation ⚙️
 ---------------
@@ -42,11 +42,11 @@ Dynamic resampling callbacks are realized with either:
 
   To **add dynamic resampling** using a **FigureWidget**, you should:
     1. wrap your plotly Figure (can be a ``go.Figure``) with :class:`FigureWidgetResampler <plotly_resampler.figure_resampler.FigureWidgetResampler>`
-    2. Create a cell output for the ``FigureWidgetResampler`` instance
+    2. output the ```FigureWidgetResampler`` instance in a cell
 
 .. tip::
 
-  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``
+  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``
 
 .. note::
 

plotly_resampler/figure_resampler/figure_resampler.py

@@ -50,7 +50,7 @@ def __init__(
             verbose,
         )
 
-        # The figureAggregator needs a dash app
+        # The FigureResampler needs a dash app
         self._app: JupyterDash | Dash | None = None
         self._port: int | None = None
         self._host: str | None = None
@@ -96,7 +96,7 @@ def show_dash(
         graph_properties = {} if graph_properties is None else graph_properties
         assert "config" not in graph_properties.keys()  # There is a param for config
         # 1. Construct the Dash app layout
-        app = JupyterDash("local_app")  # TODO -> was jupyterdash
+        app = JupyterDash("local_app")
         app.layout = dash.html.Div(
             [
                 dash.dcc.Graph(

plotly_resampler/figure_resampler/figure_resampler_interface.py

@@ -30,6 +30,8 @@
 
 
 class AbstractFigureAggregator(BaseFigure, ABC):
+    """Abstract interface for data aggregation functionality for plotly figures."""
+
     def __init__(
         self,
         figure: BaseFigure,

plotly_resampler/figure_resampler/figurewidget_resampler.py

@@ -40,7 +40,7 @@ class FigureWidgetResampler(
 
     def __init__(
         self,
-        figure: go.FigureWidget,
+        figure: go.FigureWidget | go.Figure = go.Figure(),
         convert_existing_traces: bool = True,
         default_n_shown_samples: int = 1000,
         default_downsampler: AbstractSeriesAggregator = EfficientLTTB(),