BrainVision Core Data Format (.vhdr, .vmrk, .eeg)
Brain Products’ BrainVision Recorder and Analyzer store an EEG recording as three files: a text
header (.vhdr), a text marker file (.vmrk) and the samples (.eeg, or .dat in some
exports). pybv, MNE-Python, FieldTrip, EEGLAB and BciPy write the same layout, and BIDS accepts it
for EEG. OpenReadout reads the recording from any of the three files; the header names the other
two.
Derived from the BSD-licensed readers and writer that document the layout (Neo’s
BrainVisionRawIO, MNE-Python’s BrainVision reader, pybv) and from the corpus files
(docs/provenance/brainvision.md). MNE-Python and Neo are run as the reference readers.
Crate: openreadout-ephys, format id brainvision (BRAINVISION_FORMAT_ID), extensions vhdr
and vmrk, reader BrainVisionReader, dataset BrainVisionDataset (open, open_input,
header). Detection: a first line that identifies a BrainVision header (looks_like_vhdr) →
definite; a .vmrk whose first line identifies a marker file (looks_like_vmrk) → definite; an
.eeg or .dat file with a .vhdr of the same stem next to it → likely. Axona .eeg files are
recognised by their own content first.
Layout (parse_header → BvHeader)
- Header (
.vhdr), UTF-8 or Windows-1252 text (decode_text). The first line (identification) isBrain Vision Data Exchange Header File Version 1.0,BrainVision Data Exchange Header File Version 2.0orBrainVision Core Data Format 1.0(identification_version→version). The next line, a;comment, often names the writer (writer_note,writer:BrainVision Recorder,BrainVision Analyzerfor “history path” exports,pybv,MNE-Python,FieldTrip,EEGLAB,BciPy). Then INI sections ofkey=valuelines (parse_ini→sections, case-insensitive) up to[Comment], whose free text (amplifier and filter settings) is kept ascomment.[Common Infos]:DataFileandMarkerFile(resolved next to the header: as named, then without regard to case, then under the header’s own stem →data_path,marker_path),DataFormat(BINARYorASCII),DataOrientation(MULTIPLEXED: frames of one sample per channel;VECTORIZED: all of channel 1, then channel 2 … →vectorized),DataType(onlyTIMEDOMAINis read),NumberOfChannels(at mostMAX_BV_CHANNELS),SamplingIntervalin µs (sampling_interval_us;rate_hz= 1,000,000 / interval),DataPoints(data_points),SegmentationType(segmentation),SegmentDataPoints(segment_points),Averaged(averaged).[Binary Infos]:BinaryFormat(BvSampleFormat:Int16INT_16,UInt16UINT_16,Int32INT_32,Float32IEEE_FLOAT_32;bytes,name,dtype) andUseBigEndianOrder(big_endian).[ASCII Infos](Asciiformat):DecimalSymbol(decimal_symbol),SkipLines(skip_lines),SkipColumns(skip_columns). Only MULTIPLEXED ASCII data is read; every line is indexed at open, up toMAX_BV_ASCIIbytes.[Channel Infos]:Ch<n>=<name>,<reference>,<resolution>,<unit>(BvChannel:name,reference,resolution, 1 when empty,unit,µVwhen absent);\1stands for a comma.[Coordinates]:Ch<n>=<radius>,<theta>,<phi>(coordinates).
- Markers (
.vmrk,parse_markers):[Marker Infos]Mk<n>=<type>,<description>,<position>, <points>,<channel>[,<date>](BvMarker:kind,description,positioncounting from 1,points,channel, 0 for all channels,dateYYYYMMDDhhmmssuuuuuuonNew Segmentmarkers), inMknumber order, at mostMAX_BV_MARKERS. The header and marker files are read up toMAX_BV_TEXTbytes. - Values: stored sample × the channel’s
resolution, in the channel’s unit, for every format (pybv writes floats divided by the resolution too). recorded_atis the firstNew Segmentmarker’s date,yyyy-mm-ddThh:mm:ss.uuuuuu.
Mapping
- One trace
signals: a channel per header channel (dtype of the stored format,scalethe resolution,offset0; channelextra:reference,resolution,coordinates). Samples per channel: whole frames in the data file, orDataPointswhen it is smaller. - Sweeps: one, except when
SegmentationType=MARKERBASEDandSegmentDataPointsdivides the data evenly: then each segment is a sweep (extra.sweep_starts_s). - Trace
extra:header_version,binary_format,orientation,sampling_interval_us,segmentation,averaged,recorded_at,application(the writer) andwritten_by(the writer note as written). - Table
markers(when the marker file has any):onset_sandduration_s(seconds after the first sample: (position − 1) / rate and points / rate),sample(position − 1),points,channel, andtypeanddescriptionas codes into their columns’extra.categories. format_versionis the header version.member_fileslists the three files.- Reads are capped at
MAX_BV_READsamples per channel andMAX_BV_READ_BYTESbytes.
check finding codes
missing_channel, truncated, zero_resolution (errors); missing_marker_file,
marker_identification, bad_marker, partial_frame, extra_bytes, marker_past_end
(warnings).
Oracle mapping
oracle/gen.py brainvision(): Neo’s BrainVisionRawIO gives the stored samples in their own
type, MNE-Python each channel’s resolution and the markers (_read_mrk); values are the stored
samples × resolution in float64, checked against MNE’s own values. Units are Neo’s where it read
one, else MNE’s.
Vocabulary (every public identifier in crates/openreadout-ephys/src/brainvision/ must appear here)
| identifier | meaning |
|---|---|
BrainVisionReader, BRAINVISION_FORMAT_ID, BrainVisionDataset, open, open_input, header |
entry points |
BvHeader, parse_header, parse_ini, decode_text, identification_version, version, identification, writer_note, writer, sections, comment, data_path, marker_path, format, vectorized, big_endian, sampling_interval_us, rate_hz, data_points, segmentation, segment_points, averaged, decimal_symbol, skip_lines, skip_columns, channels, markers, findings, recorded_at |
the header |
BvSampleFormat, Int16, UInt16, Int32, Float32, Ascii, bytes, name, dtype |
sample formats |
BvChannel, reference, resolution, unit, coordinates |
a channel |
BvMarker, parse_markers, kind, description, position, points, channel, date |
a marker |
MAX_BV_TEXT, MAX_BV_CHANNELS, MAX_BV_MARKERS, MAX_BV_READ, MAX_BV_READ_BYTES, MAX_BV_ASCII, looks_like_vhdr, looks_like_vmrk |
limits and detection |
How this reader was derived, file by file: provenance log.