User documentation

IMPORTANT: The Open Ephys GUI documentation has migrated to a new site – please visit https://open-ephys.github.io for the most up-to-date information.


The basics

Constructing the signal chain

The processing pipeline is built by dragging names of modules from the list on the left and dropping them onto the signal chain. A couple of rules must be obeyed:

  • Every signal chain must contain a source. Sources feed data into the signal chain; without them, the signal chain has nothing to do. Currently, acquisition won't work unless a source is present in every signal chain. It's fine to have a signal chain with nothing but a source, if all you want to do is stream data to disk.
  • Sources may only be placed at the start of a signal chain, and sinks may only be placed at the end. If a source or sink is dropped in the middle of the signal chain, the chain will automatically split in two.

Otherwise, you can have an arbitrary number of signal chains, which can branch an arbitrary number of times. However, be wary of bugs with loading and saving complex, branching signal chains.

Modules can be removed by clicking on their titles and pressing the "delete" key. Their order can be rearranged by dragging and dropping modules within the signal chain.

Pressing Cmd-Delete (OS X) or Ctrl-Backspace (Linux and Window) will clear all modules from all signal chains.

Setting parameters

Most modules have a straightforward set of parameters that appear in the editor. Although the signal chain becomes locked while data acquisition is active, it's possible to edit parameters at any time. Parameter changes are not currently tracked, so be careful about changing parameters while you're recording.

Opening/saving the signal chain.

Use Cmd-S/Ctrl-S (or the "File" drop-down menu) to save the signal chain. It must have an .xml extension.

Use Cmd-O/Ctrl-O (or the "File" drop-down menu) to open a previously saved signal chain. It must have an .xml extension in order to load.

Most, but not all, modules will save their internal settings. For safety purposes, assume that any module will not reload its settings until you confirm that it does. If settings are not being loaded properly for a particular module, feel free to submit an issue on GitHub.

Recording

There are two places in which recording is configured:

  • The file selector within the control panel (hidden by default, exposed with the arrow button). This determines the location of the saved data, as well as the strings to prepend or append to the data folder. If data has already been recorded, pressing the "+" button next to the file name automatically generates a new data folder.
  • The channel selector drawer within each module editor determines which channels will be saved. By default, only continuous channels from source nodes and events from any node are saved. To save continuous channels from any other particular module, first open the drawer by clicking the vertical lines on the right side of the module editor, then switch to the "REC" tab and highlight the channels you wish to save. It's possible to save a signal after every step in the processing pipeline, but we wouldn't recommend doing this unless you have a very fast machine with a lot of free disk space. At the moment, all channels must be saved at the same sample rate, but we're working on a way to downsample LFP channels.

Some things to keep in mind:

  • If a channel in the "REC" tab is highlighted while recording is active, it will start being written to disk immediately. If this happens in the middle of a 1024-sample buffer, the initial buffer samples will be zeros.
  • If a channel in the "REC" tab is deselected while recording is active, it will stop being written to disk immediately. If this happens in the middle of a 1024-sample buffer, the remaining buffer samples will be set to zero.
  • It's possible to start and stop recording within the same file. In this case, you'll need to refer to the "recording number" flag in the data file to figure out when the break occurred. It will increment by 1 every time the record button is pressed. To prevent multiple rounds of recordings from being saved in the same file, simply click the "plus" button next to the filename in the control panel in order to create a new data folder the next time recording begins.
  • Unlike continuous and event data, spikes are saved through the Spike Viewer. There's nothing to configure, but just be aware that your spike data won't be saved unless there's a Spike Viewer in the signal chain.

For information on exactly what is saved, check out the Data format wiki page.

Audio monitoring

Configuring the audio monitor is similar to setting up recording. By default, nothing is passed to the monitor. In order to listen to a particular channel, open the channel selector drawer and switch to the "AUDIO" tab. Any highlighted channels will be sent to the audio monitor. The volume of the audio monitor (and destination of the audio output) can be configured in the control panel.

Submitting issues

In the case of a crash, it's important to replicate what you did. If you can do that, and you don't know how to fix it yourself, go ahead and submit an issue describing the problem. Include your operating system and machine specs if you think it might be relevant.

Issues can also be used to request new features. If you're unsure about whether or not a feature is realistic, don't hesitate to ask about it through the contact page.

Debug console

The GUI is able to send debug messages to a console. In many cases, the information displayed there can greatly help locate and solve an issue. The way to access the debug console varies depending on the operating system.

Linux

To display the debug console on Linux, just run the open-ephys application in a console terminal, the output will be displayed there.

MacOS

To display the debug console on MacOS, open a terminal, navigate to the directory where the GUI application is located and run it inside the console.

Due to the structure of MacOS app bundles, the whole command to run the GUI would be ./open-ephys.app/Contents/MacOS/open-ephys Run this command from the directory which contains the App bundle. Do not access the internal App directories and run ./open-ephys from there, as some features will not be available that way.

Windows

To display the debug console on Windows, follow the following steps:

  1. Create a shortcut by right clicking the open-ephys executable and selecting the "Create shortcut" option
  2. Right click the newly created shortcut and select "Properties"
  3. In the shortcut properties page, add --console at the end of the Target line, which contains the path to the open ephys executable. Add it after any quotes, if there were any. Click OK once this has been done.
  4. Every time you need to open the console, just run the GUI via this shortcut instead of the normal executable