|
| 1 | +--- |
| 2 | +uid: ephys-socket |
| 3 | +title: Visualizing Data in the Open Ephys GUI |
| 4 | +--- |
| 5 | + |
| 6 | +This tutorial shows how to stream ephys data from Bonsai the Open Ephys |
| 7 | +GUI through 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: |
| 15 | + |
| 16 | + |
| 17 | + |
| 18 | +> [!NOTE] |
| 19 | +> - This tutorial uses NeuropixelsV1e Headstage as an example, but the process is |
| 20 | +> similar for other ephys headstages. In fact, this tutorial can be used to send |
| 21 | +> data from any Bonsai operator that produces [matrices](xref:OpenCV.Net.Mat). |
| 22 | +> - This tutorial assumes you are familiar with the [hardware guide](xref:hardware) |
| 23 | +> of the ONIX headstage you intend to use. |
| 24 | +> - A [video summary](#video-summary) of this tutorial is is available at the |
| 25 | +> bottom of this page. |
| 26 | +
|
| 27 | +## Transmit Ephys Data to a TCP Server in Bonsai |
| 28 | + |
| 29 | +Follow the [Getting Started](xref:getting-started) guide to set up and |
| 30 | +familiarize yourself with Bonsai. In particular, [download the necessary Bonsai |
| 31 | +packages](xref:install-configure-bonsai#package-installation) or [check for |
| 32 | +updates](xref:install-configure-bonsai#update-packages) if they're already |
| 33 | +installed. Once you've done that, copy/paste the following workflow into your |
| 34 | +Bonsai editor. The following sections explain how to create this workflow and |
| 35 | +configure its elements. |
| 36 | + |
| 37 | +::: workflow |
| 38 | + |
| 39 | +::: |
| 40 | + |
| 41 | +### Configure TCP Connection |
| 42 | + |
| 43 | +Place one ``TcpServer`` node per datastream at the top of the workflow and |
| 44 | +set their properties: |
| 45 | + |
| 46 | + |
| 47 | + |
| 48 | +- **Address**: Use "localhost" if you are running Bonsai and the Open Ephys GUI |
| 49 | + on the same machine. Use the IP address of the machine running the GUI if not. |
| 50 | +- **Name**: give the TCP server a unique name. This name is used later in the |
| 51 | + the workflow to specify to which server to send data. In this example, we have |
| 52 | + named them "SpikeServer" and "LfpServer". These names are arbitrary, but in |
| 53 | + our example they correspond to the kind of data they will transmit. |
| 54 | +- **Port**: choose a unique [port |
| 55 | + number](https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers). We |
| 56 | + will use this port number to establish the connection with the Open Ephys GUI. |
| 57 | + This mut be unique for each datastream that you wish to send. We used 9001 for |
| 58 | + our spike data and 9002 for LFP data. |
| 59 | + |
| 60 | +> [!IMPORTANT] |
| 61 | +> The TcpServer nodes need to be at the top of the workflow. If they end up |
| 62 | +> somewhere else and you need to move them, do the following: click and hold on |
| 63 | +> the node, hold down the Alt key on the keyboard, hover over a node in the |
| 64 | +> workflow row over which you want to place it until an arrow appears, and let |
| 65 | +> go. To learn more about moving nodes and connections in the workflow, refer to |
| 66 | +> our [Workflow Editor](xref:workflow-editor) page. |
| 67 | +
|
| 68 | +### Configure ONIX Hardware |
| 69 | + |
| 70 | +Construct an ONIX [hardware configuration chain](xref:onix-configuration): |
| 71 | + |
| 72 | +::: workflow |
| 73 | + |
| 74 | +::: |
| 75 | + |
| 76 | +1. Place the [configuration operators](xref:configure) that correspond to the |
| 77 | + hardware you intend to use between <xref:OpenEphys.Onix1.CreateContext> and |
| 78 | + <xref:OpenEphys.Onix1.StartAcquisition>. In this example, these are |
| 79 | + <xref:OpenEphys.Onix1.ConfigureNeuropixelsV1eHeadstage> and |
| 80 | + <xref:OpenEphys.Onix1.ConfigureBreakoutBoard>. |
| 81 | +1. Confirm that the device that streams electrophysiology data is enabled. In |
| 82 | + this example, we will stream data from the NeuropixelsV1e device which can |
| 83 | + be found in the properties panel by clicking the NeuropixelsV1eHeadstage |
| 84 | + node. |
| 85 | +1. In the case of NeuropixelsV1e Headstage, you must provide gain and |
| 86 | + calibration files and can perform other configurations as explained in the |
| 87 | + [NeuropixelsV1e Headstage Configuration](xref:np1e_configuration) and |
| 88 | + [NeuropixelsV1e GUI](xref:np1e_configuration) pages. In this example, we |
| 89 | + used an AP Gain value of 1000 and LFP Gain value of 50. |
| 90 | + |
| 91 | +### Stream Ephys Data |
| 92 | + |
| 93 | +Place the relevant [data I/O operators](xref:dataio) to stream electrophysiology |
| 94 | +data from your headstage: |
| 95 | + |
| 96 | +::: workflow |
| 97 | + |
| 98 | +::: |
| 99 | + |
| 100 | +1. Place the <xref:OpenEphys.Onix1.NeuropixelsV1eData> node into the workflow, |
| 101 | + since the device on NeuropixelsV1e Headstage that streams electrophysiology |
| 102 | + data is the Neuropixels 1.0 probe. |
| 103 | +1. Select the relevant members from the data frames that `NeuropixelsV1eData` |
| 104 | + produces. In this example, the relevant members are "SpikeData" and |
| 105 | + "LfpData". To do this, right-click `NeuropixelsV1eData`, hover over the |
| 106 | + output option in the context menu, and select "SpikeData" from the list. |
| 107 | + Repeat for "LfpData". |
| 108 | + |
| 109 | +Visualize the raw data to confirm that the ephys data operator is streaming |
| 110 | +data. |
| 111 | + |
| 112 | +### Transmit Data to Socket |
| 113 | + |
| 114 | +Connect a `SendMatOverSocket` operator to each of the electrophysiology data |
| 115 | +streams. This operator comes from the OpenEphys.Sockets Bonsai package. |
| 116 | + |
| 117 | +::: workflow |
| 118 | + |
| 119 | +::: |
| 120 | + |
| 121 | +Set the "Connection" property of each `SendMatOverSocket` operator to the name |
| 122 | +of a TCP Socket configured earlier. In this example, "SpikeServer" is used |
| 123 | +for "SpikeData" and "LfpServer" for "LfPData". |
| 124 | + |
| 125 | +> [!TIP] |
| 126 | +> Although the Open Ephys GUI has recording functionality, data acquired using |
| 127 | +> the Bonsai.Onix1 package should be written to disk in Bonsai because it is |
| 128 | +> possible for data to be lost e.g. if the TCP Buffer overflows. You can learn |
| 129 | +> to do this by following the [Hardware Guides](xref:hardware) for your |
| 130 | +> particular hardware. For example, if you are using the NeuropixelsV1e |
| 131 | +> Headstage like the example, you would follow the [NeuropixelsV1e Headstage Hardware |
| 132 | +> Guide](xref:np1e). |
| 133 | +
|
| 134 | +## Receive ONIX Data from Socket in Open Ephys GUI |
| 135 | + |
| 136 | +Follow the [Open Ephys GUI documentation](https://open-ephys.github.io/gui-docs/) to set up and |
| 137 | +get familiarized with the Open Ephys GUI. In particular: |
| 138 | + |
| 139 | +- Download and install the application by following the [Open Ephys GUI installation |
| 140 | + instructions](https://open-ephys.github.io/gui-docs/User-Manual/Installing-the-GUI.html) |
| 141 | +- Install the Ephys Socket plugin and the Probe Viewer plugin by using the [Plugin |
| 142 | + Installer](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/index.html#plugin-installer). |
| 143 | +- Read about [Exploring the user |
| 144 | + interface](https://open-ephys.github.io/gui-docs/User-Manual/Exploring-the-user-interface.html), |
| 145 | + [Building a signal |
| 146 | + chain](https://open-ephys.github.io/gui-docs/User-Manual/Building-a-signal-chain.html) and |
| 147 | + [General plugin |
| 148 | + features](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/index.html#general-plugin-features) |
| 149 | + |
| 150 | +Once you've done that, <a href="../../workflows/tutorials/ephys-socket/sockets-signal-chain" download>download</a> |
| 151 | +the following signal chain and load it into the GUI. The following sections explain how to |
| 152 | +create this signal chain and configure its elements. |
| 153 | + |
| 154 | + |
| 155 | + |
| 156 | +### Configure processors to visualize spike data |
| 157 | + |
| 158 | +Drag the source processor `Ephys Socket` from the Processor list and drop it |
| 159 | +onto the Signal Chain area, followed by the sink processor `Probe Viewer`. |
| 160 | + |
| 161 | +Ephys data in the Open Ephys GUI is represented using floating point values in units |
| 162 | +of microvolts. Data coming from Bonsai will need to be converted to microvolts in |
| 163 | +order to plot properly within the GUI. To do this, the `Ephys Socket` processor |
| 164 | +provides the "Scale" and "Offset" values: |
| 165 | + |
| 166 | + $Output\, (uV)= Scale * (Input - Offset)$ |
| 167 | + |
| 168 | +In this tutorial we used the following values: |
| 169 | + |
| 170 | +- **Scale**: 1.171875.The NeuropixelsV1e device on NeuropixelsV1e |
| 171 | + headstage has a step size of 1.2e6/1024/_gain_ μV/bit and the AP Gain was |
| 172 | + configured at 1000. |
| 173 | +- **Offset**: 512. The NeuropixelsV1e device outputs offset-binary |
| 174 | + encoded signed 10-bit data, so 512 corresponds to 0 volts. |
| 175 | + |
| 176 | +> [!TIP] |
| 177 | +> The appropriate scale and offset values for any headstage can be found by navigating to its |
| 178 | +> respective Data Frame page. For example, those values for the Neuropixels 1.0 device are |
| 179 | +> available on the <xref:OpenEphys.Onix1.NeuropixelsV1DataFrame> page. |
| 180 | +
|
| 181 | +After configuring `Ephys Socket` processor, press the "Connect" button to |
| 182 | +establish a connection with the `LfpServer` running in Bonsai. |
| 183 | + |
| 184 | + |
| 185 | + |
| 186 | +Open the visualizer by clicking the “tab” button in the upper right of the `Probe Viewer`. Click the |
| 187 | +play button in the Control Panel at the top of the GUI to begin data acquisition. |
| 188 | + |
| 189 | + |
| 191 | + |
| 192 | +### Configure processors to visualize LFP data |
| 193 | + |
| 194 | +Drag the source processor `Ephys Socket` from the Processor list and drop it |
| 195 | +onto the Signal Chain area, followed by the sink processor `LFP Viewer`. |
| 196 | +configure the `Ephys Socket` processor "Scale" and "Offset" to convert incoming |
| 197 | +data to microvolts. In this tutorial we have used the following values for |
| 198 | +these parameters: |
| 199 | + |
| 200 | +- **Scale**: 23.4375. The NeuropixelsV1e device on NeuropixelsV1e |
| 201 | + headstage has a least significant bit of 1.2e6/1024/_gain_ μV/bit and the |
| 202 | + LFP Gain was configured at 50. |
| 203 | +- **Offset**: 512. The NeuropixelsV1e device outputs offset-binary |
| 204 | + encoded signed 10-bit data, so 512 corresponds to 0 volts. |
| 205 | + |
| 206 | +After configuring `Ephys Socket` processor, press the "Connect" button to |
| 207 | +establish a connection with the `LfpServer` running in Bonsai. |
| 208 | + |
| 209 | + |
| 210 | + |
| 211 | +Open the visualizer by clicking the “tab” button in the upper right of the `LFP |
| 212 | +Viewer`. Click the play button in the Control Panel at the top of the GUI to |
| 213 | +begin data acquisition. |
| 214 | + |
| 215 | + |
| 217 | + |
| 218 | +> [!TIP] |
| 219 | +> You can read more about using each specific plugins used in this tutorial by reading their documentation: |
| 220 | +> - [Ephys Socket plugin](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Ephys-Socket.html) |
| 221 | +> - [Probe Viewer plugin](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Probe-Viewer.html) |
| 222 | +> - [LFP Viewer plugin](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/LFP-Viewer.html) |
| 223 | +
|
| 224 | +## Video Summary |
| 225 | + |
| 226 | +Below is video summary of this tutorial showing how this works: |
| 227 | + |
| 228 | +<video controls style="width:100%"> |
| 229 | + <source src="../../images/ephys-socket-tut/ephys_socket.mp4" type="video/mp4"> |
| 230 | +</video> |
0 commit comments