European Data Format: EDF, EDF+, BDF and BDF+ (.edf, .bdf)
EDF is the open format for EEG and polysomnography recordings (Kemp et al. 1992). EDF+ (Kemp and Olivan 2003) adds annotations, discontinuous recordings and structured patient and recording fields. BDF is BioSemi’s 24-bit version of EDF, and BDF+ the 24-bit version of EDF+. One reader handles all four. Sleep labs, clinical EEG systems and most research amplifiers can write EDF, and BIDS accepts EDF and BDF for EEG.
Derived from the published specifications (docs/provenance/edf.md): the EDF and EDF+ pages at
edfplus.info, BioSemi’s BDF page and the BDF+ description. pyedflib and MNE-Python (both BSD) are
run as the reference readers; their source was not read.
Crate: openreadout-ephys, format id edf (EDF_FORMAT_ID), extensions edf and bdf, reader
EdfReader, dataset EdfDataset (open, open_input, edf). Detection (looks_like_edf): the
version field is 0 followed by spaces (EDF) or byte 255 followed by BIOSEMI (BDF), and the
header length at byte 184 equals 256 × (signal count + 1) → definite. Other files with these
extensions are extension-only matches.
Layout (parse_edf → EdfFile)
- Fixed header, 256 bytes of ASCII (
EDF_HEADER_BLOCK): version (8;version_field,bdf), local patient identification (80;patient), local recording identification (80;recording), start datedd.mm.yy(8;start_date), start timehh.mm.ss(8;start_time), header bytes (8;header_bytes), reserved (44;reserved:EDF+C,EDF+D,BDF+C,BDF+D, BioSemi’s24BIT, or blank), number of data records (8;declared_records, −1 while recording), duration of a data record in seconds (8;record_duration_s), number of signals (4; at mostMAX_EDF_SIGNALS). - Signal headers (
EdfSignal), 256 bytes per signal, stored field by field for all signals: label (16;label), transducer type (80;transducer), physical dimension (8;physical_dimension), physical minimum and maximum (8 each;physical_min,physical_max), digital minimum and maximum (8 each;digital_min,digital_max), prefiltering (80;prefiltering), samples per data record (8;samples_per_record), reserved (32;reserved). A signal labelledEDF AnnotationsorBDF Annotationsis an annotation signal (annotations). - Data records follow the header at 256 × (signals + 1) (
data_offset,record_offset). Each holds every signal’s samples in header order (offset_in_record;record_bytesper record): 2-byte little-endian two’s complement integers in EDF, 3-byte in BDF (sample_bytes).recordsis the number of whole records in the file, at most the declared count. - Values: physical = digital ×
scale+offset, withscale= (physical max − physical min) / (digital max − digital min) andoffset= physical min − digital min ×scale. A signal whose digital range is empty (calibratedfalse) keeps its digital values (scale 1, offset 0). - TALs (time-stamped annotation lists,
parse_tal) fill the annotation signals:+onset, an optional byte 21 and duration, byte 20, then texts each ended by byte 20, and a closing 0 byte. In EDF+ and BDF+ the first TAL of every data record is a time-keeping TAL whose first text is empty; its onset is the record’s start after the header’s start time. The first record’s is the subsecond start (start_offset_s), and every time the reader reports counts from it, as pyedflib and MNE do:record_startsandrecord_startgive each record’s start after the first one’s. Every other text is an annotation (EdfAnnotation:onset_safter the first record’s start,duration_s, 0 when the TAL gives none,text). TAL times are parsed exactly to the nanosecond (seconds_ns) and subtracted before they become floating point. At mostMAX_EDF_ANNOTATION_BYTESof annotation signal are read andMAX_EDF_ANNOTATIONSannotations kept. variantnames the file:EDF,EDF+C,EDF+D,BDF,BDF+C,BDF+D(plusfor the last four kinds with a+).recorded_atis the start date and time plusstart_offset_s; the year comes from the EDF+Startdate dd-MMM-yyyysubfield when the recording field has one (recording_subfields), else fromyywith 1985 as the clipping year.
Mapping
- Traces: ordinary signals that share
samples_per_record(so a sample rate) form one trace (groups), in the order their first signal appears; a file with one rate has one trace namedsignals, otherwise each issignals at <rate> Hz.sample_rate_hz= samples per record / record duration (rate_hz). Channels keep the signal labels and units; dtypeint16(EDF) orint24(BDF). Channelextra:signal(header index),physical_min,physical_max,digital_min,digital_max,transducer,prefiltering. - Sweeps: one, except in
EDF+D/BDF+Dfiles, where runs of data records that follow each other withinEDF_CONTIGUOUS_TOLERANCE_Sare sweeps (sweeps);extra.sweep_starts_sandextra.sweep_sample_countsthen give each run’s start and length.start_sis 0: the recording starts at the first sample. - Trace
extra:samples_per_record,record_duration_s,data_records; on trace 0recorded_atand the EDF+ recording subfieldsadmin_code,technicianandequipment(X, meaning unknown, is left out). - Table
annotations(when the file has any):onset_s,duration_s(seconds after the first sample) andtext, a code into the column’sextra.categories. format_versionis the variant. The patient field is only in the vendor metadata.- Reads are capped at
MAX_EDF_READsamples per channel andMAX_EDF_READ_BYTESof records.
check finding codes
truncated, bad_range, bad_digital_range, bad_physical_range (errors); header_bytes,
records_unknown, extra_bytes, annotations_capped, missing_time_keeping, bad_tal,
record_time_gap, digital_range_exceeds_sample_size, no_annotation_signal (warnings).
Oracle mapping
oracle/gen.py edf(): pyedflib reads the digital samples of every signal and the annotations;
MNE-Python reads the header (sample counts per record, the physical and digital extremes, units).
Physical values are the pyedflib digital samples × MNE’s scale + offset, by the formula above, in
float64; pyedflib’s and MNE’s own physical values are checked against them to 1e-9.
Vocabulary (every public identifier in crates/openreadout-ephys/src/edf/ must appear here)
| identifier | meaning |
|---|---|
EdfReader, EDF_FORMAT_ID, EdfDataset, open, open_input, edf |
entry points |
EdfFile, parse_edf, bdf, version_field, patient, recording, start_date, start_time, header_bytes, reserved, declared_records, records, record_duration_s, signals, record_bytes, file_len, record_starts, annotations, findings |
the file |
variant, plus, sample_bytes, data_offset, record_offset, rate_hz, groups, sweeps, record_start, recorded_at, recording_subfields |
derived from the header |
EdfSignal, label, transducer, physical_dimension, physical_min, physical_max, digital_min, digital_max, prefiltering, samples_per_record, offset_in_record, scale, offset, calibrated |
a signal |
EdfAnnotation, onset_s, duration_s, text, parse_tal, seconds_ns, start_offset_s |
annotations and times |
EDF_HEADER_BLOCK, MAX_EDF_SIGNALS, MAX_EDF_ANNOTATION_BYTES, MAX_EDF_ANNOTATIONS, MAX_EDF_READ, MAX_EDF_READ_BYTES, EDF_CONTIGUOUS_TOLERANCE_S, looks_like_edf |
constants, limits, detection |
How this reader was derived, file by file: provenance log.