🖊️ review

Author: jvdd

.gitignore

@@ -1,6 +1,7 @@
 venv*
 .cache_datasets/
 *.DS_Store
+file_system_store/
 
 # Sphinx documentation
 *_build/

README.md

@@ -158,7 +158,7 @@ In [this Plotly-Resampler demo](https://github.com/predict-idlab/plotly-resample
 
 * 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 without needing to forward a port!
-* The `FigureWidgetResampler` *uses the python 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 which take place during these computations after finishing that computation.
+* The `FigureWidgetResampler` *uses 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](https://en.wikipedia.org/wiki/Aliasing) effects.
   The <b style="color:orange">[R]</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.
 * 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).

docs/sphinx/FAQ.rst

@@ -20,8 +20,8 @@ FAQ ❓
 
 This tilde suffix is only shown when the data is aggregated and represents the *mean aggregation bin size* which is the mean index-range difference between two consecutive aggregated samples.
 
- * for *time-indexed data*: the mean time-range which is span between 2 consecutive samples.
- * for *numeric-indexed data*: the mean numeric range which is span between 2 consecutive samples.
+ * for *time-indexed data*: the mean time-range between 2 consecutive (sampled) samples.
+ * for *numeric-indexed data*: the mean numeric range between 2 consecutive (sampled) samples.
 
 When the index is a range-index; the *mean aggregation bin size* represents the *mean* downsample ratio; i.e., the mean number of samples that are aggregated into one sample.
 
@@ -44,7 +44,7 @@ plotly-resampler can be thought of as wrapper around plain plotly figures which
 * To have dynamic aggregation:
 
   * with ``FigureResampler``, you need to call ``show_dash`` (or output the object in a cell via ``IPython.display``) -> which spawns a dash-web app, and the dynamic aggregation is realized with dash callback
-  * with ``FigureWidgetResampler``, you need to use ``IPython.display`` on the object, which uses widget-events to realize dynamic aggregation.
+  * with ``FigureWidgetResampler``, you need to use ``IPython.display`` on the object, which uses widget-events to realize dynamic aggregation (via the running IPython kernel).
 
 .. raw:: html
 
@@ -57,7 +57,7 @@ plotly-resampler can be thought of as wrapper around plain plotly figures which
    </summary>
    <div style="margin-left:1em">
 
-The ``TraceUpdater`` class is a custom dash component that aids ``dcc.Graph`` components to efficiently sent and update (in our case aggregated) data to the front-end.
+The ``TraceUpdater`` class is a custom dash component that aids ``dcc.Graph`` components to efficiently send and update (in our case aggregated) data to the front-end.
 
 For more information on how to use the trace-updater component together with the ``FigureResampler``, see our dash app `examples <https://github.com/predict-idlab/plotly-resampler/tree/main/examples>`_` and look at the `trace-updater <https://github.com/predict-idlab/trace-updater/blob/master/trace_updater/TraceUpdater.py>`_ its documentation.
 
@@ -78,19 +78,19 @@ For more information on how to use the trace-updater component together with the
 
 **The main differences are**:
 
-Datashader is able deal with various kinds of data (e.g., location related data, point clouds, ...), and plotly-resampler is more tailored towards time-series data visualizations. 
+Datashader can deal with various kinds of data (e.g., location related data, point clouds), whereas plotly-resampler is more tailored towards time-series data visualizations. 
 Furthermore, datashader outputs a **rasterized image/array** encompassing all traces their data, whereas plotly-resampler outputs an **aggregated series** per trace. Thus, datashader is more suited for analyzing data where you do not want to pin-out a certain series/trace.
 
 In our opinion, datashader truly shines (for the time series use case) when:
 
 * you want a global, overlaying view of all your traces
 * you want to visualize a large number of time series in a single plot (many traces)
-* there is a lot of noise on your high-frequency data and want to uncover the underlying pattern
+* there is a lot of noise on your high-frequency data and you want to uncover the underlying pattern
 * you want to render all data points in your visualization
 
 In our opinion, plotly-resampler shines when:
 
-* you need the capabilities to interact with the traces (e.g., hovering, toggling traces, hovertext pet trace)
+* you need the capabilities to interact with the traces (e.g., hovering, toggling traces, hovertext per trace)
 * you want to use a less complex (but more restricted) visualization interface (as opposed to holoviews), i.e., plotly
 * you want to make existing plotly time-series figures more scalable and efficient
 * to build scalable Dash apps for time-series data visualization

