readEDF: readEDF

In gjmvanboxtel/eegr: Electrophysiological data analysis

readEDF

Description

Read data from a European Data Format (EDF, EDF+, BDF, BDF+) file.

Usage

readEDF(
  file,
  records = "all",
  signals = "all",
  multifreq = c("group", "separate", "downsample", "upsample"),
  physical = TRUE
)

Arguments

file	Character string. The name of the file which the data are to be read from. file can also be a complete URL. (For the supported URL schemes,see the ‘URLs’ section of the help for url.)
records	Numeric or 'all'. In EDF, signals are stored in 'records', usually containing 0.5 or 1 second of data. This function either reads all records (default: all), or a subset of the records, thus limiting the time interval of the signals. records can be a range (e.g., 1:50) or a random sequence of records (e.g., c(1,5,12,3)). In the latter case, the records are returned in the specified order (only useful for discontinuous data). If length(records) == 0 or is.na(records), then no records are read and only the file header is returned.
signals	Numeric, character string, or 'all'. Specifies the signals to read from the input file. signals can be a range (e.g., 1:21) a random sequence of signals (e.g., c(1,5,12,3)), or a sequence of signal labels (e.g., c("F3", "Fz", "F4"). In the latter two cases, the signals are returned in the specified order. If length(signals) == 0 or is.na(signals), then no records are read and only the file header is returned.
multifreq	Character string. Specifies what to do when signals with different sampling frequencies are present in the file. Options are: "group" Signals with identical sampling frequencies are grouped together in a single ctd object (Default) "separate" Each signal will have its own ctd object "downsample" Signals with higher sampling frequencies are downsampled to the lowest frequency in the file "upsample" Signals with lower sampling frequencies are upsampled to the highest frequency in the file Up- and downsampling are performed by the resample function in the gsignal package. Note that this can take a lot of time, especially in case of upsampling to the frequency of the annotation signal (usually 1-2 kHz).
physical	Logical. If true, convert the digital data values to physical values. physval = gain * digival + offset, where gain = (physmax - physmin) / (digimax - digimin), and offset = physmax - gain * digimax. See the description of the header below for the definition of the variables used in these equations.

Details

The function readEDF reads files containing electrophysiological data stored in the European Data Format (EDF) or its variants.

EDF was published in 1992 and stores multichannel data, allowing different sample rates for each signal. Internally it includes a header and one or more data records. The header contains some general information (patient identification, start time...) and technical specs of each signal (calibration, sampling rate, filtering, ...), coded as ASCII characters. The data records contain samples as little-endian 16-bit integers.

EDF+ was published in 2003 and is largely compatible to EDF, but EDF+ files also allow coding discontinuous recordings as well as annotations, stimuli and events in UTF-8 format.

Biosemi developed an EEG acquisition system with 24-bit A/D converters, which could not be stored in the 16-bit EDF format. They introduced a 24-bit variant of EDF called BDF (Biosemi Data Format), and a BDF+ variant is sometimes also found.

The function readEDF can read all of these variants and produce different output that can be used for further processing by function in the eegr package.

Value

list (head, ctd, ..., anno). The function returns a list containing three possible elements: the file header, the data, and annotations, if present. The header is always returned; the other two elements depend on the input arguments.

header

A list named 'header' consisting of the following elements:

General header:

id0

First identification byte. For BDF: -1 (0xFF), for EDF: ASCII "0" (0x30, old) or " " (0x32, new)

id1

Identification string, "" for EDF, "BIOSEMI" for BDF (7 bytes ASCII)

lsi

Local subject identification (80 bytes ASCII)

lri

Local recording identification (80 bytes ASCII)

date

Starting date of recording (8 bytes ASCII - "dd.mm.yy")

time

Starting time of recording (8 bytes ASCII - "hh.mm.ss")

nbytes

Number of bytes in header record (converted from 8 bytes ASCII to numeric)

version

Reserved. Used for version of format. Empty for EDF, "EDF+C" for EDF continuous data, "EDF+D" for EDF discontinuous data, "BIOSEMI" or "24BIT" for BDF (44 bytes ASCII)

nrec

Number of data records (converted from 8 bytes ASCII to numeric), -1 if unknown

duration

Duration of one data record in seconds (converted from 8 bytes ASCII to numeric)

ns

Number of signals in each data record (converted from 4 bytes ASCII to numeric)

Signal-specific header (one for each signal in the file):

label

Signal labels, e.g. "Fpz", "Fz" (ns * 16 bytes ASCII)

transducer

Transducer type, e.g. "AgAgCl electrode" (ns * 80 bytes ASCII)

dimension

Physical dimension of signal, e.g., "uV", "Ohm" (ns * 8 bytes ASCII)

physmin

Physical minimum in units of dimension (ns * 8 bytes ASCII converted to numeric)

physmax

Physical maximum in units of dimension (ns * 8 bytes ASCII converted to numeric)

digimin

Digital minimum ((ns * 8 bytes ASCII converted to numeric)

digimax

Digital maximum (ns * 8 bytes ASCII converted to numeric)

gain

Gain factor used for mapping digital to physical values (ns * numeric)

offset

Offset value used for mapping digital to physical values (ns * numeric)

prefilt

Prefiltering, e.g., "TC:3s;LP:70Hz" (ns * 80 bytes ASCII)

nsamp

Number of samples in one data record (ns * 8 bytes ASCII converted to numeric)

resvd

Reserved (ns * 32 bytes ASCII)

data

One or more Continuous Time Domain (ctd) objects. If the input file contains signals which all have the same sampling frequency, or if either the "upsample" or "downsample" options were specified in the multifreq parameter, then there is a single ctd object, and it is named 'ctd'.

In case of multiple sampling frequencies, then if the multifreq = "group", as many ctd objects are returned as there are sampling frequencies, and they are named ctdF, where F equals the sampling frequency of the data in that object. For instance, for a data file with sampling frequencies of 256 and 1024 Hz, two ctd objects will be returned, named ctd256 and ctd1024.

In case multifreq = "separate" is specified, there will be as many ctd objects as there are signals, and they will be named 'ctd1...ctdN', where N equals the number of signals in the file.

annotations

A (list of) data frame(s) named 'anno' containing the annotations parsed from the EDF+/BDF+ annotation channels, or from the Biosemi 'status' channel. Each annotation consists of the following fields:

sample

sample number of annotation

time

corresponding time, relative to beginning of file

value

value of annotation, as per EDF+ specification, see https://www.edfplus.info/specs/edfplus.html. For Biosemi this ia a 16 bit number, as only bits 0-15 of 24 are used as triggers, see http://biosemi.com/faq/trigger_signals.htm

. For EDF+ and BDF+ files, the Time-stamped Annotation Lists (TALs) will also be returned. In this case, sample numbers and times are relative to the beginning of the file, irrespective of the records read.

Author(s)

Geert van Boxtel, [e-mail]

References

Kemp B., Värri, A., Rosa, A.C., Nielsen, K.D. and Gade, J. (1992). A simple format for exchange of digitized polygraphic recordings. Electroencephalogr Clin Neurophysiol, 82(5), 391-393.

Kemp, B. and Olivan, J. (2003). European data format ’plus’ (EDF+), an EDF alike standard format for the exchange of physiological data. Clin Neurophysiol, 114(9), 1755-1761.

European Data Format. https://www.edfplus.info/

Which file format does Biosemi use? https://www.biosemi.com/faq/file_format.htm

Examples

## Not run: 
  edf <- readEDF('test.edf', signals = 1:10, records = "all")
  summary(edf$ctd)
  header <- readEDF(file.bdf, records = NA)
  header

## End(Not run)

gjmvanboxtel/eegr documentation built on May 20, 2023, 4:26 a.m.