Content for spike detection tut (#143)

* Add content for ephys data processing tutorial, considering style for clarity --------- Co-authored-by: ChucklesOnGitHub <[email protected]>
open-ephys · Nov 13, 2024 · b9761e0 · b9761e0
1 parent 3acafaa
commit b9761e0
Show file tree

Hide file tree

Showing 21 changed files with 894 additions and 24 deletions.
diff --git a/articles/getting-started/index.md b/articles/getting-started/index.md
@@ -3,10 +3,11 @@ uid: getting-started
 title: Getting Started
 ---
 
-Welcome to the user guide! The next few pages are dedicated to users who are unfamiliar with ONIX
-and Bonsai, and will teach them what ONIX is, how to download and install Bonsai, open a new file,
-place operators (and understand what an operator is), reorder a workflow, run a workflow, and
-finally visualize data.
+Welcome to the user guide! The next few pages are for users to learn how to use ONIX hardware using the OpenEphys.Onix1
+Bonsai package. Browse the articles in the table of contents to learn more.
 
-For those who are already familiar with Bonsai and ONIX and are looking for a particular device or headstage
-to learn about and how to utilize, visit the <xref:hardware>.
+This software documentation is intended to be used hand-in-hand with the 
+[Hardware documentation](https://open-ephys.github.io/onix-docs/index.html) to learn about and start using their ONIX hardware. 
+
+For those who are looking for user guides and example workflows for using a particular device or headstage in Bonsai, visit
+the <xref:hardware>.
diff --git a/articles/getting-started/reference.md b/articles/getting-started/reference.md
@@ -0,0 +1,21 @@
+---
+uid: reference
+title: Software Reference
+---
+
+The following table provides information about which operators correspond to which hardware and the "Shift" and "Scale"
+values to convert the ADC value to μV. For more information, refer to the 
+[Basic Ephys Data Processing in Bonsai](xref:basic-ephys-processing).
+
+| Hardware                         | Configuration Operator                                      | Ephys Device                                                                                                     | Ephys Data Operator                           | Data Frame                                         | Shift  | Scale              |
+|----------------------------------|-------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|----------------------------------------------------|--------|--------------------|
+| Headstage64                      | <xref:OpenEphys.Onix1.ConfigureHeadstage64>                 | [Intan Rhd2164 (amplifier channels)](https://intantech.com/files/Intan_RHD2164_datasheet.pdf)                    | <xref:OpenEphys.Onix1.Rhd2164Data>            | <xref:OpenEphys.Onix1.Rhd2164DataFrame>            | -32768 | 0.195              |
+| HeadstageRhs2116                 | <xref:OpenEphys.Onix1.ConfigureHeadstageRhs2116>            | [Intan Rhs2116](https://intantech.com/files/Intan_RHS2116_datasheet.pdf)                                         | <xref:OpenEphys.Onix1.Rhs2116Data>            | <xref:OpenEphys.Onix1.Rhs2116DataFrame>            | -32768 | 0.195              |
+| NeuropixelsV1e<wbr>Headstage     | <xref:OpenEphys.Onix1.ConfigureNeuropixelsV1eHeadstage>     | [Neuropixels 1.0 probe (AP)](https://www.neuropixels.org/_files/ugd/328966_c5e4d31e8a974962b5eb8ec975408c9f.pdf) | <xref:OpenEphys.Onix1.NeuropixelsV1eData>     | <xref:OpenEphys.Onix1.NeuropixelsV1DataFrame>      | -512   | $1.2e6/1024/gain$* |
+| NeuropixelsV2e<wbr>Headstage     | <xref:OpenEphys.Onix1.ConfigureNeuropixelsV2eHeadstage>     | [Neuropixels 2.0 probe](https://www.neuropixels.org/_files/ugd/328966_2b39661f072d405b8d284c3c73588bc6.pdf)      | <xref:OpenEphys.Onix1.NeuropixelsV2eData>     | <xref:OpenEphys.Onix1.NeuropixelsV2eDataFrame>     | -2048  | 3.05176            |
+| NeuropixelsV2eBeta<wbr>Headstage | <xref:OpenEphys.Onix1.ConfigureNeuropixelsV2eBetaHeadstage> | Neuropixels 2.0 Beta probe                                                                                       | <xref:OpenEphys.Onix1.NeuropixelsV2eBetaData> | <xref:OpenEphys.Onix1.NeuropixelsV2eBetaDataFrame> | -8192  | 0.7629             |
+
+\* The Neuropixels 1.0 probes have selectable gain which has an effect on the multiplier for scaling the signal to μV,
+so the $1.2e6/1024/gain$ formula must be used to calculate the correct "Scale" value. The Gain is set by the user in the
+[Configuration GUI](xref:np1e_gui) of that headstage.
+
diff --git a/articles/getting-started/visualize-data.md b/articles/getting-started/visualize-data.md
@@ -3,9 +3,79 @@ uid: visualize-data
 title: Visualize Data
 ---
 
-To visualize data from any `*Data` operator, typically the variable that needs to be visualized must first be output from the operator. To do this, right-click on any `*Data` operator and select the first option; this will be something similar to `Output (OpenEphys.Onix1.*DataFrame)`. From the drop-down list, select the corresponding data variable to be visualized. Doing so will create a new operator in the workflow.
+Bonsai has ["type visualizers"](https://bonsai-rx.org/docs/articles/editor.html?#type-visualizers) that display data
+produced by an operator. They are opened by double-clicking the corresponding node while the workflow is running.
 
-Select this new operator and right-click it, search for the **Select Visualizer** option and choose a visualizer from that drop-down menu. Note that some data types will require a secondary operator to be connected directly after it, such as a `RollingGraph` operator. If so, this secondary operator must be right-clicked and the appropriate visualizer must be selected here.
+Read below for more details about how to visualize data.
 
-> [!Note]
-> Some visualizers come as Bonsai operators and can be found in the `Bonsai.Design.Visualizers` package, which can be installed in the Bonsai package manager. These operators must be placed in the workflow and be linked to a data operator to visualize the data properly.
+## Selecting operator data members for visualization
+
+Some operators, such as [ONIX data I/O operators](xref:dataio), require selecting members from their output to visualize
+their data:  
+  1. Right-click the node that corresponds to the data I/O operator you'd like to visualize.
+  1. Hover the cursor over the "Output" option that appears in the context menu.
+  1. Click the member you would like to visualize from the list of members.
+
+This populates the workflow with a <xref:Bonsai.Expressions.MemberSelectorBuilder> operator that selects the single
+member from the data frame produced by the data I/O operator.
+
+<video controls>
+  <source src="../../images/select-member.mp4" type="video/mp4">
+</video> 
+
+> [!NOTE]
+> Member selection is required when an operator's output type doesn't have type visualizers that allow users to inspect
+> the data in a meaningful capacity. This is true for [ONIX data I/O operators](xref:dataio) which typically produce 
+> [data frames](xref:data-elements).
+
+## Selecting visualizers
+
+Select the visualizer you would like to use for visualizing data:
+  1. Right-click the `MemberSelector` node labelled with the member you would like to visualize.
+  1. Hover the cursor over the "Select Visualizer" option in the context menu.
+  1. Click the visualizer you would like to use from the list of visualizers.
+
+<video controls>
+  <source src="../../images/set-visualizer.mp4" type="video/mp4">
+</video> 
+
+## Opening visualizers
+
+Open the visualizer and check:
+  1. Start the workflow.
+  1. If the desired visualizer is closed, double-click the `MemberSelector` node labelled with the member you would
+     like to visualize.
+  1. Visualize the data.     
+
+  > [!NOTE]
+  > Data will only be visualized if the operator is producing data. If you can't see any data, check that:
+  > - The device from which you are trying to read is enabled.
+  > - Events are occurring. Some devices are stream-based and some are event-based. Event-based devices only produce data upon certain
+  >   events. For example, the <xref:OpenEphys.Onix1.DigitalInput> operator only produces data when the digital
+  >   port status changes state.
+
+  > [!TIP] 
+  > Visualizers can be selected while the workflow is running which is helpful for more quickly trying different visualizer
+  > options in succession if you are unsure about which one you want to use.
+
+## Configuring visualizers
+Some visualizers, in particular those that involve plots, allow additional configuration.
+Right-click the visualizer window to gain access to configuration options.
+
+  For example, the MatVisualizer allows configuration of:
+  - X and Y scale: click to toggle between "auto" and fixed values.
+  - Channel view: click the grid square to toggle between superimposed or separate  
+  - History Length: click the arrow and configure the number of samples displayed in the plot. 
+  - Display Previous: click the arrow and configure the amount of buffers displayed in the plot. 
+  - Channel Offset: click the arrow and configure the Y offset.
+  - Channels per Page: click the arrow and configure the amount of channels displayed per visualizer page. The page number is displayed at the top of the visualizer. Move between pages by using the PageUp and PageDn keys on the keyboard. 
+
+<video controls>
+  <source src="../../images/visualize-data.mp4" type="video/mp4">
+</video> 
+
+> [!TIP]
+> For other data visualization options, additional visualizers are available as standalone operators and can be found in
+> the `Bonsai.Design.Visualizers` package. These visualizer operators must be connected to an operator that produces a
+> sequence of compatible data. The visualizer window can be opened by double-clicking the visualizer node instead of the
+> preceding data node.
diff --git a/articles/hardware/index.md b/articles/hardware/index.md
@@ -3,4 +3,5 @@ uid: hardware
 title: Hardware Guides
 ---
 
-Here you will find user guides for the ONIX breakout board, headstages, and other compatible hardware that are supported by the library.
+Here you will find user guides and example workflows for the ONIX breakout board, headstages, and other compatible
+hardware that are supported by the library.
diff --git a/articles/toc.yml b/articles/toc.yml
@@ -8,6 +8,7 @@
   - href: getting-started/initialize-oni-context.md
   - href: getting-started/start-workflow.md
   - href: getting-started/visualize-data.md
+  - href: getting-started/reference.md
 
 - name: Hardware Guides
   href: hardware/index.md

diff --git a/articles/tutorials/basic-ephys-processing.md b/articles/tutorials/basic-ephys-processing.md
@@ -0,0 +1,144 @@
+---
+uid: basic-ephys-processing
+title: Basic Ephys Data Processing in Bonsai
+---
+
+This tutorial shows how to use ONIX hardware and the OpenEphys.Onix1 Bonsai package to perform basic online signal
+processing on electrophysiology data in Bonsai such as channel selection and reordering, frequency filtering and event
+detection (in this example, spike detection using a fixed threshold crossing).
+
+This type of processing is helpful for visualizing data during acquisition and can be a starting point for more advanced
+workflows such as closed-loop experiments. For specialized data visualizations from very dense arrays like Neuropixels
+probes, for example, we recommend piping that data to the Open Ephys GUI.
+
+<!-- Event detection in Bonsai will be faster and it allows actuation using ONIX or other hardware for closed-loop
+applications. However, more advanced event detection algorithms such as spike sorting, ripple detection, etc. need
+specific implementations in Bonsai. -->
+<!-- I'm not sure we need to discuss what this tutorial doesn't do -->
+
+This tutorial guides you through building the following workflow: 
+
+::: workflow
+![/workflows/tutorials/basic-ephys-processing/spikes.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/spikes.bonsai)
+:::
+
+> [!NOTE]
+> Although this tutorial uses headstage64 as an example, the process is similar for other ephys headstages. This
+> tutorial assumes you are familiar with the [hardware guide](xref:hardware) of the ONIX headstage you intend to use.
+> Use this [reference](xref:reference) for which ephys <xref:dataio> and scaling you need to use for each headstage, and links to relevant
+> documentation. 
+
+## Set up and get started in Bonsai
+
+Follow the [Getting Started](xref:getting-started) guide to set up and get familiarized with Bonsai. In particular:
+
+- [Download the necessary Bonsai packages](xref:install-configure-bonsai#install-packages-in-bonsai) or 
+[check for updates](xref:install-configure-bonsai#update-packages-in-bonsai). This tutorial assumes 
+you're using the latest software.
+- Read about [visualizing data](xref:visualize-data) since we recommend checking each step of the tutorial by visualizing the data produced but we don't cover it here.
+
+## Configure the hardware
+
+::: workflow
+![/workflows/tutorials/basic-ephys-processing/configuration.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/configuration.bonsai)
+:::
+
+Construct a [top-level hardware configuration chain](xref:initialize-onicontext): 
+
+1. Place the [configuration operators](xref:configure) that correspond to the hardware you intend to use between
+<xref:OpenEphys.Onix1.CreateContext> and <xref:OpenEphys.Onix1.StartAcquisition>. In this example, these are
+<xref:OpenEphys.Onix1.ConfigureHeadstage64> and <xref:OpenEphys.Onix1.ConfigureBreakoutBoard>.
+1. Confirm that the device that streams electrophysiology data is enabled. The Rhd2164 device (an Intan amplifier) on
+the headstage64 is the only device used in this tutorial, so you could disable other devices on the headstage and on the
+breakout board to improve performance if you wanted to.
+
+## Stream ephys data into Bonsai
+
+::: workflow
+![/workflows/tutorials/basic-ephys-processing/ephys-data.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/ephys-data.bonsai)
+:::
+
+Place the relevant operators to stream electrophysiology data from your headstage:
+
+1. Because the device on headstage64 that streams electrophysiology data is the Rhd2164 Intan amplifier, we placed the
+<xref:OpenEphys.Onix1.Rhd2164Data> node onto the workflow. Use this [reference](xref:reference) to find the ephys data operator
+that corresponds to each device.
+1. Select the relevant members from the data frames that the data operator produces. In this example, the relevant members are "AmplifierData" and "Clock". To select those members, right-click the `Rhd2164` node, hover over the output option in the context menu, and select it from
+the list.
+1. Visualize the raw data to confirm that the ephys data operator is streaming data. 
+
+## Select and reorder channels
+
+::: workflow
+![/workflows/tutorials/basic-ephys-processing/select-convert-ephys-data.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/select-convert-ephys-data.bonsai)
+:::
+
+Connect a <xref:Bonsai.Dsp.SelectChannels> operator to the electrophysiology data stream and edit its "Channels" property.
+
+- Remember indexing in Bonsai starts at 0.
+- Use commas to list multiple channels and brackets for ranges.
+- Reorder channels by listing the channel numbers in the order in which you want to visualize the channels.
+
+## Convert ephys data to microvolts
+
+::: workflow
+![/workflows/tutorials/basic-ephys-processing/select-convert-ephys-data.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/select-convert-ephys-data.bonsai)
+:::
+
+### Center the signal around zero
+Connect a <xref:Bonsai.Dsp.ConvertScale> operator to the `SelectChannels` operator and set its properties:
+- Edit its "Shift" property to subtract 2^bit depth - 1^ from the signal. Use this [reference](xref:reference) to find
+the Shift necessary for each device. In this example, we "Shift" -32768 because the Rhd2164 device outputs unsigned
+16-bit data.
+- Set the "Depth" property to F32 because this bit depth is required to correctly represent scaled data from all
+devices.
+
+### Scale the signal to microvolts
+Connect a second `ConvertScale` operator to the first `ConvertScale` operator and set its properties:
+- Edit its "Scale" property to multiply the signal by a scalar in order to get microvolt values. This scalar is
+determined by the gain of the amplifier and resolution the ADC contained in the amplifier device. Use this 
+[reference](xref:reference) to find the "Scale" necessary for each device. In this example, we "Scale" by 0.195 because
+the Rhd2164 device on headstage64 has a step size of 0.195&nbsp;μV/bit
+- Keep the "Depth" property at F32.
+
+Visualize the transformed data to confirm the output of the shifting and scaling operations
+worked as expected, i.e. that the signal is centered around zero and that the values make sense in microvolts.
+
+> [!NOTE]
+> Although both the Shift and Scale calculation can be done in one `ConvertScale` operator, the calculations are
+> more straightforward using two operators connected in series because the `ConvertScale` operator applies the
+> "Shift" offset after applying the "Scale" scalar so if we used a single operator, we would have to scale the Shift
+> parameter.
+
+## Apply a filter
+
+::: workflow
+![/workflows/tutorials/basic-ephys-processing/filter-ephys-data.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/filter-ephys-data.bonsai)
+:::
+
+Connect a `FrequencyFilter` operator to the second `ConvertScale` operator and set its properties.
+- Set its "SampleRate" property to 30000. Ephys data in all devices is 30 kHz.
+- Set the "FilterType" property to an adequate type. In this example, we use a high pass filter to look at spikes.
+- Set the "Cutoff1" and "Cutoff2" properties to an adequate value. In this example, we use 300 Hz as the
+    lower cutoff frequency. 
+
+Visualize the filtered data.
+
+> [!TIP] 
+> If you choose to save data, we recommend you place the `MatrixWriter` operator before filtering and scaling to save raw
+> data instead of scaled or filtered data. Filtering with the `FrequencyFilter` operator before recording could remove signals from a bandwidth of interest and converting to microvolts with the second `ConvertScale` operator could increase the size of your data without increasing meaningful information.
+
+## Detect events
+
+::: workflow
+![/workflows/tutorials/basic-ephys-processing/spike-detection.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/spike-detection.bonsai)
+:::
+
+Based on the amplitude of the signal on the selected channel, set a fixed threshold for detecting spikes. <!-- discuss these details? -->
+
+Visualize the spike data.
+
+> [!TIP] 
+> You can test the spike detection using a pre-recorded data known to have spikes: recreate the
+> workflow from this example without the hardware configuration chain in a new workflow and replace the ephys data node (in the case of the headstage64, replace
+> the `Rhd2164` node) with a `MatrixReader` that reads from the file containing spiking ephys data in unsigned 16-bit format.
diff --git a/articles/tutorials/index.md b/articles/tutorials/index.md
@@ -3,7 +3,8 @@ uid: tutorials
 title: Tutorials
 ---
 
-> [!Note]
-> This section will contains tutorials that demonstrate how to make the most of
-> the Bonsai library by combining ONIX with third party tools, tuning closed loop
-> response times, etc.
+This section contains tutorials that demonstrate how to make the most of
+the Bonsai library by combining ONIX with third party software tools
+
+<!-- , tuning closed loop
+response times, etc.. -->
diff --git a/articles/tutorials/toc.yml b/articles/tutorials/toc.yml
@@ -1,2 +1,4 @@
 - href: index.md
-  items: 
+  items: [
+    href: basic-ephys-processing.md
+  ]
diff --git a/docfx.json b/docfx.json
@@ -45,7 +45,8 @@
         "attributes",
         "customcontainers",
         "footnotes",
-        "figures"
+        "figures",
+        "emphasisextras"
       ],
       "alerts": {
         "IMPORTANT": "alert alert-warning"

diff --git a/images/select-member.mp4 b/images/select-member.mp4
diff --git a/images/set-visualizer.mp4 b/images/set-visualizer.mp4
diff --git a/images/visualize-data.mp4 b/images/visualize-data.mp4
diff --git a/template/public/main.css b/template/public/main.css
@@ -60,38 +60,42 @@ figcaption {
   padding: 0.25rem;
 }
 
-h1 {
+/* h1 {
   font-weight: 500;
-  /* originally font-size: calc(1.375rem + 1.5vw) */
   font-size: calc(2.2rem + 0.8vw);
 }
 
 h2 {
   font-weight: 480;
-  /* originally font-size: calc(1.325rem + .9vw) */
   font-size: calc(2.0rem + 0.6vw);
 }
 
 h3 {
   font-weight: 460;
-  /* originally font-size calc(1.3 + 0.6vw); */
   font-size: calc(1.8rem + 0.4vw);
 }
 
 h4 {
   font-weight: 440;
-  /* originally font-size calc(1.275 + 0.3vw); */
   font-size: calc(1.6rem + 0.2vw);
 }
 
 h5 {
   font-weight: 420;
-  /* originally font-size: 1.25rem */
   font-size: 1.4rem;
 }
 
 h6 {
   font-weight: 400;
-  /* originally font-size: 1rem; */
   font-size: 1.2rem;
+} */
+
+/* This is for formatting markdown files specifically */
+
+ol ol, ol ul {
+  margin-bottom: 1rem
+}
+
+ol li div {
+  margin-bottom: 0rem !important
 }