Multichannel Timeseries (#418)

multichannel_timeseries/anaconda-project.yml

@@ -0,0 +1,89 @@
+name: multichannel_timeseries
+description: Display and annotate multichannel timeseries data in Neuroscience
+
+examples_config:
+  created: 2024-11-20
+  maintainers:
+  - "droumis"
+  labels:
+  - "hvplot"
+  - "panel"
+  - "holoviews"
+  - "datashader"
+  - "holonote"
+  categories:
+  - Neuroscience
+  title: "Multichannel Timeseries"
+  deployments:
+  - command: notebook
+  - command: dashboard
+    resource_profile: default
+    auto_deploy: true
+  notebooks_to_skip: []
+  skip_notebooks_evaluation: false
+  no_data_ingestion: false
+  gh_runner: "ubuntu-latest"
+
+user_fields: [examples_config]
+
+channels:
+- conda-forge
+- nodefaults
+
+packages: &pkgs
+- notebook>=6.5.2,<7 # required
+- python=3.11
+- numpy>=2.0.2 # auto min pinned 2024-11-18
+- panel>=1.4.2
+- hvplot>=0.10.0
+- pandas>=2.2.1
+- holoviews>=1.19.0 # 1.19: wide df handling, scalebars
+- datashader>=0.16.3 # auto min pinned 2024-11-18
+- xarray>=2024.5.0,<2024.10.0 # datatree merged into xarray 2024.10.0
+- zarr>=2.18.3 # auto min pinned 2024-11-18
+- pyarrow>=18.0.0 # auto min pinned 2024-11-18
+- dask>=2024.11.2 # auto min pinned 2024-11-18
+- h5py>=3.12.1 # auto min pinned 2024-11-18
+- mne-lsl>=1.6.1 # auto min pinned 2024-11-18
+- jupyterlab>=4.3.0 # auto min pinned 2024-11-18
+- holonote>=0.2.1 # 0.2.1: visibility and coloring fixes
+- pyproj==3.6.1
+- bokeh>=3.6.0 # 3.6.0: scalebar on subplots
+- ndpyramid==0.2.0 # avoid HybridMappingProxy error in 0.3.1
+- pooch>=1.8.2 # auto min pinned 2024-11-18
+- pip
+- pip:
+  - tsdownsample>=0.1.3
+  - mne[hdf5]>=1.8.0 # auto min pinned 2024-11-18 # pip instead of conda to avoid missing io module error
+
+dependencies: *pkgs
+
+commands:
+  lab:
+    unix: jupyter lab index.ipynb
+    windows: jupyter lab index.ipynb
+  notebook:
+    notebook: index.ipynb
+  dashboard:
+    unix: panel serve --rest-session-info --session-history -1 multichan.ipynb --show
+    supports_http_options: true
+
+variables: {}
+
+downloads:
+  EEG_data:
+    url: https://datasets.holoviz.org/eeg/v1/S001R04.edf
+    description: |
+      EEG Dataset
+    filename: data/S001R04.edf
+  LFP_data:
+    url: https://datasets.holoviz.org/lfp/v1/sub-719828686_ses-754312389_probe-756781563_ecephys.nwb
+    description: |
+      Ephys NWB Dataset https://datasets.holoviz.org/lfp/README.md
+    filename: data/sub-719828686_ses-754312389_probe-756781563_ecephys.nwb
+
+platforms:
+- linux-64
+- osx-64
+- win-64
+- osx-arm64

multichannel_timeseries/index.ipynb

@@ -0,0 +1,143 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Multichannel Timeseries\n",
+    "\n",
+    "## Introduction\n",
+    "\n",
+    "Visualizing time series from various sources on a vertically stacked, time-aligned display is often the first tool employed when working with data from [electrophysiological](https://en.wikipedia.org/wiki/Electrophysiology) studies. These experiments generally seek to provide insight into the activities of nerve cells or muscles, as well as how they relate to each other or other measurable variables, such as the spatial position of the organism under study. Electrophysiological recording sessions can include diverse data types like electromyograms (EMG), electroencephalograms (EEG), local field potentials (LFP), or neural action potentials (spikes) - each consisting of multiple streams of information ('channels') that all are unified by their alignment to a single series of timestamps, but having a heterogenuous range of amplitude values.\n",
+    "\n",
+    "There are many different approaches for a visualization of multichannel timeseries data, but we'll highlight the one that we've found to be promising in many scenarios. If you have a dataset that is too large to fit into memory, check out the alternate approaches in the 'Extensions and Alternate Workflows' below the Recommended Workflow."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "___"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Key Features\n",
+    "Analyzing electrophysiological data often involves searching for patterns across time, channels, and covariates. Target features that support this type of investigation for time-aligned, amplitude-diverse data include:\n",
+    "\n",
+    "- **Smooth Interactions at Scale:** Smooth zooming and panning across time and channels.\n",
+    "- **Subcoordinate Axes:** Independent amplitude dimension (y-axis) per channel.\n",
+    "- **Instant Inspection:** Quick information preview about the data under the cursor.\n",
+    "- **Group-Aware Handling:** Zooming and y-range normalization per specified channel group/type.\n",
+    "- **Reference View:** Minimap for navigation and contextualization in large datasets.\n",
+    "- **Responsive Scale Bar:** Dynamic amplitude reference measurement.\n",
+    "- **Time-Range Annotations:** Create and edit time-range annotations directly on the plot."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 👉 [Recommended Workflow](./0_multichan.ipynb) (Start Here)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src='./assets/240927_multichan.png' alt=\"Multichannel timeseries recommended workflows\" align=\"right\" width=75%>\n",
+    "\n",
+    "The [recommended multichannel timeseries notebook](./0_multichan.ipynb) provides a workflow for processing and analyzing multichannel timeseries **datasets that fit in memory**.\n",
+    "\n",
+    "It covers the importance of live downsampling using algorithms that maintain the signal shape and optimize browser performance.\n",
+    "\n",
+    "Although it features the MNE-Python library for handling and visualization of raw EEG data, the concepts and methods are applicable to various timeseries data beyond EEG.\n",
+    "\n",
+    "<div style=\"clear: both;\"></div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Extensions and Alternate Workflows"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "| Title | Preview | Type | Summary | Details |\n",
+    "|---|---|---|---|---|\n",
+    "| [Minimap Widget](./0_multichan.ipynb#Minimap-Extension) | <img src=\"./thumbnails/minimap.png\" alt=\"Minimap\" width=\"500\"> | Extension | Use HoloViews RangeToolLink and Datashader to rasterize an aggregate view. | Create a minimap widget that provides a condensed overview of the entire dataset, allowing users to select and zoom into areas of interest quickly in the main plot while maintaining the contextualization of the zoomed out view. |\n",
+    "| [Time Range Annotation](./0_multichan.ipynb#Time-Range-Annotation-Extension) | <img src=\"./thumbnails/annotation.png\" alt=\"annotation\" width=\"500\"> | Extension | Utilize HoloNote along with any primary workflow approach. | Create (or import), edit, and save a table of start and end times. View the categorized ranges overlaid on the multichannel timeseries plot. HoloNote allows you to interact with time range annotations directly on a plot, through widgets, or programmatically. |\n",
+    "| [Standalone App](./0_multichan.ipynb#Standalone-App-Extension) | <img src=\"./thumbnails/standalone.png\" alt=\"Standalone App\" width=\"500\"> | Extension | Deploy the visualization as a standalone, template-styled web application using HoloViz Panel.  | This extension shows how to wrap your plot within a Panel Template for a styled, interactive web app that can run outside of a Jupyter Notebook. By marking the Panel component as servable, you can launch the app directly from the command line, providing a user-friendly interface in its own browser window. |\n",
+    "| [Scale Bar](./0_multichan.ipynb#scale-bar-extension) | <img src=\"./thumbnails/scalebar.png\" alt=\"Scale Bar\" width=\"500\"> | Extension | Provides an accurate, dynamic, and customizable reference gauge of signal amplitude. | The scale bar feature in HoloViews+Bokeh allows for precise measurement indicators on plots. Requires Bokeh>=3.6.0 and HoloViews>=1.19.2 |\n",
+    "| **[Larger Dataset <br> (> RAM)](./1_large_multichan.ipynb)** | <img src=\"./thumbnails/large_multichan.png\" alt=\"Larger Dataset\" width=\"500\"> | **Alternate Workflow** | Utilize Xarray, Zarr, and Dask for dynamic access of data subsets at optimal resolution. | To handle datasets beyond available memory (RAM), we can utilize dynamic access of certain data ranges and resolutions, using a precomputed hierarchical array pyramid. |\n",
+    "| [Pyramid Level Widget](./1_large_multichan.ipynb#Pyramid-Indicator-Extesion) | <img src=\"./thumbnails/pyramid_level.png\" alt=\"Pyramid Level\" width=\"500\"> | Extension | Indicator for the active Pyramid Level | Use a custom HoloViews Stream to update the indicator styling of the different resolution levels of the data |  \n",
+    " "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Funding:\n",
+    "\n",
+    "- 2023 - 2024: Chan Zuckerberg Initiative. Learn more in the [grant announcement](https://blog.bokeh.org/announcing-czi-funding-for-bokeh-for-bioscience-5f74426c011a).\n",
+    "  - Project Lead: Demetris Roumis, PhD (@droumis on [HoloViz Discord](https://discord.gg/X6Eq9CvZZn))\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}