Open Ephys Format#
Windows, Linux, macOS
Josh Siegle, Aarón Cuevas López
Data is stored in blocks with well-defined record markers, meaning data recovery is possible even if files are truncated by a crash.
The file header contains all the information required to load the file.
Windows imposes a limit on the number files that can be written to simultaneously, meaning the Open Ephys format is not compatible with very high-channel-count recordings (>8000 channels).
In order to achieve robustness, files contain redundant information, meaning they use extra space and take longer to load.
All data files are stored within the same Record Node directory, with a completely flat hierarchy. Files for different experiments have a number appended after an underscore (starting with
_2 for the second experiment in a session). Data from different recordings is distinguished by the
recording index values within each
Each Record Node directory also contains at least one
structure.openephys file, an XML file with metadata about the available files, as well as
messages.events, a text file containing text events saved by the GUI.
All headers are 1024 bytes long, and are written as a MATLAB-compatible string with the following fields and values:
format = ‘Open Ephys Data Format’
version = 0.4
header_bytes = 1024
description = ‘(String describing the header)’
date_created = ‘dd-mm-yyyy hhmmss’
channel = ‘(String with channel name)’
channelType = ‘(String describing the channel type)’
sampleRate = (integer sampling rate)
blockLength = 1024
bufferSize = 1024
bitVolts = (floating point value of microvolts/bit for headstage channels, or volts/bit for ADC channels)
For those not using MATLAB, each header entry is on a separate line with the following format:
field names appear after a “header.” prefix
field names and values are separated by ” = “
the value of the field is in plain text, with intended strings enclosed in single quotes (as demonstrated above)
each line is terminated with a semicolon
Continuous data for each channel is stored in a separate
.continuous file, identified by the processor ID (e.g.
100), stream name, and channel name (e.g.
CH1). After the 1024-byte header, continuous data is organized into “records,” each containing 1024 samples.
Each record is 2070 bytes long, and is terminated by a 10-byte record marker (0 1 2 3 4 5 6 7 8 255).
Events for each stream are stored in a
.events file. Each “record” contains the data for an individual event stored according to the following scheme:
Data from each electrode is saved in a separate file. The filename is derived from the electrode name with spaces removed (e.g., “Electrode1”) and the data stream name.
Each record contains an individual spike event (saved for one or more channels), and is written in the following format:
Since the samples are saved as 16-bit unsigned integers, converting them to microvolts involves subtracting 32768, dividing by the gain, and multiplying by 1000.
Reading data in Python#
(recommended) Create a
Sessionobject using the open-ephys-python-tools package. The data format will be automatically detected.
Fileobject using the pyopenephys package.
OpenEphys.pyin the open-ephys/analysis-tools repository.
Reading data in Matlab#
Use the open-ephys-matlab-tools <open-ephys/open-ephys-matlab-tools>`__ library.