EDFlib is a programming library for C/C++ to read/write EDF+/BDF+ files. (It also reads old-type EDF/BDF files.)
EDF means European Data Format. BDF is the 24-bits version of EDF.
For a Java version, look here. For a Python version, look here.
The library consists of only two files: edflib.h and edflib.c
and has been tested using the GCC compiler on Linux and MinGW on windows.
MS visual C compiler has not been tested but should work.
EDFlib is used in the EDF-plugin for Scilab.
This is free software, it is experimental and available under a very permissive BSD style license.
This means that you can use this library in (commercial) closed-source software.
Despite this software is intend to be usefull, there is no warranty, use this software at your own risk.
Feedback to: teuniz@protonmail.com
A collection of VI's to write files in the European Data Format for Labview.
In EDF, the sensitivity (e.g. uV/bit) and offset are stored using four parameters:
digital maximum and minimum, and physical maximum and minimum.
Here, digital means the raw data coming from a sensor or ADC. Physical means the units like uV.
The sensitivity in units/bit is calculated as follows:
units per bit = (physical max - physical min) / (digital max - digital min)
The digital offset is calculated as follows:
offset = (physical max / units per bit) - digital max
For a better explanation about the relation between digital data and physical data, read the document Coding Schemes Used with Data Converters.
note: An EDF file usually contains multiple so-called datarecords. One datarecord usually has a duration of one second (this is the default but it is not mandatory!).
In that case a file with a duration of five minutes contains 300 datarecords. The duration of a datarecord can be freely choosen but, if possible, use values from
0.1 to 1 second for easier handling. Just make sure that the total size of one datarecord, expressed in bytes, does not exceed 10MByte (15MBytes for BDF(+)).
The recommendation of a maximum datarecordsize of 61440 bytes in the EDF and EDF+ specification was usefull in the time people were still using DOS as their main operating system.
Using DOS and fast (near) pointers (16-bit pointers), the maximum allocatable block of memory was 64KByte.
This is not a concern anymore so the maximum datarecord size now is limited to 10MByte for EDF(+) and 15MByte for BDF(+).
This helps to accommodate for higher samplingrates used by modern, fast Analog to Digital Converters.
EDF header character encoding: The EDF specification says that only ASCII characters are allowed.
EDFlib will automatically convert characters with accents, umlauts, tilde, etc. to their "normal" equivalent without the accent/umlaut/tilde/etc.
The description/name of an EDF+ annotation on the other hand, is encoded in UTF-8.
int edfopen_file_readonly(const char *path, struct edf_hdr_struct *edfhdr, int read_annotations);
Path is a null-terminated string containing the path to the file.
hdr is a pointer to an edf_hdr_struct, all fields in this struct will be overwritten.
The edf_hdr_struct will be filled with all the relevant header- and signalinfo/parameters.
Read the headerfile edflib.h to see what info is available and how to access it.
Have a look at the demo file main.c as well.
The structure contains a "handle" which you need for the other functions.
When it returns the value EDFLIB_FILE_CONTAINS_FORMAT_ERRORS, it means that the file is not EDF (or EDF+, BDF, BDF+) compliant.
Check the file with EDFbrowser to get information about the problem.
read_annotations must have one of the following values:
Returns 0 on success, in case of an error it returns -1 and an errorcode will be set in the member "filetype" of struct edf_hdr_struct.
This function is required if you want to read a file
int edfclose_file(int handle);
Closes the file.
Returns -1 in case of an error, 0 on success.
int edfread_physical_samples(int handle, int edfsignal, int n, double *buf);
Reads n samples from edfsignal, starting from the current sample position indicator, into buf.
The values are converted to their physical values e.g. microVolts, beats per minute, etc.
Bufsize should be equal to or bigger than sizeof(double[n]).
Returns the amount of samples read (this can be less than n or zero) or -1 in case of an error
The sample position indicator will be increased with the amount of samples read.
int edfread_digital_samples(int handle, int edfsignal, int n, int *buf);
Reads n samples from edfsignal, starting from the current sample position indicator, into buf.
The values are the "raw" digital values.
Bufsize should be equal to or bigger than sizeof(int[n]).
Returns the amount of samples read (this can be less than n or zero) or -1 in case of an error
The sample position indicator will be increased with the amount of samples read.
long long edfseek(int handle, int edfsignal, long long offset, int whence);
The edfseek() function sets the sample position indicator for the edfsignal pointed to by edfsignal.
The new position, measured in samples, is obtained by adding offset samples to the position specified by whence.
If whence is set to EDFSEEK_SET, EDFSEEK_CUR, or EDFSEEK_END, the offset is relative to the start of the file,
the current position indicator, or end-of-file, respectively.
Returns the current offset. Otherwise, -1 is returned.
Note that every signal has it's own independent sample position indicator and edfseek() affects only one of them.
long long edftell(int handle, int edfsignal);
The edftell() function obtains the current value of the sample position indicator for the edfsignal pointed to by edfsignal.
Returns the current offset. Otherwise, -1 is returned
Note that every signal has it's own independent sample position indicator and edftell() affects only one of them.
void edfrewind(int handle, int edfsignal);
The edfrewind() function sets the sample position indicator for the edfsignal pointed to by edfsignal to the beginning of the file.
It is equivalent to: (void) edfseek(int handle, int edfsignal, 0LL, EDFSEEK_SET).
Note that every signal has it's own independent sample position indicator and edfrewind() affects only one of them.
int edf_get_annotation(int handle, int n, struct edf_annotation_struct *annot);
Fills the edf_annotation_struct with the annotation n, returns 0 on success, otherwise -1.
The string that describes the annotation/event is encoded in UTF-8.
To obtain the number of annotations in a file, check edf_hdr_struct -> annotations_in_file.
int edfopen_file_writeonly(const char *path, int filetype, int number_of_signals);
Opens an new file for writing. Warning, an already existing file with the same name will be silently overwritten without advance warning!
path is a null-terminated string containing the path and name of the file
filetype must be EDFLIB_FILETYPE_EDFPLUS or EDFLIB_FILETYPE_BDFPLUS
Returns a handle on success, you need this handle for the other functions.
In case of an error, it returns a negative number corresponding to one of the following values:
EDFLIB_MALLOC_ERROR
EDFLIB_NO_SUCH_FILE_OR_DIRECTORY
EDFLIB_MAXFILES_REACHED
EDFLIB_FILE_ALREADY_OPENED
EDFLIB_NUMBER_OF_SIGNALS_INVALID
This function is required if you want to write a file.
int edf_set_samplefrequency(int handle, int edfsignal, int samplefrequency);
Sets the samplefrequency of signal edfsignal. (In reallity, it sets the number of samples in a datarecord.)
Returns 0 on success, otherwise -1
This function is required for every signal and can be called only after opening a
file in writemode and before the first sample write action
int edf_set_physical_maximum(int handle, int edfsignal, double phys_max);
Sets the maximum physical value of signal edfsignal.
Returns 0 on success, otherwise -1
This function is required for every signal and can be called only after opening a
file in writemode and before the first sample write action.
int edf_set_physical_minimum(int handle, int edfsignal, double phys_min);
Sets the minimum physical value of signal edfsignal.
Usually this will be (-(phys_max))
Returns 0 on success, otherwise -1
This function is required for every signal and can be called only after opening a
file in writemode and before the first sample write action.
int edf_set_digital_maximum(int handle, int edfsignal, int dig_max);
Sets the maximum digital value of signal edfsignal. Usually, the value 32767 is used for EDF+ and 8388607 for BDF+.
Returns 0 on success, otherwise -1
This function is required for every signal and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_digital_minimum(int handle, int edfsignal, int dig_min);
Sets the minimum digital value of signal edfsignal. Usually, the value -32768 is used for EDF+ and -8388608 for BDF+.
Usually this will be (-(dig_max + 1))
Returns 0 on success, otherwise -1
This function is required for every signal and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_label(int handle, int edfsignal, const char *label);
Sets the label (name) of signal edfsignal ("FP1", "SaO2", etc.).
label is a pointer to a NULL-terminated ASCII-string containing the label (name) of the signal edfsignal.
Returns 0 on success, otherwise -1
This function is recommended for every signal when you want to write a file
and can be called only after opening a file in writemode and before the first sample write action.
int edf_set_prefilter(int handle, int edfsignal, const char *prefilter);
Sets the prefilter of signal edfsignal ("HP:0.1Hz", "LP:75Hz N:50Hz", etc.).
prefilter is a pointer to a NULL-terminated ASCII-string containing the prefilter text of the signal edfsignal.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode and before
the first sample write action.
int edf_set_transducer(int handle, int edfsignal, const char *transducer);
Sets the transducer of signal edfsignal ("AgAgCl cup electrodes", etc.).
transducer is a pointer to a NULL-terminated ASCII-string containing the transducer text of the signal edfsignal.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode and before
the first sample write action.
int edf_set_physical_dimension(int handle, int edfsignal, const char *phys_dim);
Sets the physical dimension of signal edfsignal ("uV", "BPM", "mA", "Degr.", etc.).
phys_dim is a pointer to a NULL-terminated ASCII-string containing the physical dimension of the signal edfsignal.
Returns 0 on success, otherwise -1
This function is recommended for every signal when you want to write a file
and can be called only after opening a file in writemode and before the first sample write action.
int edf_set_startdatetime(int handle, int startdate_year, int startdate_month, int startdate_day, int starttime_hour, int starttime_minute, int starttime_second);
Sets the startdate and starttime.
year: 1985 - 2084, month: 1 - 12, day: 1 - 31
hour: 0 - 23, minute: 0 - 59, second: 0 - 59
If not called, the library will use the system date and time at runtime.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
Note: for anonymization purposes, the consensus is to use 1985-01-01 00:00:00 for the startdate and starttime.
int edf_set_patientname(int handle, const char *patientname);
Sets the patientname. patientname is a pointer to a null-terminated ASCII-string.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_patientcode(int handle, const char *patientcode);
Sets the patientcode. patientcode is a pointer to a null-terminated ASCII-string.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_gender(int handle, int gender);
Sets the gender. 1 is male, 0 is female.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_birthdate(int handle, int birthdate_year, int birthdate_month, int birthdate_day);
Sets the birthdate.
year: 1800 - 3000, month: 1 - 12, day: 1 - 31
This function is optional.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_patient_additional(int handle, const char *patient_additional);
Sets the additional patientinfo. patient_additional is a pointer to a null-terminated ASCII-string.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_admincode(int handle, const char *admincode);
Sets the admincode. admincode is a pointer to a null-terminated ASCII-string.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_technician(int handle, const char *technician);
Sets the technicians name. technician is a pointer to a null-terminated ASCII-string.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_equipment(int handle, const char *equipment);
Sets the name of the equipment used during the aquisition. equipment is a pointer to a null-terminated ASCII-string.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edf_set_recording_additional(int handle, const char *recording_additional);
Sets the additional recordinginfo. recording_additional is a pointer to a null-terminated ASCII-string.
Returns 0 on success, otherwise -1
This function is optional and can be called only after opening a file in writemode
and before the first sample write action.
int edfwrite_physical_samples(int handle, double *buf);
Writes n physical samples (uV, mA, Ohm) from *buf belonging to one signal
where n is the samplefrequency of the signal.
The physical samples will be converted to digital samples using the
values of physical maximum, physical minimum, digital maximum and digital minimum.
The number of samples written is equal to the samplefrequency of the signal.
Size of buf should be equal to or bigger than sizeof(double[samplefrequency]).
Call this function for every signal in the file. The order is important!
When there are 4 signals in the file, the order of calling this function
must be: signal 0, signal 1, signal 2, signal 3, signal 0, signal 1, signal 2, etc.
Returns 0 on success, otherwise -1
int edf_blockwrite_physical_samples(int handle, double *buf);
Writes physical samples (uV, mA, Ohm) from *buf.
buf must be filled with samples from all signals, starting with n samples of signal 0, n samples of signal 1, n samples of signal 2, etc.
where n is the samplefrequency of the signal.
One block equals one second.
The physical samples will be converted to digital samples using the
values of physical maximum, physical minimum, digital maximum and digital minimum.
The total number of samples written is equal to the sum of the samplefrequencies of all signals.
Size of buf should be equal to or bigger than sizeof(double) multiplied by the sum of the samplefrequencies of all signals.
Returns 0 on success, otherwise -1
int edfwrite_digital_samples(int handle, int *buf);
Writes n "raw" digital samples from *buf belonging to one signal
where n is the samplefrequency of the signal.
The 16 (or 24 in case of BDF) least significant bits of the sample will be written to the
file without any conversion.
The number of samples written is equal to the samplefrequency of that signal.
Size of buf should be equal to or bigger than sizeof(int[samplefrequency]).
Call this function for every signal in the file. The order is important!
When there are 4 signals in the file, the order of calling this function
must be: signal 0, signal 1, signal 2, signal 3, signal 0, signal 1, signal 2, etc.
Returns 0 on success, otherwise -1
int edf_blockwrite_digital_samples(int handle, int *buf);
Writes "raw" digital samples from *buf.
buf must be filled with samples from all signals, starting with n samples of signal 0, n samples of signal 1, n samples of signal 2, etc.
where n is the samplefrequency of the signal.
One block equals one second.
The 16 (or 24 in case of BDF) least significant bits of the sample will be written to the
file without any conversion.
The number of samples written is equal to the sum of the samplefrequencies of all signals.
Size of buf should be equal to or bigger than sizeof(int) multiplied by the sum of the samplefrequencies of all signals
Returns 0 on success, otherwise -1
int edfwrite_digital_short_samples(int handle, short *buf);
Writes n "raw" digital samples from *buf belonging to one signal
where n is the samplefrequency of the signal.
The samples will be written to the file without any conversion.
Because the size of a short is 16-bit, do not use this function when you write a BDF file.
The number of samples written is equal to the samplefrequency of the signal.
Size of buf should be equal to or bigger than sizeof(short[samplefrequency]).
Call this function for every signal in the file. The order is important!
When there are 4 signals in the file, the order of calling this function
must be: signal 0, signal 1, signal 2, signal 3, signal 0, signal 1, signal 2, etc.
Returns 0 on success, otherwise -1
int edf_blockwrite_digital_short_samples(int handle, short *buf);
Writes "raw" digital samples from *buf.
buf must be filled with samples from all signals, starting with n samples of signal 0, n samples of signal 1, n samples of signal 2, etc.
where n is the samplefrequency of that signal.
One block equals one second.
The samples will be written to the file without any conversion.
Because the size of a short is 16-bit, do not use this function when you write a BDF file.
The number of samples written is equal to the sum of the samplefrequencies of all signals.
Size of buf should be equal to or bigger than sizeof(short) multiplied by the sum of the samplefrequencies of all signals
Returns 0 on success, otherwise -1
int edf_blockwrite_digital_3byte_samples(int handle, void *buf);
Writes "raw" digital samples from *buf.
buf must be filled with samples from all signals, starting with n samples of signal 0, n samples of signal 1, n samples of signal 2, etc.
where n is the samplefrequency of that signal.
One block equals one second.
The samples will be written to the file without any conversion.
Because the size of three bytes is 24-bit, do not use this function when you write an EDF file.
The number of samples written is equal to the sum of the samplefrequencies of all signals.
Size of buf should be equal to or bigger than: the sum of the samplefrequencies of all signals x 3 bytes
Returns 0 on success, otherwise -1
int edfwrite_annotation_utf8(int handle, long long onset, long long duration, const char *description);
Writes an annotation/event to the file.
onset is relative to the starttime and startdate of the file.
onset and duration are in units of 100 microSeconds! resolution is 0.0001 second!
For example: 34.071 seconds must be written as 340710.
If duration is unknown or not applicable: set a negative number (-1).
description is a null-terminated UTF8-string containing the text that describes the event.
This function is optional and can be called only after opening a file in writemode
and before closing the file.
int edfwrite_annotation_latin1(int handle, long long onset, long long duration, const char *description);
Writes an annotation/event to the file.
onset is relative to the starttime and startdate of the file.
onset and duration are in units of 100 microSeconds! resolution is 0.0001 second!
For example: 34.071 seconds must be written as 340710.
If duration is unknown or not applicable: set a negative number (-1).
description is a null-terminated Latin1-string containing the text that describes the event.
This function is optional and can be called only after opening a file in writemode
and before closing the file.
int edf_set_datarecord_duration(int handle, int duration);
Sets the datarecord duration. The default value is 1 second.
ATTENTION: the argument "duration" is expressed in units of 10 microSeconds!
So, if you want to set the datarecord duration to 0.1 second, you must give
the argument "duration" a value of "10000".
This function is optional, normally you don't need to change the default value.
The datarecord duration must be in the range 0.001 to 60.0 seconds.
Returns 0 on success, otherwise -1
This function is NOT REQUIRED but can be called after opening a
file in writemode and before the first sample write action.
This function can be used when you want to use a samplerate
which is not an integer. For example, if you want to use a samplerate of 0.5 Hz,
set the samplefrequency to 5 Hz and the datarecord duration to 10 seconds.
Do not use this function, except when absolutely necessary!
int edf_set_micro_datarecord_duration(int handle, int duration);
Sets the datarecord duration to a very small value.
ATTENTION: the argument "duration" is expressed in units of 1 microSecond!
This function is optional, normally you don't need to change the default value.
The datarecord duration must be in the range 1 to 99 micro-seconds.
Returns 0 on success, otherwise -1
This function is NOT REQUIRED but can be called after opening a
file in writemode and before the first sample write action.
This function can be used when you want to use a very high samplerate.
For example, if you want to use a samplerate of 5 GHz,
set the samplefrequency to 5000 Hz and the datarecord duration to 1 micro-second.
Do not use this function if not necessary.
This function was added to accommodate for high speed ADC's e.g. Digital Sampling Oscilloscopes.
int edf_set_subsecond_starttime(int handle, int subsecond);
Sets the subsecond starttime expressed in units of 100 nanoSeconds.
Valid range is 0 to 9999999 inclusive. Default is 0
This function is optional and can be called only after opening a file in writemode
and before the first sample write action
Returns 0 on success, otherwise -1
It is strongly recommended to use a maximum resolution of no more than 100 micro-Seconds.
e.g. use 1234000 to set a starttime offset of 0.1234 seconds (instead of 1234567)
in other words, leave the last 3 digits at zero
int edflib_version(void);
Returns the version number of this library, multiplied by hundred. If version is "1.00", it will return 100.
int edflib_is_file_used(const char *path);
Returns 1 if the file is used, either for reading or writing. Otherwise returns 0.
int edflib_get_number_of_open_files(void);
Returns the number of open files, either for reading or writing.
int edflib_get_handle(int file_number);
Returns the handle of an opened file, either for reading or writing. file_number starts with 0, returns -1 if the file is not opened.
EDFplus and BDFplus store the annotations in one or more signals (in order to be backwards compatibel with EDF and BDF).
The counting of the signals in the file starts at 0. Signals used for annotations are skipped.
This means that the annotationsignal(s) in the file are hided.
Use the function edf_get_annotation() to get the annotations.
So, when a file contains 5 signals and the third signal is used to store the annotations, the library will
report that there are only 4 signals in the file.
The library will "map" the signalnumbers as follows: 0->0, 1->1, 2->3, 3->4.
This way you don't need to worry about which signals are annotationsignals. The library will do it for you.
In order to keep the resulting filesize acceptable, EDFlib limits the maximum annotation description length
at 40 bytes.
To avoid rounding errors, the library stores some timevalues in variables of type long long int.
In order not to loose the subsecond precision, all timevalues have been multiplied by 10000000.
This will limit the timeresolution to 100 nanoSeconds. To calculate the amount of seconds, divide
the timevalue by 10000000 or use the macro EDFLIB_TIME_DIMENSION which is declared in edflib.h.
The following variables do use this when you open a file for reading:
"file_duration", "starttime_subsecond", "datarecord_duration" and "onset".
No. Discontinuous files can be converted to continuous files with EDFbrowser.
Originally, EDF has two headerfields reserved for the patientname and the recording info.
Both fields can each contain 80 bytes. EDF+ and BDF+ have divided these fields in subfields in order
to identify administrationcode, birthdate, etc. Because of backwards compatibility with EDF and BDF,
these subfields ared divided in two groups. Both groups have to share 80 bytes minus some other bytes
used for other purpose like startdate. The following table shows how many bytes are available for the
two groups. Birthdate takes 10 bytes.
| 72 bytes are available for: | patientname | patientcode | birthdate | patient_additional |
| 42 bytes are available for: | admincode | technician | equipment | recording_additional |
EDFlib will perform a maximum size check for these two groups and prevent against writing too many bytes
into the header.
samplefrequency = ((double)hdr.signalparam[edfsignal].smp_in_datarecord / (double)hdr.datarecord_duration) * EDFLIB_TIME_DIMENSION;
If n is an integer (has no fraction):
long long offset;
if(!(hdr.datarecord_duration % EDFLIB_TIME_DIMENSION))
{
offset = (n / (hdr.datarecord_duration / EDFLIB_TIME_DIMENSION)) * hdr.signalparam[edfsignal].smp_in_datarecord;
}
else
{
offset = (long long)(((double)n / ((double)hdr.datarecord_duration / (double)EDFLIB_TIME_DIMENSION)) * (double)hdr.signalparam[edfsignal].smp_in_datarecord);
}
edfseek(handle, edfsignal, offset, EDFSEEK_SET)));
If n has a fraction:
long long offset; offset = (long long)(((double)n / ((double)hdr.datarecord_duration / (double)EDFLIB_TIME_DIMENSION)) * (double)hdr.signalparam[edfsignal].smp_in_datarecord); edfseek(handle, edfsignal, offset, EDFSEEK_SET)));