Skip to content

Commit c6e21cf

Browse files
jonnewjonnew
committed
Review socket tutorial
- Tried to streamline and clarify text - Please replace the first image with something that summarizes the end result of the tutorial
1 parent bb42e93 commit c6e21cf

File tree

6 files changed

+148
-115
lines changed

6 files changed

+148
-115
lines changed

‎articles/tutorials/ephys-socket.md

Lines changed: 138 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -3,117 +3,141 @@ uid: ephys-socket
33
title: Visualizing Data in the Open Ephys GUI
44
---
55

6-
This tutorial shows how to stream data from ONIX hardware in Bonsai and visualize it in the Open
7-
Ephys GUI through an intermediary TCP connection. This approach lets users take advantage of both
8-
the extensibility of Bonsai and specialized visualizers available in the Open Ephys GUI such as the
9-
Probe Viewer which is specifically designed for very dense arrays like Neuropixels probes. By the
10-
end of this tutorial, you will have a workflow that transmits two data streams from a NeuropixelsV1e
11-
probe (384 channels of LFP band and AP band data) and an Open Ephys GUI signal chain that receives
12-
and visualizes the two data streams in the Open Ephys GUI:
13-
14-
::: workflow
15-
![SVG of copyable functional workflow](../../workflows/tutorials/ephys-socket/ephys-socket.bonsai)
16-
:::
6+
This tutorial shows how to stream ephys data from Bonsai the Open Ephys
7+
GUIthrough an intermediary TCP connection. This approach lets users take
8+
advantage of both the extensibility of Bonsai and specialized visualizers
9+
available in the Open Ephys GUI such as the Probe Viewer which is specifically
10+
designed for very dense arrays like Neuropixels probes. By the end of this
11+
tutorial, you will have a workflow that transmits two data streams from a
12+
NeuropixelsV1e headstage (384 channels of LFP band and AP band data) and an Open
13+
Ephys GUI signal chain that receives and visualizes the two data streams in the
14+
Open Ephys GUI:
1715

1816
![screenshot of socket signal chain viewport](../../images/ephys-socket-tut/socket-viewport.webp)
1917

2018
Click <a href="../../workflows/tutorials/ephys-socket/sockets-signal-chain" download>here</a> to
2119
download the signal chain that corresponds to the above graph.
2220