docs/sphinx/getting_started.rst

@@ -56,7 +56,7 @@ Dynamic resampling callbacks are realized:
 
     **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. output the ```FigureWidgetResampler`` instance in a cell
+      2. output the ``FigureWidgetResampler`` instance in a cell
 
   .. tip::
 
@@ -120,7 +120,7 @@ The gif below demonstrates the example usage of of :class:`FigureWidgetResampler
     <br><br>
 
 
-Furthermore, plotly figurewidget allows to conveniently add callbacks to for example click events. This allows to create a high-frequency time series annotation app in a couple of lines; a shown in the gif below and `this notebook <https://github.com/predict-idlab/plotly-resampler/blob/main/examples/figurewidget_example.ipynb>`_.
+Furthermore, plotly's ``FigureWidget`` allows to conveniently add callbacks to for example click events. This allows creating a high-frequency time series annotation app in a couple of lines; as shown in the gif below and in `this notebook <https://github.com/predict-idlab/plotly-resampler/blob/main/examples/figurewidget_example.ipynb>`_.
 
 
 .. image:: _static/annotate_twitter.gif

examples/README.md

@@ -1,12 +1,6 @@
 # plotly-resampler examples
 
-This directory withholds several examples, highlighting the applicability of 
-plotly-resampler for various use cases.
-
-To successfully run these examples, make sure that you've installed all the requirements by running:
-```bash
-pip install -r requirements.txt
-```
+This directory withholds several examples, highlighting the applicability of plotly-resampler for various use cases.
 
 
 ## Prerequisites
@@ -19,8 +13,7 @@ pip install -r requirements.txt
 ## 1. Example notebooks
 ### 1.1 basic examples
 
-The [basic example notebook](basic_example.ipynb) covers most use-cases in which plotly resampler will be employed. It is the ideal hands-on starting point for data-scientists who want to use
-plotly-resampler in their day-to-day jupyter environments.
+The [basic example notebook](basic_example.ipynb) covers most use-cases in which plotly resampler will be employed. It servers as an ideal starting point for data-scientists who want to use plotly-resampler in their day-to-day jupyter environments.
 
 Additionally, this notebook also shows some more advanced functionalities, such as:
 * Retaining (a static) plotly-resampler figure in your notebook
@@ -30,7 +23,7 @@ Additionally, this notebook also shows some more advanced functionalities, such
 
 ### 1.2 Figurewidget example
 
-The [figurewidget example notebook](figurewidget_example.ipynb) utilizes the `FigureWidgetResampler` wrapper to 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.
+The [figurewidget example notebook](figurewidget_example.ipynb) utilizes the `FigureWidgetResampler` wrapper to create a `go.FigureWidget` with dynamic aggregation functionality. A major advantage of this approach is that this does not create a web application, avoiding starting an application on a port (and forwarding that port when working remotely).
 
 Additionally, this notebook highlights how to use the `FigureWidget` its on-click callback to utilize plotly for large **time series annotation**.
 
