Skip to content

Commit b9761e0

Browse files
cjshaChucklesOnGitHub
cjsha
and
ChucklesOnGitHub
authored
Content for spike detection tut (#143)
* Add content for ephys data processing tutorial, considering style for clarity --------- Co-authored-by: ChucklesOnGitHub <[email protected]>
1 parent 3acafaa commit b9761e0

21 files changed

+894
-24
lines changed

‎articles/getting-started/index.md

+7-6
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,11 @@ uid: getting-started
33
title: Getting Started
44
---
55

6-
Welcome to the user guide! The next few pages are dedicated to users who are unfamiliar with ONIX
7-
and Bonsai, and will teach them what ONIX is, how to download and install Bonsai, open a new file,
8-
place operators (and understand what an operator is), reorder a workflow, run a workflow, and
9-
finally visualize data.
6+
Welcome to the user guide! The next few pages are for users to learn how to use ONIX hardware using the OpenEphys.Onix1
7+
Bonsai package. Browse the articles in the table of contents to learn more.
108

11-
For those who are already familiar with Bonsai and ONIX and are looking for a particular device or headstage
12-
to learn about and how to utilize, visit the <xref:hardware>.
9+
This software documentation is intended to be used hand-in-hand with the
10+
[Hardware documentation](https://open-ephys.github.io/onix-docs/index.html) to learn about and start using their ONIX hardware.
11+
12+
For those who are looking for user guides and example workflows for using a particular device or headstage in Bonsai, visit
13+
the <xref:hardware>.

‎articles/getting-started/reference.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
uid: reference
3+
title: Software Reference
4+
---
5+
6+
The following table provides information about which operators correspond to which hardware and the "Shift" and "Scale"
7+
values to convert the ADC value to μV. For more information, refer to the
8+
[Basic Ephys Data Processing in Bonsai](xref:basic-ephys-processing).
9+
10+
| Hardware | Configuration Operator | Ephys Device | Ephys Data Operator | Data Frame | Shift | Scale |
11+
|----------------------------------|-------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|----------------------------------------------------|--------|--------------------|
12+
| 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 |
13+
| 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 |
14+
| 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$* |
15+
| 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 |
16+
| NeuropixelsV2eBeta<wbr>Headstage | <xref:OpenEphys.Onix1.ConfigureNeuropixelsV2eBetaHeadstage> | Neuropixels 2.0 Beta probe | <xref:OpenEphys.Onix1.NeuropixelsV2eBetaData> | <xref:OpenEphys.Onix1.NeuropixelsV2eBetaDataFrame> | -8192 | 0.7629 |
17+
18+
\* The Neuropixels 1.0 probes have selectable gain which has an effect on the multiplier for scaling the signal to μV,
19+
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
20+
[Configuration GUI](xref:np1e_gui) of that headstage.
21+

‎articles/getting-started/visualize-data.md

+74-4
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,79 @@ uid: visualize-data
33
title: Visualize Data
44
---
55

6-
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.
6+
Bonsai has ["type visualizers"](https://bonsai-rx.org/docs/articles/editor.html?#type-visualizers) that display data
7+
produced by an operator. They are opened by double-clicking the corresponding node while the workflow is running.
78

8-
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.
9+
Read below for more details about how to visualize data.
910

10-
> [!Note]
11-
> 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.
11+
## Selecting operator data members for visualization
12+
13+
Some operators, such as [ONIX data I/O operators](xref:dataio), require selecting members from their output to visualize
14+
their data:
15+
1. Right-click the node that corresponds to the data I/O operator you'd like to visualize.
16+
1. Hover the cursor over the "Output" option that appears in the context menu.
17+
1. Click the member you would like to visualize from the list of members.
18+
19+
This populates the workflow with a <xref:Bonsai.Expressions.MemberSelectorBuilder> operator that selects the single
20+
member from the data frame produced by the data I/O operator.
21+
22+
<video controls>
23+
<source src="../../images/select-member.mp4" type="video/mp4">
24+
</video>
25+
26+
> [!NOTE]
27+
> Member selection is required when an operator's output type doesn't have type visualizers that allow users to inspect
28+
> the data in a meaningful capacity. This is true for [ONIX data I/O operators](xref:dataio) which typically produce
29+
> [data frames](xref:data-elements).
30+
31+
## Selecting visualizers
32+
33+
Select the visualizer you would like to use for visualizing data:
34+
1. Right-click the `MemberSelector` node labelled with the member you would like to visualize.
35+
1. Hover the cursor over the "Select Visualizer" option in the context menu.
36+
1. Click the visualizer you would like to use from the list of visualizers.
37+
38+
<video controls>
39+
<source src="../../images/set-visualizer.mp4" type="video/mp4">
40+
</video>
41+
42+
## Opening visualizers
43+
44+
Open the visualizer and check:
45+
1. Start the workflow.
46+
1. If the desired visualizer is closed, double-click the `MemberSelector` node labelled with the member you would
47+
like to visualize.
48+
1. Visualize the data.
49+
50+
> [!NOTE]
51+
> Data will only be visualized if the operator is producing data. If you can't see any data, check that:
52+
> - The device from which you are trying to read is enabled.
53+
> - Events are occurring. Some devices are stream-based and some are event-based. Event-based devices only produce data upon certain
54+
> events. For example, the <xref:OpenEphys.Onix1.DigitalInput> operator only produces data when the digital
55+
> port status changes state.
56+
57+
> [!TIP]
58+
> Visualizers can be selected while the workflow is running which is helpful for more quickly trying different visualizer
59+
> options in succession if you are unsure about which one you want to use.
60+
61+
## Configuring visualizers
62+
Some visualizers, in particular those that involve plots, allow additional configuration.
63+
Right-click the visualizer window to gain access to configuration options.
64+
65+
For example, the MatVisualizer allows configuration of:
66+
- X and Y scale: click to toggle between "auto" and fixed values.
67+
- Channel view: click the grid square to toggle between superimposed or separate
68+
- History Length: click the arrow and configure the number of samples displayed in the plot.
69+
- Display Previous: click the arrow and configure the amount of buffers displayed in the plot.
70+
- Channel Offset: click the arrow and configure the Y offset.
71+
- 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.
72+
73+
<video controls>
74+
<source src="../../images/visualize-data.mp4" type="video/mp4">
75+
</video>
76+
77+
> [!TIP]
78+
> For other data visualization options, additional visualizers are available as standalone operators and can be found in
79+
> the `Bonsai.Design.Visualizers` package. These visualizer operators must be connected to an operator that produces a
80+
> sequence of compatible data. The visualizer window can be opened by double-clicking the visualizer node instead of the
81+
> preceding data node.

‎articles/hardware/index.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,5 @@ uid: hardware
33
title: Hardware Guides
44
---
55

6-
Here you will find user guides for the ONIX breakout board, headstages, and other compatible hardware that are supported by the library.
6+
Here you will find user guides and example workflows for the ONIX breakout board, headstages, and other compatible
7+
hardware that are supported by the library.

‎articles/toc.yml

+1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
- href: getting-started/initialize-oni-context.md
99
- href: getting-started/start-workflow.md
1010
- href: getting-started/visualize-data.md
11+
- href: getting-started/reference.md
1112

1213
- name: Hardware Guides
1314
href: hardware/index.md

‎articles/tutorials/basic-ephys-processing.md

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
uid: basic-ephys-processing
3+
title: Basic Ephys Data Processing in Bonsai
4+
---
5+
6+
This tutorial shows how to use ONIX hardware and the OpenEphys.Onix1 Bonsai package to perform basic online signal
7+
processing on electrophysiology data in Bonsai such as channel selection and reordering, frequency filtering and event
8+
detection (in this example, spike detection using a fixed threshold crossing).
9+
10+
This type of processing is helpful for visualizing data during acquisition and can be a starting point for more advanced
11+
workflows such as closed-loop experiments. For specialized data visualizations from very dense arrays like Neuropixels
12+
probes, for example, we recommend piping that data to the Open Ephys GUI.
13+
14+
<!-- Event detection in Bonsai will be faster and it allows actuation using ONIX or other hardware for closed-loop
15+
applications. However, more advanced event detection algorithms such as spike sorting, ripple detection, etc. need
16+
specific implementations in Bonsai. -->
17+
<!-- I'm not sure we need to discuss what this tutorial doesn't do -->
18+
19+
This tutorial guides you through building the following workflow:
20+
21+
::: workflow
22+
![/workflows/tutorials/basic-ephys-processing/spikes.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/spikes.bonsai)
23+
:::
24+
25+
> [!NOTE]
26+
> Although this tutorial uses headstage64 as an example, the process is similar for other ephys headstages. This
27+
> tutorial assumes you are familiar with the [hardware guide](xref:hardware) of the ONIX headstage you intend to use.
28+
> Use this [reference](xref:reference) for which ephys <xref:dataio> and scaling you need to use for each headstage, and links to relevant
29+
> documentation.
30+
31+
## Set up and get started in Bonsai
32+
33+
Follow the [Getting Started](xref:getting-started) guide to set up and get familiarized with Bonsai. In particular:
34+
35+
- [Download the necessary Bonsai packages](xref:install-configure-bonsai#install-packages-in-bonsai) or
36+
[check for updates](xref:install-configure-bonsai#update-packages-in-bonsai). This tutorial assumes
37+
you're using the latest software.
38+
- 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.
39+
40+
## Configure the hardware
41+
42+
::: workflow
43+
![/workflows/tutorials/basic-ephys-processing/configuration.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/configuration.bonsai)
44+
:::
45+
46+
Construct a [top-level hardware configuration chain](xref:initialize-onicontext):
47+
48+
1. Place the [configuration operators](xref:configure) that correspond to the hardware you intend to use between
49+
<xref:OpenEphys.Onix1.CreateContext> and <xref:OpenEphys.Onix1.StartAcquisition>. In this example, these are
50+
<xref:OpenEphys.Onix1.ConfigureHeadstage64> and <xref:OpenEphys.Onix1.ConfigureBreakoutBoard>.
51+
1. Confirm that the device that streams electrophysiology data is enabled. The Rhd2164 device (an Intan amplifier) on
52+
the headstage64 is the only device used in this tutorial, so you could disable other devices on the headstage and on the
53+
breakout board to improve performance if you wanted to.
54+
55+
## Stream ephys data into Bonsai
56+
57+
::: workflow
58+
![/workflows/tutorials/basic-ephys-processing/ephys-data.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/ephys-data.bonsai)
59+
:::
60+
61+
Place the relevant operators to stream electrophysiology data from your headstage:
62+
63+
1. Because the device on headstage64 that streams electrophysiology data is the Rhd2164 Intan amplifier, we placed the
64+
<xref:OpenEphys.Onix1.Rhd2164Data> node onto the workflow. Use this [reference](xref:reference) to find the ephys data operator
65+
that corresponds to each device.
66+
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
67+
the list.
68+
1. Visualize the raw data to confirm that the ephys data operator is streaming data.
69+
70+
## Select and reorder channels
71+
72+
::: workflow
73+
![/workflows/tutorials/basic-ephys-processing/select-convert-ephys-data.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/select-convert-ephys-data.bonsai)
74+
:::
75+
76+
Connect a <xref:Bonsai.Dsp.SelectChannels> operator to the electrophysiology data stream and edit its "Channels" property.
77+
78+
- Remember indexing in Bonsai starts at 0.
79+
- Use commas to list multiple channels and brackets for ranges.
80+
- Reorder channels by listing the channel numbers in the order in which you want to visualize the channels.
81+
82+
## Convert ephys data to microvolts
83+
84+
::: workflow
85+
![/workflows/tutorials/basic-ephys-processing/select-convert-ephys-data.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/select-convert-ephys-data.bonsai)
86+
:::
87+
88+
### Center the signal around zero
89+
Connect a <xref:Bonsai.Dsp.ConvertScale> operator to the `SelectChannels` operator and set its properties:
90+
- Edit its "Shift" property to subtract 2^bit depth - 1^ from the signal. Use this [reference](xref:reference) to find
91+
the Shift necessary for each device. In this example, we "Shift" -32768 because the Rhd2164 device outputs unsigned
92+
16-bit data.
93+
- Set the "Depth" property to F32 because this bit depth is required to correctly represent scaled data from all
94+
devices.
95+
96+
### Scale the signal to microvolts
97+
Connect a second `ConvertScale` operator to the first `ConvertScale` operator and set its properties:
98+
- Edit its "Scale" property to multiply the signal by a scalar in order to get microvolt values. This scalar is
99+
determined by the gain of the amplifier and resolution the ADC contained in the amplifier device. Use this
100+
[reference](xref:reference) to find the "Scale" necessary for each device. In this example, we "Scale" by 0.195 because
101+
the Rhd2164 device on headstage64 has a step size of 0.195&nbsp;μV/bit
102+
- Keep the "Depth" property at F32.
103+
104+
Visualize the transformed data to confirm the output of the shifting and scaling operations
105+
worked as expected, i.e. that the signal is centered around zero and that the values make sense in microvolts.
106+
107+
> [!NOTE]
108+
> Although both the Shift and Scale calculation can be done in one `ConvertScale` operator, the calculations are
109+
> more straightforward using two operators connected in series because the `ConvertScale` operator applies the
110+
> "Shift" offset after applying the "Scale" scalar so if we used a single operator, we would have to scale the Shift
111+
> parameter.
112+
113+
## Apply a filter
114+
115+
::: workflow
116+
![/workflows/tutorials/basic-ephys-processing/filter-ephys-data.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/filter-ephys-data.bonsai)
117+
:::
118+
119+
Connect a `FrequencyFilter` operator to the second `ConvertScale` operator and set its properties.
120+
- Set its "SampleRate" property to 30000. Ephys data in all devices is 30 kHz.
121+
- Set the "FilterType" property to an adequate type. In this example, we use a high pass filter to look at spikes.
122+
- Set the "Cutoff1" and "Cutoff2" properties to an adequate value. In this example, we use 300 Hz as the
123+
lower cutoff frequency.
124+
125+
Visualize the filtered data.
126+
127+
> [!TIP]
128+
> If you choose to save data, we recommend you place the `MatrixWriter` operator before filtering and scaling to save raw
129+
> 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.
130+
131+
## Detect events
132+
133+
::: workflow
134+
![/workflows/tutorials/basic-ephys-processing/spike-detection.bonsai workflow](../../workflows/tutorials/basic-ephys-processing/spike-detection.bonsai)
135+
:::
136+
137+
Based on the amplitude of the signal on the selected channel, set a fixed threshold for detecting spikes. <!-- discuss these details? -->
138+
139+
Visualize the spike data.
140+
141+
> [!TIP]
142+
> You can test the spike detection using a pre-recorded data known to have spikes: recreate the
143+
> 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
144+
> the `Rhd2164` node) with a `MatrixReader` that reads from the file containing spiking ephys data in unsigned 16-bit format.

‎articles/tutorials/index.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ uid: tutorials
33
title: Tutorials
44
---
55

6-
> [!Note]
7-
> This section will contains tutorials that demonstrate how to make the most of
8-
> the Bonsai library by combining ONIX with third party tools, tuning closed loop
9-
> response times, etc.
6+
This section contains tutorials that demonstrate how to make the most of
7+
the Bonsai library by combining ONIX with third party software tools
8+
9+
<!-- , tuning closed loop
10+
response times, etc.. -->

‎articles/tutorials/toc.yml

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
11
- href: index.md
2-
items:
2+
items: [
3+
href: basic-ephys-processing.md
4+
]

‎docfx.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@
4545
"attributes",
4646
"customcontainers",
4747
"footnotes",
48-
"figures"
48+
"figures",
49+
"emphasisextras"
4950
],
5051
"alerts": {
5152
"IMPORTANT": "alert alert-warning"

‎images/select-member.mp4

136 KB
Binary file not shown.

‎images/set-visualizer.mp4

140 KB
Binary file not shown.

‎images/visualize-data.mp4

428 KB
Binary file not shown.

‎template/public/main.css

+11-7
Original file line numberDiff line numberDiff line change
@@ -60,38 +60,42 @@ figcaption {
6060
padding: 0.25rem;
6161
}
6262

63-
h1 {
63+
/* h1 {
6464
font-weight: 500;
65-
/* originally font-size: calc(1.375rem + 1.5vw) */
6665
font-size: calc(2.2rem + 0.8vw);
6766
}
6867
6968
h2 {
7069
font-weight: 480;
71-
/* originally font-size: calc(1.325rem + .9vw) */
7270
font-size: calc(2.0rem + 0.6vw);
7371
}
7472
7573
h3 {
7674
font-weight: 460;
77-
/* originally font-size calc(1.3 + 0.6vw); */
7875
font-size: calc(1.8rem + 0.4vw);
7976
}
8077
8178
h4 {
8279
font-weight: 440;
83-
/* originally font-size calc(1.275 + 0.3vw); */
8480
font-size: calc(1.6rem + 0.2vw);
8581
}
8682
8783
h5 {
8884
font-weight: 420;
89-
/* originally font-size: 1.25rem */
9085
font-size: 1.4rem;
9186
}
9287
9388
h6 {
9489
font-weight: 400;
95-
/* originally font-size: 1rem; */
9690
font-size: 1.2rem;
91+
} */
92+
93+
/* This is for formatting markdown files specifically */
94+
95+
ol ol, ol ul {
96+
margin-bottom: 1rem
97+
}
98+
99+
ol li div {
100+
margin-bottom: 0rem !important
97101
}

0 commit comments

Comments
 (0)