The philosophy behind the Open Ephys GUI differs from that of existing commercial software for neuroscience. Taking inspiration from audio processing software such as Ableton Live, the GUI is structured around independent modules that can be mixed and matched to build a custom signal chain. We hope that this structure will give users and developers a tremendous amount of flexibility, without compromising functionality.
Because the way the GUI works is probably different than what you're used to, it may be helpful to start with some guidance. The instructions that follow will show you how to build the "classic" signal chain for extracellular electrophysiology, which includes simultaneously visualizing local field potentials and spike events. This signal chain is hard-coded into most commercial software, but it's only one of numerous ways to configure the GUI. Hopefully once you've finished this tutorial, many possibilities for modifying the GUI's functionality will become obvious.
When you first open the GUI, the signal chain is empty. Nothing happens if you hit the "play" or "record" buttons, since there's no data flowing through the processing pipeline.
On the left, you see all the available modules for building the signal chain, organized by type. "Sources" bring data into the application, either by communicating with an external device, reading data from a file, or generating samples on the fly. "Filters" alter the data in some way, either by modifying continuous signals or creating new events. "Sinks" send data outside the signal chain, for example to a USB device or a display. "Utilities" are used to construct the signal chain or control recording, but they don't modify data in any way.
The processing pipeline is configured by dragging modules from the list on the left and dropping them in the appropriate order onto the Signal Chain (large black zone) at the bottom of the screen. You can construct the pipeline in any order you'd like, but since every signal chain needs a Source, let's start with that.
A new module should appear, with a button that says "Select File." The File Reader works pretty much as advertised—it reads data from a file. The File Read can currently only read KWD files saved by the Open Ephys GUI. Here's how to configure it:
data_stream_16ch_cortex," and click "Open.", or the file 'structure.oebin', which will allow you to open "
data_stream_16ch_cortex," within the file reader.
Alternative, you can drag and drop a KWD file onto the File Reader module.
The File Reader is now configured to read pre-recorded data from 8 twisted-wire stereotrodes in mouse barrel cortex.
You will also notice that a "File Reader" icon has appeared in the "Graph" tab. This section of the GUI will become useful as the signal chain grows more complex. By clicking on a processor's icon, its module will automatically become visible. A signal chain with many branches would otherwise be difficult to navigate.
We want to use the incoming data for both visualizing the local field potential (LFP) and extracting spike waveforms. For the LFP, we'd like to keep the broadband signal, but spikes extraction requires a filter with a low cutoff around 600 Hz and a high cutoff around 6000 Hz. The GUI makes this easy to do by allowing you to split the signal chain. Then, the same data can be processed in two (or more) different ways.
Data always flows through the signal chain from left to right. If you happened to drop the Splitter to the left of the File Reader, it would become part of a separate signal chain (since every signal chain must begin with a source).
Clicking on the Splitter allows you to toggle back and forth between the two paths. Since there's currently nothing to the right of it, however, this won't change anything. Before you move onto the next step, make sure the top arrow of the Splitter is black.
Now we'll add our first sink to the signal chain, in order to send data to the computer's display.
The LFP Viewer's display won't be visible until you select whether you want the graphics to appear in a tab or in their own window. The tabs are available so the GUI is easy to use on small displays (such as a laptop screen). But if you have more real estate, you can put each visualizer in a separate window.
Since we now have a source and sink in the signal chain, the GUI can start to do useful things.
You should see 16 channels of data flowing through the LFP Viewer. You can play with the parameters of the LFP Viewer (such as voltage range, timebase, and spread) to change the look of the display. These don't change any aspect of the underlying data, only how it appears on the screen.
Before you can edit the signal chain again, you have to stop acquisition. The GUI can change the parameters of individual modules while acquisition is active, but you can't add, delete, or move modules.
Now it's time to edit the other branch of the signal chain.
The LFP Viewer's editor should disappear, leaving a blank signal chain to the right of the Splitter. To configure spike extraction, we'll need to add three separate modules: a bandpass filter, a spike detector, and a spike viewer. Why not combine them all into one? We think it's better to give each module a single function, to encourage code reuse. For example, it would be inefficient to reimplement a bandpass filter in every module that needs one. Instead, we've created a bandpass filter module that can be used for a variety of tasks. Why not combine spike detection and visualization? There are a lot of cases in which you'd want to do something with spikes before they're visualized, such as measuring changes in firing rate or implementing automated clustering algorithms. Separating detection and visualization gives you much more flexibility.
If your window is too narrow to display the entire processing pipeline, use the arrows to the right of the signal chain to shift the modules left and right. You can also use the icons in the Graph tab to bring the individual modules into focus.
Now our signal chain is complete, but we have to configure the Spike Detector before we can acquire spikes. The data being read by the File Reader was collected from 8 stereotrodes, so let's set up spike detection to reflect our electrode arrangement.
You should now see eight stereotrode displays in the Spike Viewer. Each one contains two waveform plots (which display the spike waveforms from each channel of the stereotrode) and one projection plot (which display the peak heights on each channel).
At any point in time (even while acquisition is active), you can deactivate individual electrode channels or change their threshold. You can also change which continuous channels map to which electrodes.
One potential point of confusion is that parameters cannot be shared across modules. Therefore, changing the threshold in the Spike Detector only affects the number of spikes that the Spike Viewer receives, rather than its internal parameters. However, there is a separate threshold within the Spike Viewer that determines which spikes are displayed and save to disk.
You've now created a signal processing pipeline that replicates nearly all the functionality of commercial electrophysiology software from Plexon or Neuralynx. But there's one important thing we haven't done yet, which is save the data.
Because of how the GUI is structured, recording has to work a little differently than it does in traditional electrophysiology applications. By default, the GUI records only continuous data from "Source" processors. To record data at other points in the processing pipeline, you have to manually select the channels you'd like to save from within an individual module. If you really want to, you can save every channel at every step in the signal chain. Or, you can save the data only after it's been filtered and processed in specific ways. As you can see, this approach gives the user tremendous flexibility, but can also lead to confusion when you first use the software. We are open to suggestions for ways to make the recording process more transparent and intuitive.
By default, the GUI will save your data in the directory from which the application is launched. Since this isn't always ideal, you can choose a different location through the Control Panel.
The data files won't be saved directly in this directory, but rather inside another directory that will be created inside this folder. This sub-folder won't be created _unless you actually record data_.
By default the name of the data folder is just the date and time, in the format `
YEAR-MONTH-DAY_HOUR_MINUTE_SECOND`. If you want to prepend a string (such as a subject name) or append a string (such as experiment number), that's easy to do.
YY-MM-DD_HH-MM-SS' string and type "open".
YY-MM-DD_HH-MM-SS' string and type "ephys".
All events that flow through the signal chain are saved automatically into a file called `all_channels.events` (or experimentX.kwe, if you're using the Kwik data format). This includes both events that are generated by external devices (such as TTLs) and events that are emitted by modules within the application. There's currently no way to disable saving events.
Selecting continuous channels for recording is done through an interface within each module.
Now we've configured the GUI to save the first three channels of data that come into the File Reader. If you want to save data from other modules, such as after it's been bandpass filtered, go through the steps above and select the appropriate channels.
In the Open Ephys data format, data from each channel is saved in its own file, with the title "
XXX = the ID number of the module it came from and
YYY = the channel number within that module. To translate the module ID back to its name, you can look at the XML settings file that is saved along with the recorded data.
In the Kwik format, all the data from an individual processor is saved in the same HDF5 file.
For more information on how the data is stored, check out the data format page on the wiki.
At the moment, spikes are recorded through the Spike Viewer. If the Spike Viewer is not part of the signal chain, no spikes will be written to disk. With the way the signal chain is currently configured, spikes will be saved, so there's nothing more you have to do. However, if there were only a Spike Detector (and no Spike Viewer), this wouldn't be the case.
Spikes are saved in separate files for each electrode. The name of the electrode is the same as the name of the file, with a "
.spikes" extension. You can read more about the spike file format on the data format page.
As you've probably guessed by now, the circular button in the control panel initiates recording.
This creates the data directory and starts writing continuous data, spikes, and events to disk. The background of the Control Panel becomes red, and the clock now keeps track of the total time spent recording (rather than the total duration of acquisition).
This closes all the files that are currently being saved.
Whenever you stop recording and the application is still open, you have the option of keeping the same data directory. This will append new data to the existing files.
Alternatively, you can click the "+" button in the recording options interface, which will signal that the GUI should create a new data directory the next time the record button is pressed.
Once the files are saved, it's easy to load the data into MATLAB or Python. We've created a
load_open_ephys_data m-file an
OpenEphys.py file that require only the filename as input.
Configuring the audio monitor is similar to configuring recording output.
After you've configured your signal chain, you can save it for later use.
Loading a configuration is just as easy.
The signal chain should be re-loaded exactly as you left it, including the parameters within each module. If it appears that something is changed, it could mean there's a bug in the loading code. In that case, consider submitting an issue if one doesn't already exist.
We have prepared some example configuration files that show some of the basic features described here. You can find them in
Resources/Configs/ , or on github.
Alternatively, you can select the "Reload on startup" option from the "File" menu, which will automatically reload the last-used configuration the next time the application is launched.
If you ran into any problems during this tutorial, it's likely they were due to bugs in the software, rather than your own mistakes. If you can replicate the problem, feel free to document it on the GitHub issues page. If it's something serious, we'll try to fix it as soon as possible.
You can also submit feature requests through the issues page. Better yet, though, you can try to add new features yourself! For more information, read the developer documentation section of this wiki.