@@ -48,7 +41,7 @@ which `plotly-resampler` is integrated
 | **advanced apps** |                                                                                                                                                                                                                                                                                     |
 | [dynamic sine generator](dash_apps/11_sine_generator.py) | exponential sine generator which uses [pattern matching callbacks](https://dash.plotly.com/pattern-matching-callbacks) to remove and construct plotly-resampler graphs dynamically                                                                                                  |
 | [file visualization](dash_apps/12_file_selector.py) | load and visualize multiple `.parquet` files with plotly-resampler                                                                                                                                                                                                                  |
-| [dynamic static graph](dash_apps/13_coarse_fine.py) | Visualization dashboard in which a dynamic (i.e., plotly-resampler graph) and static graph (i.e., go.Figure) are shown (made for [this issue](https://github.com/predict-idlab/plotly-resampler/issues/56)). Graph interaction events on the coarse graph update the dynamic graph. |
+| [dynamic static graph](dash_apps/13_coarse_fine.py) | Visualization dashboard in which a dynamic (i.e., plotly-resampler graph) and a coarse, static graph (i.e., go.Figure) are shown (made for [this issue](https://github.com/predict-idlab/plotly-resampler/issues/56)). Graph interaction events on the coarse graph update the dynamic graph. |
 
 ## 3. Other apps
 

examples/basic_example.ipynb

@@ -8,7 +8,7 @@
    "outputs": [],
    "source": [
     "%load_ext autoreload\n",
-    "%autoreload 2\n"
+    "%autoreload 2"
    ]
   },
   {
@@ -23,7 +23,6 @@
     "\n",
     "import plotly.graph_objects as go\n",
     "from plotly.subplots import make_subplots\n",
-    "from datetime import datetime\n",
     "\n",
     "from helper import groupby_consecutive\n",
     "\n",
@@ -344,7 +343,7 @@
     "    <li>we add a unique _uid to each object</li>\n",
     "    <li>we add a new endpoint to the underlying flask app that</li><ul>\n",
     "        <li>is only accessible via the corresponding app its _uid</li>\n",
-    "        <li>hasCORS rights for any origin and 'Content-Type' headers</li>\n",
+    "        <li>has CORS rights for any origin and 'Content-Type' headers</li>\n",
     "        </ul>\n",
     "        <li>Note that this is the only CORS endpoint of the JupyterDash app & is only preset when \"inline_persistent\" is used!</li>\n",
     "    <li>we check in the JavaScript output of the notebook cell whether that endpoint is reachable and emits the expected message (i.e., \"Alive\")</li><ul>\n",
@@ -461,7 +460,7 @@
     "* restart the kernel; and reopen this notebook\n",
     "* export this notebook to html\n",
     "\n",
-    "ou should see a static (aggregated) image of the above figure"
+    "you should see a static (aggregated) image of the above figure"
    ]
   },
   {
@@ -506,8 +505,8 @@
    "id": "6bffa11a",
    "metadata": {},
    "source": [
-    "now we adjust the figure data  \n",
-    "**note**: after running the cell below, we need to manually trigger a graph update (by for example zooming / resetting the axes) to ensure that the new data is shown."
+    "Now we adjust the figure data  \n",
+    "**Note**: after running the cell below, we need to manually trigger a graph update (by for example zooming / resetting the axes) to ensure that the new data is shown."
    ]
   },
   {
@@ -547,8 +546,8 @@
    "id": "22687274",
    "metadata": {},
    "source": [
-    "now we adjust the figure data  \n",
-    "**note**: after running the cell below, we need to manually trigger a graph update (by for example zooming / resetting the axes) to ensure that the new data is shown."
+    "Now we adjust the figure data  \n",
+    "**Note**: after running the cell below, we need to manually trigger a graph update (by for example zooming / resetting the axes) to ensure that the new data is shown."
    ]
   },
   {
@@ -566,7 +565,7 @@
    "id": "f4130fac",
    "metadata": {},
    "source": [
-    "**pro tip**: `FigureWidgetResampler` has the `reload_data` and `reset_axes` methods to do this automatically"
+    "**Pro tip**: `FigureWidgetResampler` has the `reload_data` and `reset_axes` methods to do this automatically"
    ]
   },
   {
@@ -1137,19 +1136,14 @@
     ")\n",
     "fig.show_dash(mode=\"inline\", port=9032)\n"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "336f4a9f",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
+  "interpreter": {
+   "hash": "7de7e435a0bf9ca45826b967e5fb3b58dc0ed05475145ede0348ba81bb2b2016"
+  },
   "kernelspec": {
-   "display_name": "Python 3.10.5 ('plotly-resampler-MpVFAeoZ-py3.10')",
+   "display_name": "Python 3.8.10 ('venv')",
    "language": "python",
    "name": "python3"
   },
@@ -1163,7 +1157,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.5"
+   "version": "3.8.10"
   },
   "toc-autonumbering": true,
   "vscode": {

examples/dash_apps/01_minimal_global.py

@@ -1,6 +1,6 @@
 """Minimal dash app example.
 
-Click on a button, and see a plotly-resampler graph of a noisy sinusoid.
+Click on a button, and see a plotly-resampler graph of two noisy sinusoids.
 No dynamic graph construction / pattern matching callbacks are needed.
 
 This example uses a global FigureResampler object, which is considered a bad practice.
@@ -30,7 +30,7 @@
 app = dash.Dash(__name__)
 fig: FigureResampler = FigureResampler()
 # NOTE: in this example, this reference to a FigureResampler is essential to preserve
-# throughout the whole dash app! If your dash app want to create a new go.Figure(),
+# throughout the whole dash app! If your dash app wants to create a new go.Figure(),
 # you should not construct a new FigureResampler object, but replace the figure of this
 # FigureResampler object by using the FigureResampler.replace() method.
 

examples/dash_apps/02_minimal_cache.py

@@ -1,12 +1,11 @@
 """Minimal dash app example.
 
-Click on a button, and see a plotly-resampler graph of a noisy sinusoid.
+Click on a button, and see a plotly-resampler graph of two noisy sinusoids.
 No dynamic graph construction / pattern matching callbacks are needed.
 
 This example uses the dash-extensions its ServersideOutput functionality to cache
 the FigureResampler per user/session on the server side. This way, no global figure
-variable is used and shows the best practice of using plotly-resampler Figures within
-dash-apps.
+variable is used and shows the best practice of using plotly-resampler within dash-apps.
 
 """
 
@@ -34,7 +33,7 @@
         html.H1("plotly-resampler + dash-extensions", style={"textAlign": "center"}),
         html.Button("plot chart", id="plot-button", n_clicks=0),
         html.Hr(),
-        # The graph and it's needed components to serialize and update efficiently
+        # The graph and its needed components to serialize and update efficiently
         # Note: we also add a dcc.Store component, which will be used to link the
         #       server side cached FigureResampler object
         dcc.Graph(id="graph-id"),

examples/dash_apps/03_minimal_cache_dynamic.py

@@ -1,19 +1,20 @@
 """Minimal dynamic dash app example.
 
-Click on a button, and draw a new plotly-resampler graph of a noisy sinusoid.
+Click on a button, and draw a new plotly-resampler graph of two noisy sinusoids.
 This example uses pattern-matching callbacks to update dynamically constructed graphs.
 The plotly-resampler graphs themselves are cached on the server side.
 
-The main difference between this example and the dash_app_minimal_cache.py is that here,
-we want to cache using a dcc.Store that is not yet available on the client side. As a
-result we split up our logic into two callbacks: (1) the callback used to construct the
-necessary components and send them to the client-side, and (2) the callback used to
-construct the actual plotly-resampler graph and cache it on the server side. These
-two callbacks are chained together using the dcc.Interval component.
+The main difference between this example and 02_minimal_cache.py is that here, we want
+to cache using a dcc.Store that is not yet available on the client side. As a result we
+split up our logic into two callbacks: (1) the callback used to construct the necessary
+components and send them to the client-side, and (2) the callback used to construct the
+actual plotly-resampler graph and cache it on the server side. These two callbacks are
+chained together using the dcc.Interval component.
 
 """
 
 from uuid import uuid4
+from typing import List
 
 import numpy as np
 import plotly.graph_objects as go
@@ -46,18 +47,18 @@
 
 # ------------------------------------ DASH logic -------------------------------------
 # This method adds the needed components to the front-end, but does not yet contain the
-# figureResampler graph construction logic.
+# FigureResampler graph construction logic.
 @app.callback(
     Output("container", "children"),
     Input("add-chart", "n_clicks"),
     State("container", "children"),
     prevent_initial_call=True,
 )
-def add_graph_div(n_clicks: int, div_children: list[html.Div]):
+def add_graph_div(n_clicks: int, div_children: List[html.Div]):
     uid = str(uuid4())
     new_child = html.Div(
         children=[
-            # The graph and it's needed components to serialize and update efficiently
+            # The graph and its needed components to serialize and update efficiently
             # Note: we also add a dcc.Store component, which will be used to link the
             #       server side cached FigureResampler object
             dcc.Graph(id={"type": "dynamic-graph", "index": uid}, figure=go.Figure()),
@@ -75,7 +76,7 @@ def add_graph_div(n_clicks: int, div_children: list[html.Div]):
     return div_children
 
 
-# This method constructs the figureResampler graph and caches it on the server side
+# This method constructs the FigureResampler graph and caches it on the server side
 @app.callback(
     ServersideOutput({"type": "store", "index": MATCH}, "data"),
     Output({"type": "dynamic-graph", "index": MATCH}, "figure"),