23-
> [!NOTE]
24-
> This tutorial uses NeuropixelsV1e Headstage as an example, but the process is similar for
25-
> other ephys headstages. This tutorial assumes you are familiar with the [hardware
26-
> guide](xref:hardware) of the ONIX headstage you intend to use. Use the information on the
27-
> <xref:data-elements> reference page to know which shift and scaling you need to use for each
28-
> device on other headstages.
29-
30-
A video demonstration is available at the bottom of this page.
31-
32-
## Transmit ONIX Data to Socket in Bonsai
33-
34-
Follow the [Getting Started](xref:getting-started) guide to set up and familiarize yourself with
35-
Bonsai. In particular, [download the necessary Bonsai packages](xref:install-configure-bonsai#package-installation)
36-
or [check for updates](xref:install-configure-bonsai#update-packages) if they're already installed.
21+
> [!NOTE]
22+
> This tutorial uses NeuropixelsV1e Headstage as an example, but the process is
23+
> similar for other ephys headstages. In fact, this tutorial can be used to send
24+
> data from any Bonsai operator that produces an applies to any data source that
25+
> produces matrices (`OpenCV.NET.Mat`s).
26+
>
27+
> This tutorial assumes you are familiar with the [hardware
28+
> guide](xref:hardware) of the ONIX headstage you intend to use. Use the
29+
> information on the <xref:data-elements> reference page to know which shift and
30+
> scaling you need to use for each device on other headstages.
31+
>
32+
> A [video summary](#video-summary) of this tutorial is is available at the
33+
> bottom of this page.
34+
35+
## Transmit Ephys Data to a TCP Server in Bonsai
36+
37+
Follow the [Getting Started](xref:getting-started) guide to set up and
38+
familiarize yourself with Bonsai. In particular, [download the necessary Bonsai
39+
packages](xref:install-configure-bonsai#package-installation) or [check for
40+
updates](xref:install-configure-bonsai#update-packages) if they're already
41+
installed. Once you've done that, copy/paste the following workflow into your
42+
Bonsai editor. The following sections explain how to configure each element of
43+
this workflow
44+
45+
::: workflow
46+
![SVG of copyable functional workflow](../../workflows/tutorials/ephys-socket/ephys-socket.bonsai)
47+
:::
3748

3849
### Configure TCP Connection
3950

40-
Place one TcpServer node per datastream at the top of the workflow and set their properties:
41-
42-
::: workflow
43-
![SVG of workflow that creates TCP sockets](../../workflows/tutorials/ephys-socket/configure-socket.bonsai)
44-
:::
45-
46-
- Address: Use "localhost" because Bonsai and the Open Ephys GUI will be running on the same machine
47-
in this tutorial.
48-
- Name: give the communication channel a unique name. We will use this name to provide the
49-
datastream to the socket within Bonsai. In this example, we have named them "SpikeSocket" and
50-
"LfpSocket". These names are arbitrary, but in our example they correspond to the kind of data
51-
they will transmit
52-
- Port: choose a unique port number. We will use this port number to establish the connection with
53-
the Open Ephys GUI.
54-
55-
> [!TIP]
56-
> The TcpServer nodes need to be at the top of the workflow. If they end up somewhere else
57-
> and you need to move them, do the following: click and hold on the node, hold down the Alt key on
58-
> the keyboard, hover over a node in the workflow row over which you want to place it until an arrow
59-
> appears, and let go. To learn more about moving nodes and connections in the workflow, refer to our
60-
> [Workflow Editor](xref:workflow-editor) page.
51+
Place one ``TcpServer`` node per datastream at the top of the workflow and
52+
set their properties:
53+
54+
![Screenshot of TCPServer configuration in Bonsai](../../images/ephys-socket-tut/tcp-server-config.png)
55+
56+
- **Address**: Use "localhost" if you are running Bonsai and the Open Ephys GUI
57+
on the same machine or the IP address of the machine running the GUI if not.
58+
- **Name**: give the TCP server a unique name. We will use this name to provide
59+
later in the workflow to send data though the connections established by this
60+
server. In this example, we have named them "SpikeServer" and "LfpServer".
61+
These names are arbitrary, but in our example they correspond to the kind of
62+
data they will transmit.
63+
- **Port**: choose a unique [port
64+
number](https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers). We
65+
will use this port number to establish the connection with the Open Ephys GUI.
66+
This mut be unique for each datastream that you wish to send. We used 9001 for
67+
our spike data and 9002 for LFP data.
68+
69+
> [!IMPORTANT]
70+
> The TcpServer nodes need to be at the top of the workflow. If they end up
71+
> somewhere else and you need to move them, do the following: click and hold on
72+
> the node, hold down the Alt key on the keyboard, hover over a node in the
73+
> workflow row over which you want to place it until an arrow appears, and let
74+
> go. To learn more about moving nodes and connections in the workflow, refer to
75+
> our [Workflow Editor](xref:workflow-editor) page.
6176
6277
### Configure ONIX Hardware
6378

64-
Construct an ONIX [hardware configuration chain](xref:onix-configuration):
79+
Construct an ONIX [hardware configuration chain](xref:onix-configuration):
6580

66-
::: workflow
67-
![SVG of workflow that creates TCP sockets & configures hardware](../../workflows/tutorials/ephys-socket/configuration.bonsai)
81+
::: workflow
82+
![SVG of workflow that creates TCP sockets & configures hardware](../../workflows/tutorials/ephys-socket/configuration.bonsai)
6883
:::
6984

70-
1. Place the [configuration operators](xref:configure) that correspond to the hardware you intend to
71-
use between <xref:OpenEphys.Onix1.CreateContext> and <xref:OpenEphys.Onix1.StartAcquisition>. In
72-
this example, these are <xref:OpenEphys.Onix1.ConfigureNeuropixelsV1eHeadstage> and
85+
1. Place the [configuration operators](xref:configure) that correspond to the
86+
hardware you intend to use between <xref:OpenEphys.Onix1.CreateContext> and
87+
<xref:OpenEphys.Onix1.StartAcquisition>. In this example, these are
88+
<xref:OpenEphys.Onix1.ConfigureNeuropixelsV1eHeadstage> and
7389
<xref:OpenEphys.Onix1.ConfigureBreakoutBoard>.
74-
1. Confirm that the device that streams electrophysiology data is enabled. In this example, we will
75-
stream data from the NeuropixelsV1e device which can be found in the properties panel by
76-
clicking the NeuropixelsV1eHeadstage node.
77-
1. In the case of NeuropixelsV1e Headstage, you must provide gain and calibration files and can
78-
perform other configurations as explained in the [NeuropixelsV1e Headstage
79-
Configuration](xref:np1e_configuration) and [NeuropixelsV1e GUI](xref:np1e_configuration) pages.
80-
In this example, we used an AP Gain value of 1000 and LFP Gain value of 50.
90+
1. Confirm that the device that streams electrophysiology data is enabled. In
91+
this example, we will stream data from the NeuropixelsV1e device which can
92+
be found in the properties panel by clicking the NeuropixelsV1eHeadstage
93+
node.
94+
1. In the case of NeuropixelsV1e Headstage, you must provide gain and
95+
calibration files and can perform other configurations as explained in the
96+
[NeuropixelsV1e Headstage Configuration](xref:np1e_configuration) and
97+
[NeuropixelsV1e GUI](xref:np1e_configuration) pages. In this example, we
98+
used an AP Gain value of 1000 and LFP Gain value of 50.
8199

82100
### Stream Ephys Data
83101

84-
Place the relevant [data I/O operators](xref:dataio) to stream electrophysiology data from your
85-
headstage:
102+
Place the relevant [data I/O operators](xref:dataio) to stream electrophysiology
103+
data from your headstage:
86104

87-
::: workflow
105+
::: workflow
88106
![SVG of workflow that creates TCP sockets, configures hardware, & streams data](../../workflows/tutorials/ephys-socket/ephys-data.bonsai)
89107
:::
90108

91-
1. Place the <xref:OpenEphys.Onix1.NeuropixelsV1eData> node into the workflow, since the device on
92-
NeuropixelsV1e Headstage that streams electrophysiology data is the Neuropixels 1.0 probe.
93-
1. Select the relevant members from the data frames that `NeuropixelsV1eData` produces. In this
94-
example, the relevant members are "SpikeData" and "LfpData". To do this, right-click
95-
`NeuropixelsV1eData`, hover over the output option in the context menu, and select "SpikeData"
96-
from the list. Repeat for "LfpData".
109+
1. Place the <xref:OpenEphys.Onix1.NeuropixelsV1eData> node into the workflow,
110+
since the device on NeuropixelsV1e Headstage that streams electrophysiology
111+
data is the Neuropixels 1.0 probe.
112+
1. Select the relevant members from the data frames that `NeuropixelsV1eData`
113+
produces. In this example, the relevant members are "SpikeData" and
114+
"LfpData". To do this, right-click `NeuropixelsV1eData`, hover over the
115+
output option in the context menu, and select "SpikeData" from the list.
116+
Repeat for "LfpData".
97117

98-
Visualize the raw data to confirm that the ephys data operator is streaming data.
118+
Visualize the raw data to confirm that the ephys data operator is streaming
119+
data.
99120

100121
### Transmit Data to Socket
101122

102-
Connect a `SendMatOverSocket` operator to each of the electrophysiology data streams. This operator
103-
comes from the OpenEphys.Sockets Bonsai package.
123+
Connect a `SendMatOverSocket` operator to each of the electrophysiology data
124+
streams. This operator comes from the OpenEphys.Sockets Bonsai package.
104125

105-
::: workflow
106-
![SVG of workflow that creates TCP sockets, configures hardware, & streams data over sockets](../../workflows/tutorials/ephys-socket/ephys-socket.bonsai)
126+
::: workflow
127+
![SVG of workflow that creates TCP sockets, configures hardware, & streams data over sockets](../../workflows/tutorials/ephys-socket/ephys-socket.bonsai)
107128
:::
108129

109-
Configure the "Connection" property of each `SendMatOverSocket` operator to each of the TCP Socket names
110-
configured earlier. In this example, we used "SpikeSocket" for "SpikeData" and "LfpSocket" for "LfPData".
130+
Configure the "Connection" property of each `SendMatOverSocket` operator to each
131+
of the TCP Socket names configured earlier. In this example, we used
132+
"SpikeServer" for "SpikeData" and "LfpServer" for "LfPData".
111133

112134
> [!TIP]
113-
> Although the Open Ephys GUI has recording functionality, data acquired using the Bonsai.Onix1
114-
> package should be written to file in Bonsai. You can learn to do this by following the [Hardware
115-
> Guides](xref:hardware) for your particular hardware. For this example, if you are using the
116-
> NeuropixelsV1e Headstage like the example, follow the [NeuropixelsV1e Headstage Hardware
135+
> Although the Open Ephys GUI has recording functionality, data acquired using
136+
> the Bonsai.Onix1 package should be written to disk in Bonsai because it is
137+
> possible for data to be lost if e.g. the TCP Buffer overflows. You can learn
138+
> to do this by following the [Hardware Guides](xref:hardware) for your
139+
> particular hardware. For this example, if you are using the NeuropixelsV1e
140+
> Headstage like the example, follow the [NeuropixelsV1e Headstage Hardware
117141
> Guide](xref:np1e).
118142
119143
## Receive ONIX Data from Socket in Open Ephys GUI
@@ -134,19 +158,26 @@ get familiarized with the Open Ephys GUI. In particular:
134158

135159
### Configure processors to visualize spike data
136160

137-
Drag the source processor `Ephys Socket` from the Processor list and drop it onto the Signal Chain
138-
area, followed by the sink processor `Probe Viewer`.
161+
Drag the source processor `Ephys Socket` from the Processor list and drop it
162+
onto the Signal Chain area, followed by the sink processor `Probe Viewer`.
163+
164+
Ephys data in the Open Ephys GUI is represented using floating point values in units
165+
of microvolts. Data coming from Bonsai will need to be converted to microvolts in
166+
order to plot properly within the GUI. To do this, the `Ephys Socket` processor
167+
provides the "Scale" and "Offset" values.:
139168

140-
Configure the Scale and Offset properties of the `Ephys Socket` processor:
169+
$Output\, (uV)= Scale * (Input - Offset)$
141170

142-
- Edit its "Scale" property to multiply the signal by a scalar in order to get microvolt values.
143-
This scalar is determined by the gain of the amplifier and resolution the ADC contained in the
144-
amplifier device. In this example, we "Scale" by 1.171875 because the NeuropixelsV1e device on
145-
NeuropixelsV1e headstage has a step size of 1.2e6/1024/_gain_&nbsp;μV/bit and the AP Gain was
171+
In this tutorial we used the following values:
172+
173+
- **Scale**: 1.171875.The NeuropixelsV1e device on NeuropixelsV1e
174+
headstage has a step size of 1.2e6/1024/_gain_&nbsp;μV/bit and the AP Gain was
146175
configured at 1000.
147-
- Edit its "Offset" property to subtract 2^bit depth - 1^ from the signal. In this example, we
148-
"Offset" 512 because the NeuropixelsV1e device outputs unsigned 10-bit data.
149-
- Press the "Connect" button on the `Ephys Socket`.
176+
- **Offset**: 512. The NeuropixelsV1e device outputs offset-binary
177+
encoded signed 10-bit data, so 512 corresponds to 0 volts.
178+
179+
After configuring `Ephys Socket` processor, press the "Connect" button to
180+
establish a connection with the `LfpServer` running in Bonsai.
150181

151182
![cropped screenshot of port 9001 signal chain](../../images/ephys-socket-tut/port-9001-signal-chain.webp)
152183

@@ -158,24 +189,26 @@ visualizer](../../images/ephys-socket-tut/ephys_socket_probe_viewer_gui_window.p
158189

159190
### Configure processors to visualize LFP data
160191

161-
Drag the source processor `Ephys Socket` from the Processor list and drop it onto the Signal Chain
162-
area, followed by the sink processor `Probe Viewer`.
192+
Drag the source processor `Ephys Socket` from the Processor list and drop it
193+
onto the Signal Chain area, followed by the sink processor `LFP Viewer`.
194+
configure the `Ephys Socket` processor "Scale" and "Offset" to convert incoming
195+
data to microvolts. In this tutorial we have used the following values for
196+
these parameters:
163197

164-
Configure the Scale and Offset properties of the `Ephys Socket` processor:
198+
- **Scale**: 23.4375. The NeuropixelsV1e device on NeuropixelsV1e
199+
headstage has a least significant bit of 1.2e6/1024/_gain_&nbsp;μV/bit and the
200+
LFP Gain was configured at 50.
201+
- **Offset**: 512. The NeuropixelsV1e device outputs offset-binary
202+
encoded signed 10-bit data, so 512 corresponds to 0 volts.
165203

166-
- Edit its "Scale" property to multiply the signal by a scalar in order to get microvolt values.
167-
This scalar is determined by the gain of the amplifier and resolution the ADC contained in the
168-
amplifier device. In this example, we "Scale" by 23.4375 because the NeuropixelsV1e device on
169-
NeuropixelsV1e headstage has a step size of 1.2e6/1024/_gain_&nbsp;μV/bit and the LFP Gain was
170-
configured at 50.
171-
- Edit its "Offset" property to subtract 2^bit depth - 1^ from the signal. In this example, we
172-
"Offset" 512 because the NeuropixelsV1e device outputs unsigned 10-bit data.
173-
- Press the "Connect" button on the `Ephys Socket`.
204+
After configuring `Ephys Socket` processor, press the "Connect" button to
205+
establish a connection with the `LfpServer` running in Bonsai.
174206

175207
![cropped screenshot of port 9002 signal chain](../../images/ephys-socket-tut/port-9002-signal-chain.webp)
176208

177-
Open the visualizer by clicking the “tab” button in the upper right of the `LFP Viewer`. Click the
178-
play button in the Control Panel at the top of the GUI to begin data acquisition.
209+
Open the visualizer by clicking the “tab” button in the upper right of the `LFP
210+
Viewer`. Click the play button in the Control Panel at the top of the GUI to
211+
begin data acquisition.
179212

180213
![TCP Socket LFP Open Ephys GUI
181214
visualizer](../../images/ephys-socket-tut/ephys_socket_lfp_viewer_gui_window.png)
@@ -186,10 +219,10 @@ visualizer](../../images/ephys-socket-tut/ephys_socket_lfp_viewer_gui_window.png
186219
> - [Probe Viewer plugin](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Probe-Viewer.html)
187220
> - [LFP Viewer plugin](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/LFP-Viewer.html)
188221
189-
## Stream Ephys Data in Bonsai and Visualize it in the Open Ephys GUI
222+
## Video Summary
190223

191-
Here is a video showing how this works:
224+
Below is video summary of this tutorial showing how this works:
192225

193226
<video controls style="width:100%">
194227
<source src="../../images/ephys-socket-tut/ephys_socket.mp4" type="video/mp4">
195-
</video>
228+
</video>

‎images/ephys-socket-tut/tcp-server-config.png

29.7 KB
Loading

‎workflows/tutorials/ephys-socket/configuration.bonsai

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@
88
<Nodes>
99
<Expression xsi:type="Combinator">
1010
<Combinator xsi:type="p1:TcpServer">
11-
<p1:Name>SpikeSocket</p1:Name>
11+
<p1:Name>SpikeServer</p1:Name>
1212
<p1:Port>9001</p1:Port>
1313
<p1:Address>localhost</p1:Address>
1414
</Combinator>
1515
</Expression>
1616
<Expression xsi:type="Combinator">
1717
<Combinator xsi:type="p1:TcpServer">
18-
<p1:Name>LfpSocket</p1:Name>
18+
<p1:Name>LfpServer</p1:Name>
1919
<p1:Port>9002</p1:Port>
2020
<p1:Address>localhost</p1:Address>
2121
</Combinator>

‎workflows/tutorials/ephys-socket/configure-socket.bonsai

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@
77
<Nodes>
88
<Expression xsi:type="Combinator">
99
<Combinator xsi:type="p1:TcpServer">
10-
<p1:Name>SpikeSocket</p1:Name>
10+
<p1:Name>SpikeServer</p1:Name>
1111
<p1:Port>9001</p1:Port>
1212
<p1:Address>localhost</p1:Address>
1313
</Combinator>
1414
</Expression>
1515
<Expression xsi:type="Combinator">
1616
<Combinator xsi:type="p1:TcpServer">
17-
<p1:Name>LfpSocket</p1:Name>
17+
<p1:Name>LfpServer</p1:Name>
1818
<p1:Port>9002</p1:Port>
1919
<p1:Address>localhost</p1:Address>
2020
</Combinator>

‎workflows/tutorials/ephys-socket/ephys-data.bonsai

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@
88
<Nodes>
99
<Expression xsi:type="Combinator">
1010
<Combinator xsi:type="p1:TcpServer">
11-
<p1:Name>SpikeSocket</p1:Name>
11+
<p1:Name>SpikeServer</p1:Name>
1212
<p1:Port>9001</p1:Port>
1313
<p1:Address>localhost</p1:Address>
1414
</Combinator>
1515
</Expression>
1616
<Expression xsi:type="Combinator">
1717
<Combinator xsi:type="p1:TcpServer">
18-
<p1:Name>LfpSocket</p1:Name>
18+
<p1:Name>LfpServer</p1:Name>
1919
<p1:Port>9002</p1:Port>
2020
<p1:Address>localhost</p1:Address>
2121
</Combinator>

0 commit comments

Comments
 (0)