ephys-processing-listening.md

uid	title
ephys-process-listen	Process and Listen to Ephys Data

This tutorial shows you how to perform basic online signal processing of electrophysiology data in Bonsai such as channel selection/reordering, frequency filtering, and fixed-threshold spike detection as well as how to listen to ephys data using ONIX hardware and the OpenEphys.Onix1 Bonsai package.

Note

This tutorial serves primarily as an introduction to basic operations for processing electrophysiology data in Bonsai. These operations can also be performed in the Open Ephys GUI which provides advanced visualizations and built-in processing modules.

::: workflow :::

Tip

Although this tutorial uses headstage 64 as an example, the process is similar for other ephys headstages. This tutorial assumes you are familiar with the guide corresponding to the headstage you intend to use. This reference provides information about the xref:dataio and offset/scalar values as well as links to other documentation that pertain to your particular headstage.

Get Started in Bonsai

Follow the Getting Started guide to set up and familiarize yourself with Bonsai. In particular:

• Download the necessary Bonsai packages or check for updates if they're already installed. This tutorial assumes you're using the latest packages.
• Read about visualizing data. We recommend verifying each step of the tutorial by visualizing the data produced.

Configure the Hardware

Construct a top-level hardware configuration chain:

::: workflow :::

1. Place the configuration operators that corresponds 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.ConfigureBreakoutBoard and xref:OpenEphys.Onix1.ConfigureHeadstage64.
2. Confirm that the device that streams electrophysiology data is enabled. The Rhd2164 device (an Intan ephys acquisition acquisition chip) on the headstage 64 is the only device used in this tutorial, so you can disable other devices on the headstage and on the breakout board.

Stream Ephys Data into Bonsai

Place the relevant operators to stream electrophysiology data from your headstage:

::: workflow :::

1. We placed the xref:OpenEphys.Onix1.Rhd2164Data place into the workflow because the device on headstage 64 that streams electrophysiology data is the Rhd2164 Intan amplifier.
2. Select the relevant member from the data frames that Rhd2164Data produces. In this example, the relevant member is AmplifierData. To do this, right-click Rhd2164Data, hover over the output option in the context menu, and select "AmplifierData" from the list.

Visualize the raw data to confirm that the ephys data operator is streaming data.

Detect Spikes

Select and reorder channels

Connect a xref:Bonsai.Dsp.SelectChannels operator to the electrophysiology data stream and edit its "Channels" property:

::: workflow :::

• Remember indexing starts at 0.
• Reorder channels by listing the channel numbers in the order in which you want to visualize the channels.

Center the signal around zero

Connect a xref:Bonsai.Dsp.ConvertScale operator to the SelectChannels operator and set its properties:

::: workflow :::

• Edit its Shift property to subtract 2^bit depth - 1^ from the signal. In this example, we shift -32768 because the Rhd2164 device outputs unsigned 16-bit data. Use this reference to find the equivalent value for your hardware.
• Set the Depth property to S16 or F32. A sufficiently large data type is required to represent ephys data without overflow.

Scale the signal to microvolts

Connect a second ConvertScale to the first ConvertScale and set its properties:

::: workflow :::

• 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 bioacquisition device. In this example, we scale by 0.195 because the Rhd2164 device on headstage64 has a step size of 0.195 μV/bit. Use this reference to find the equivalent value for your hardware.
• Set the Depth property at F32 which is required to represent decimal values.

Visualize the transformed data to confirm the output of the shifting and scaling operations are performed 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 computations can be done with a single ConvertScale, the calculation is more straightforward using two operators connected in series because ConvertScale applies the "shift" transformation after applying the "scale" transformation. If we used a single operator, we would have to pre-scale the Shift property.

Apply a filter

Connect a FrequencyFilter operator to the second ConvertScale operator and set its properties:

::: workflow :::

• 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 band pass filter to look at spikes and remove slowly changing signals.
• Set the Cutoff1 and Cutoff2 properties to adequate values.

Visualize the filtered data to confirm that it matches your expectations.

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. Converting to microvolts with the second ConvertScale operator increases the size of your data (because it's converted to F32 from S16) without increasing meaningful information. Filtering with the FrequencyFilter operator before recording removes signal in irrecoverable ways. It's preferable to either save both or apply another filter when loading and processing the data.

Detect spikes with fixed threshold

::: workflow :::

Based on the amplitude of the signal on the selected channel, set a fixed threshold for detecting spikes.

Visualize the spike data.

Listen to Ephys

The output of AmplifierData can be directed into two separate signal processing streams. In other words, it is possible for two downstream operators to receive the same sequence of AmplifierDataFrames. This is helpful for creating two distinct disparate processes for the same data stream, one for visualizing spikes in several channels as we did above and one for listening to a single channel as follows.

Select a channel and process the signal for audio

::: workflow :::

The same basic steps as the Spike Detection section are performed. However, the property settings are critically different.

• Select a single channel for listening instead of multiple channels for detecting spikes.
• Use the second ConvertScale to scale the signal by a value between 0 and 1 to control the volume of the audio signal instead of scaling by 0.195 to convert to microvolts. This ConvertScale effectively serves as a volume knob.

Visualize the data and compare it at various points in the processing pipeline to confirm it matches your expectations.

Play ephys data as audio

::: workflow :::

Connect an AudioPlayback operator to FrequencyFilter and set its SampleRate property to 30000.

Providing data to AudioPlayback that is outside of the bounds of a signed 16 bit integer (-32,768 to +32,767) introduces clipping distortion into the audio signal, so it is recommended to maintain a Scale property value of less than 1 for the volume knob ConvertScale. Maximize other volume settings on your PC before exceeding 1.