Introduction

The European Data Format (EDF) is a simple and flexible format for exchange and storage of multichannel biological and physical signals. It was developed by a few European ‘medical’ engineers who first met at the 1987 international Sleep Congress in Copenhagen. See http://www.edfplus.info/

The original EDF specification has been expanded in several ways. EDF+ supports the addition of annotations and non-continuous recordings. The BioSemi Data Format BDF format uses 24 bits per sample (in stead of the 16 bits per sample in EDF). And BDF+ is an EDF+ like extension of BDF.

This packages supports all these variants.

Both EDF and BDF files consist of an header followed by one or more data records with the recorded signals, either ordinary signals or annotation signals.

This package follows this structure by providing two basic functions: readEdfHeader and readEdfSignals (see the help pages for details)

The examples below are based on the following files:

AFile an EDF+ file with a continuous recording of 2 ordinary signals, two annotation signals and a sub second start specification
BFile a BDF+ file with a continuous recording of 11 ordinary signals and one annotation signal
CFile an EDF+ file with a continuous recording of 11 ordinary signals and one annotation signal
DFile an EDF+ file with a discontinuous recording of 11 ordinary signals and one annotation signal

The BFile, CFile and DFile are derived from the “test_generator_2” test files from http://www.teuniz.net/edf_bdf_testfiles. The AFile is derived from the “test_generator8” file received from Teunis van Beelen by private communications.

libDir <- system.file ("extdata", package="edfReader")
AFile <- paste (libDir, '/edfAnnonC.edf', sep='') # a file with 2 annotation signals
BFile <- paste (libDir, '/bdfPlusC.bdf' , sep='') # a continuously recorded BDF file
CFile <- paste (libDir, '/edfPlusC.edf' , sep='') # a continuously recorded EDF file
DFile <- paste (libDir, '/edfPlusD.edf' , sep='') # a discontinuously recorded EDF file

EDF headers objects

Introduction

The readEdfHeader function returns a list of class ‘ebdfHeader’ with all the data from the EDF or BDF file header. Part of this list is a data frame of class ‘ebdfSHeader’ which contains the signal headers.

The ebdfHeader

A file header can be read with readEdfHeader()

require (edfReader)
AHdr  <- readEdfHeader (AFile)
BHdr  <- readEdfHeader (BFile)
CHdr  <- readEdfHeader (CFile)            
DHdr  <- readEdfHeader (DFile)

Summaries of the header data can be shown with the S3 summary () and print() functions

BHdr

##  Patient               : X X X X 
##  RecordingId           : Startdate 10-DEC-2009 X X test_generator 
##  StartTime             : 2009-12-10 12:45:54 
##  Continuous recording  : TRUE 
##  Signal labels         : squarewave, ramp, pulse, ECG, noise, sine 1 Hz, sine 8 Hz, sine 8.5 Hz, sine 15 Hz, sine 17 Hz, sine 50 Hz, BDF Annotations

summary (AHdr)

##  File name             : /Library/Frameworks/R.framework/Versions/3.2/Resources/library/edfReader/extdata/edfAnnonC.edf 
##  File type             : EDF+ 
##  Version               : 0 
##  Patient               : X X X X 
##  RecordingId           : Startdate 01-JAN-2000 X X X 
##  StartTime             : 2000-01-01 14:15:16.7 
##  Continuous recording  : TRUE 
##  Recorded period       : 1.2 sec 
##  Ordinary signals      : 2 
##  Annotation signals    : 2 
##  Signal labels         : EDF Annotations, Channel 1, EDF Annotations, Channel 2 
##  R signal names        : EDF Annotations-1, Channel 1, EDF Annotations-2, Channel 2 
##  Note                  : duplicate label names

The summary() provides somewhat more information than the print() function. For all details use str().

edfAnnonC.edf contains two annotation. These signals must have the same label. As edfReader names signals after their labels (see below), distinguished names are created by appending ‘-1’ and ‘-2’ to the labels.

NOTE Actually, the startTime fraction .7 is not read from the edf/bdf file header but from the first data record. For details, see the section “Samples, time and periods”.

The ebdfSHeader

Summaries of the signal header data can be shown with the S3 print() and summary () functions.

AHdr$sHeader

##  Signal labels         : EDF Annotations, Channel 1, EDF Annotations, Channel 2 
##  R signal names        : EDF Annotations-1, Channel 1, EDF Annotations-2, Channel 2 
##  Note                  : duplicate label names

summary (CHdr$sHeader)

##    signal           label            name transducer sampleRate preFilter
## 1       1      squarewave      squarewave                   200          
## 2       2            ramp            ramp                   200          
## 3       3           pulse           pulse                   200          
## 4       4             ECG             ECG                   200          
## 5       5           noise           noise                   200          
## 6       6       sine 1 Hz       sine 1 Hz                   200          
## 7       7       sine 8 Hz       sine 8 Hz                   200          
## 8       8     sine 8.5 Hz     sine 8.5 Hz                   200          
## 9       9      sine 15 Hz      sine 15 Hz                   200          
## 10     10      sine 17 Hz      sine 17 Hz                   200          
## 11     11      sine 50 Hz      sine 50 Hz                   200          
## 12     12 EDF Annotations EDF Annotations                    NA

EDF signal objects

Introduction

The readEdfSignals function with simplify=FALSE returns a list of class ‘ebdfSignals’ with the signals selected from the EDF / BDF file.

The signals in this list are of the following :

continuous signals
of class ‘ebdfCSignal’ which may result from all types of EDF(+)/BDF(+) files
fragmented signals
of class ‘ebdfFSignal’ which result from EDF+D and BDF+D files only
annotation signals
of class ‘ebdfASignal’ which may result from all types of EDF+ and BDF+ files.

Reading the whole recording of all signals

The signals in an EDF or BDF file can be read with the readEdfSignals function.

ASignals <- readEdfSignals (AHdr)
ASignals

## Annotation signal: 
##   signal annotations      from     till
## 1    1,3           8 0.749 sec 1.89 sec
## Ordinary signals: 
##  Continuous recording    : TRUE 
##  Period read             : 1.2 sec = whole recording 
##           signal     label transducer sampleRate samples preFilter
## Channel 1      2 Channel 1                 30000   36000          
## Channel 2      4 Channel 2                 20000   24000

NOTE 1 See below in case the file contains only one signal.

NOTE 2 The annotation signal number ‘1,3’ indicates that the ‘ebdfASignal’ annotation object contains the annotations from both signals 1 and 3. This can be prevented by using the ‘mergeASignals=FALSE’ option.

DSignals <- readEdfSignals (DHdr)
DSignals

## Annotation signal: 
##   signal annotations  from  till
## 1     12           1 0 sec 0 sec
## Ordinary signals: 
##  Continuous recording    : FALSE 
##  Period read             : 20 sec = whole recording 
##             signal       label transducer sampleRate samples preFilter
## squarewave       1  squarewave                   200    4000          
## ramp             2        ramp                   200    4000          
## pulse            3       pulse                   200    4000          
## ECG              4         ECG                   200    4000          
## noise            5       noise                   200    4000          
## sine 1 Hz        6   sine 1 Hz                   200    4000          
## sine 8 Hz        7   sine 8 Hz                   200    4000          
## sine 8.5 Hz      8 sine 8.5 Hz                   200    4000          
## sine 15 Hz       9  sine 15 Hz                   200    4000          
## sine 17 Hz      10  sine 17 Hz                   200    4000          
## sine 50 Hz      11  sine 50 Hz                   200    4000

By default all fragments in a discontinuously recorded signals will be concatenated into one signal with the gaps filled with NA values. This can be prevented by using the ‘fragments=TRUE’ option.

DSignalsF <- readEdfSignals (DHdr, fragments = TRUE)
DSignalsF

## Annotation signal: 
##   signal annotations  from  till
## 1     12           1 0 sec 0 sec
## Ordinary signals: 
##  Continuous recording    : FALSE 
##  Period read             : 20 sec = whole recording 
##             signal       label transducer sampleRate samples preFilter
## squarewave       1  squarewave                   200       1          
## ramp             2        ramp                   200       1          
## pulse            3       pulse                   200       1          
## ECG              4         ECG                   200       1          
## noise            5       noise                   200       1          
## sine 1 Hz        6   sine 1 Hz                   200       1          
## sine 8 Hz        7   sine 8 Hz                   200       1          
## sine 8.5 Hz      8 sine 8.5 Hz                   200       1          
## sine 15 Hz       9  sine 15 Hz                   200       1          
## sine 17 Hz      10  sine 17 Hz                   200       1          
## sine 50 Hz      11  sine 50 Hz                   200       1

A summary of the list of signals can be shown with the S3 summary () functions. For this ‘ebdfSignals’ objects it shows the same data as the S3 print function (see above). For object details use the str() function.

Reading a selection of signals

The reading of signals can be restricted to specific set by using the signals parameter. Signals can be identified by their signal number, label, name, or signal type (‘Ordinary’ or ‘Annotations’). Also, the list may contain duplicates. The following 3 designations refer e.g. to the same signal.

CSignals8 <- readEdfSignals (CHdr, signals=c(8, "8", "sine 8.5 Hz"))
CSignals8

##  Signal number           : 8 
##  Label                   : sine 8.5 Hz 
##  StartTime               : 2009-12-10 12:44:02 
##  Continuous recording    : TRUE 
##  Recorded period         : 20 sec 
##  Period read             : 20 sec 
##  Transducer              :  
##  Range                   : -1000 : 1000 uV 
##  Prefilter               :  
##  Bits per sample         : 16 
##  Sample rate             : 200 
##  Number of samples       : 4000

NOTE As in this case only one signal was read, the list of one was simplified to a singe ‘ebdfCSignal’ object. This could be prevented by using the ‘simplify=FALSE’ parameter.

EXAMPLE readEdfSignals (CHdr, signals=7, simplify=FALSE)[[1]] and readEdfSignals (CHdr, signals=7) will return the same object.

Reading a selected period

If required the reading can be restricted also to a particular period. A period is identified with the ‘from’ and ‘till’ parameters which specify a time in seconds relative to start of the recording.

ASignalsPeriod    <- readEdfSignals (AHdr, from=0.7, till=1.8)
ASignalsPeriod

## Annotation signal: 
##   signal annotations      from    till
## 1    1,3           6 0.749 sec 1.8 sec
## Ordinary signals: 
##  Continuous recording    : TRUE 
##  Period read             : 0.5 sec starting at 0.7 sec till the end 
##           signal     label transducer sampleRate samples preFilter
## Channel 1      2 Channel 1                 30000   15000          
## Channel 2      4 Channel 2                 20000   10000

NOTE 1 The annotations included are those with an onset up to and including 1.8 sec. The onset for an annotation may be outside the recorded period.

NOTE 2 Because the recorded period is only 1.2 sec (see above or use summary(ASignalsPeriod)), the period read will not be [0.7, 1.8) but only [0.7, 1,2).

NOTE 3 For time and rounding details see the section “Samples, time and periods”

Summaries of a list of signals can be shown with the S3 print() and summary () functions.

Ordinary signals, continuously recorded

Summaries of a continuously recorded ordinary signal can be shown with the S3 print() and summary () functions.

CSignals <- readEdfSignals (CHdr)
summary (CSignals$pulse)         # edfReader names signals after their label

##  Signal number           : 3 
##  Label                   : pulse 
##  StartTime               : 2009-12-10 12:44:02 
##  Continuous recording    : TRUE 
##  Recorded period         : 20 sec 
##  Period read             : 20 sec 
##  Transducer              :  
##  Range                   : -1000 : 1000 uV 
##  Prefilter               :  
##  Bits per sample         : 16 
##  Sample rate             : 200 
##  Number of samples       : 4000 
##  Signal summary          :

##     Min.  1st Qu.   Median     Mean  3rd Qu.     Max. 
##  0.01526  0.01526  0.01526  2.01500  0.01526 99.99000

Ordinary signals, not continuously recorded

Ordinary signals that are not continuously recorded can be read in two different ways:

as a ‘continuous’ sequence of samples with ‘NA’ values filling the gaps (use ‘fragments=FALSE’, the default).
The result is of class ‘ebdfCSignal’ (the same as for a continuously recorded signal).
as a number fragments of continuously recorded parts (use ‘fragments=TRUE’)
The result is of class ‘ebdfFSignal’.

The latter method will use a more complex data structure, the first may result in a (much too) huge object.

CDSignals <- readEdfSignals (DHdr, from=5.1, till=18)
FDSignals <- readEdfSignals (DHdr, fragments=TRUE)

The objects of class ‘ebdfCSignal’ are printed and summarised in the same way as continuously recorded signals.

Summaries of a not continuously recorded ordinary signal stored in fragments can be shown with the S3 print() and summary () functions.

summary (FDSignals$`sine 8.5 Hz`)         # note the "`" quotes for a name with spaces.

##  Signal number           : 8 
##  Label                   : sine 8.5 Hz 
##  StartTime               : 2009-12-10 12:44:02 
##  Continuous recording    : FALSE 
##  Total period            : 20 sec 
##  Recorded period         : 11 sec 
##  Read from total period  : 20 sec 
##  Transducer              :  
##  Range                   : -1000 : 1000 uV 
##  Prefilter               :  
##  Bits per sample         : 16 
##  Sample rate             : 200 
##  Number of fragments     : 6 
##   fragment start samples   Min. X1st.Qu.   Median     Mean X3rd.Qu.  Max.
## 1        1     0     200 -99.87   -65.22  9.41500  3.73800    71.82 99.99
## 2        2     2     200 -99.87   -65.22  9.41500  3.73800    71.82 99.99
## 3        3     4    1200 -99.96   -70.70  0.01526  0.01526    70.73 99.99
## 4        4    12     200 -99.87   -65.22  9.41500  3.73800    71.82 99.99
## 5        5    15     200 -99.96   -71.79 -9.38400 -3.70800    65.25 99.90
## 6        6    19     200 -99.96   -71.79 -9.38400 -3.70800    65.25 99.90
## All fragments:
##      Min.   1st Qu.    Median      Mean   3rd Qu.      Max. 
## -99.96000 -70.70000   0.01526   0.35370  70.73000  99.99000

NOTE In case of more then 10 fragments, the list of fragments summaries will be limited to 5 followed by the number of omitted summaries.

Annotation signals

Summaries of an annotation signal (ASignal) can be shown with the S3 print() and summary () functions.

CSignals$`EDF Annotations`

##  Signal number           : 12 
##  Label                   : EDF Annotations 
##  StartTime               : 2009-12-10 12:44:02 
##  Record start specs      : 0 
##  Annotations             : 2 
##  Time first annotation   : 0 sec 
##  Time last annotation    : 600 sec (= 00:10:00)

summary(ASignalsPeriod$`EDF Annotations`)

##  Signal number           : 1 3 
##  Label                   : EDF Annotations 
##  StartTime               : 2000-01-01 14:15:16.7 
##  Record start specs      : 0 
##  Annotations             : 6 
##  Time first annotation   : 0.749 sec 
##  Time last annotation    : 1.8 sec

NOTE 1 Because both annotation signals are merged into one, the merged signal is named EDF Annotations again.

NOTE 2 The “Record start specs = 0” indicates that the record start specifications are not included, i.e. readEdfSignals was used with the parameter recordStartTimes = FALSE.

Samples, time and periods.

The start time

In case of an EDF or BDF file, the startTime attribute is based on the startdate and starttime in the EDF/BDF header.

The starttime in an EDF/BDF header is specified up to the second.

In EDF+ and BDT+ files a sub second start time can be specified as the start time of the first data record. See the last paragraph in section .2.2.4 of the EDF+ specification.

See, e.g., the startTime for the

format (AHdr$startTime, format="%Y-%m-%d %H:%M:%OS3",  usetz = FALSE)

## [1] "2000-01-01 14:15:16.700"

ASignalsPlusStartTimes <- readEdfSignals(AHdr, signals='EDF Annotations-1', recordStarts=TRUE)
annots <- ASignalsPlusStartTimes$annotations
annots[annots$isRecordStart==TRUE,'onset'][1]

## [1] 0.7

For EDF+ and BDT+ files, the startTime shown by the edfReader is based on both the data in the header and in the start time of the first data record.

Samples and time

As usual, a recording starts at time 0 with sample 1.

Consequently sample n will be at time (n-1)/sRate, where sRate denotes the sample rate.

Samples and periods

Apart from rounding errors, a from - till period in readEdfSignals will be the period [from,till), i.e. starting at from and up to be but not including till.

This may sound strange, but this convention has the following properties

the sample rate can be defined as the total number of samples divided by the total time
or, more precise, any period which is a multiple of the sample period sPeriod will always contain the same number of samples
i.e. for any t ≥ 0, [t, t+n*sPeriod) will always contain n samples
for any number of adjacent periods, the total number of samples will be always the sum of the samples in the individual periods.
the first sample will be ceiling(from*sRate) + 1
the last sample will be ceiling(till*sRate)
with from=t and till=t, the empty set [t,t) corresponds to [ceiling(t*sRate) + 1, ceiling(t*sRate)] which is also empty.

Alignment

The problem

In an EDF+/BDF+ file the start of the recording of the signals in a data record is specified in its first annotations signal. For a +D file the recording in a subsequent data record may start at any time after the start of the previous data record plus the record duration time.

The gap between to +D file data records may not be an exact multiple of the sample period of its signals. This raises a question about the alignment of samples in these subsequent data records.

Two basic models.

The alignment of ordinary signals can be modelled in two different ways:

with a interrupted clock
In which case the first sample for every recorded signal is taken at the start of the recording for that data record
which a continuously running clock
In which case the clock starts at the start of the first record and all sampling is based on the individual signal sample rate(s). In other words, the sample time for a signal sample in the data records is aligned to its sample rate.

It should be noted that the model with the continuously running clock is (implicitly) required if one want to map all fragments of a signal into a single single (with NA values in the gap) one.

The edfReader supports both models, for any fragment it provides both the aligned data according to the “continuously running clock” model as well as the record start time from the data record.

Alignment details

The first sample in every +D record can be aligned as follows:

n = ceiling (sRate * recordStartTime) + 1

and the

sampleTime = (n - 1) / sRate

Where

sRate is the sample rate
n is the sample number when continuously sampled from the start of the recording
recordStartTime denotes the start of the record relative to the start of the recording
sampleTime the (aligned) sample time for the n’s sample

However, in order to avoid rounding unnecessary rounding errors the first formula is actually implemented as follows:

n = ceiling (sRate * (recordStartTime - maxTErr)) + 1

Where maxTErr = 5 * .Machine$double.eps (= normally 5 * 2.220446e-16 = 1.110223e-15 )

Parameters involved

For any signal object and any fragment:

the ‘start’ parameter contains the aligned signal / fragment start time in seconds, relative to the start in the recording (for a signal it is always 0)
the ‘fromSample’ parameter contains the sample number for the corresponding sample
the ‘recordingStart’ parameter contains the start of the recording for the data record. For a ‘+’ file this is the time specified in the first annotation signal
a ‘from’ parameter in an readEdfSignals invocation is relative to the start of the recording. The default value is 0
a ‘till’ parameter in an readEdfSignals invocation is relative to the start of the recording. The default value is Inf
a ‘recordedPeriod’ parameter equals the number of data records times the record duration time as specified in the header
a totalPeriod parameter contains the period from the start time in the header till the end of the recording, i.e. the record start time of the last data record plus the record duration time

Object details

Header details

Header attributes

The header data encompass the following:

str (CHdr,  max.level=1)

## List of 17
##  $ fileName           : chr "/Library/Frameworks/R.framework/Versions/3.2/Resources/library/edfReader/extdata/edfPlusC.edf"
##  $ fileType           : chr "EDF"
##  $ version            : chr "0"
##  $ patient            : chr "X X X X"
##  $ recordingId        : chr "Startdate 10-DEC-2009 X X test_generator"
##  $ startTime          : POSIXct[1:1], format: "2009-12-10 12:44:02"
##  $ headerLength       : int 3328
##  $ reserved           : chr "EDF+C"
##  $ nRecords           : int 20
##  $ recordDuration     : num 1
##  $ nSignals           : int 12
##  $ recordedPeriod     : num 20
##  $ sampleBits         : num 16
##  $ isPlus             : logi TRUE
##  $ isContinuous       : logi TRUE
##  $ sHeaders           :Classes 'ebdfSHeaders' and 'data.frame':  12 obs. of  15 variables:
##  $ startSecondFraction: num 0
##  - attr(*, "class")= chr "ebdfHeader"

The fields version, patient, recordingId, startTime, headerLength, reserved, nRecords, recordDuration, and nSignals are from the file header.

the startSecondFraction attribute contains the sub second start data specified in the first data record. See the ‘The start time’ section above.

NOTE In order to avoid annoying rounding errors, the sub second start time is stored separately. trunc (startTime, ‘sec’) is less accurate.

sHeader is detailed below. The others attributes are derived ones.

Signal header attributes

The signal header data encompass the following:

str (CHdr$sHeader, max.level=1)

## Classes 'ebdfSHeaders' and 'data.frame': 12 obs. of  15 variables:
##  $ label           : chr  "squarewave" "ramp" "pulse" "ECG" ...
##  $ transducerType  : chr  "" "" "" "" ...
##  $ physicalDim     : chr  "uV" "uV" "uV" "uV" ...
##  $ physicalMin     : num  -1000 -1000 -1000 -1000 -1000 -1000 -1000 -1000 -1000 -1000 ...
##  $ physicalMax     : num  1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 ...
##  $ digitalMin      : int  -32768 -32768 -32768 -32768 -32768 -32768 -32768 -32768 -32768 -32768 ...
##  $ digitalMax      : int  32767 32767 32767 32767 32767 32767 32767 32767 32767 32767 ...
##  $ preFilter       : chr  "" "" "" "" ...
##  $ samplesPerRecord: int  200 200 200 200 200 200 200 200 200 200 ...
##  $ reserved        : chr  "" "" "" "" ...
##  $ gain            : num  0.0305 0.0305 0.0305 0.0305 0.0305 ...
##  $ offset          : num  0.0153 0.0153 0.0153 0.0153 0.0153 ...
##  $ sRate           : num  200 200 200 200 200 200 200 200 200 200 ...
##  $ isAnnotation    : logi  FALSE FALSE FALSE FALSE FALSE FALSE ...
##  $ sLength         : int  4000 4000 4000 4000 4000 4000 4000 4000 4000 4000 ...

The fields label, transducerType, physicalDim, physicalMin, physicalMax, digitalMin, digitalMax, preFilter, samplesPerRecord, and reserved are from the file header. The others are derived. Gain and offset are used to map the digital sample values to the range of physical values.

For annotation signals the only relevant fields are “label” which must have the value “EDF Annotations” (or “BDF Annotations”) and “samplesPerRecord”.

Signal details

Ordinary signal objects of class ‘ebdfCSignal’

The data for ordinary signal objects of class ‘ebdfCSignal’ encompass the following:

str(CSignals$pulse, max.level=1)

## List of 17
##  $ signal        : num [1:4000] 99.9924 99.9924 99.9924 99.9924 0.0153 ...
##  $ startTime     : POSIXct[1:1], format: "2009-12-10 12:44:02"
##  $ signalNumber  : int 3
##  $ label         : chr "pulse"
##  $ isContinuous  : logi TRUE
##  $ isAnnotation  : logi FALSE
##  $ recordedPeriod: num 20
##  $ totalPeriod   : num 20
##  $ from          : num 0
##  $ till          : num Inf
##  $ start         : num 0
##  $ fromSample    : num 1
##  $ transducerType: chr ""
##  $ sampleBits    : num 16
##  $ sRate         : num 200
##  $ range         : chr "-1000 : 1000 uV"
##  $ preFilter     : chr ""
##  - attr(*, "class")= chr "ebdfCSignal"

The attributes startTime, signalNumber, label, isContinuous, isAnnotation, recordedPeriod, totalPeriod, transducerType, sampleBits, sRate, range, and preFilter are (derived) from the header data.

For a continuously recorded signal the totalPeriod is equal to the recordedPeriod. For a not continuously recorded signal the total period equals the start of the last data record plus its duration.

The attributes from and till contain the values of the corresponding actual readEdfSignals parameters. The default values are 0 and Inf.

The start attribute contains the start time and is always zero. The fromSample attribute contains the first sample number and is always 1. By including these attributes, signals and fragments share the same time/sample attributes.

The signal attribute contains the sample data from the EDF / BDF data records. If read with the readEdfSignals parameter physical=TRUE, the default, the digital sample values are mapped to physical values. With physical=FALSE, signals contains the digital sample values.

The physical values are calculated as follows:
physicalValue = gain * digitalValue + offset,
with: gain = (physicalMax - physicalMin) / (digitalMax - digitalMin)
offset = physicalMax - gain * digitalMax

Ordinary signal objects of class ‘ebdfFSignal’

The data for ordinary signal objects of class ‘ebdfFSignal’ encompass the following:

str(FDSignals$`sine 8.5 Hz`, max.level=1)

## List of 17
##  $ startTime     : POSIXct[1:1], format: "2009-12-10 12:44:02"
##  $ signalNumber  : int 8
##  $ label         : chr "sine 8.5 Hz"
##  $ isContinuous  : logi FALSE
##  $ isAnnotation  : logi FALSE
##  $ recordedPeriod: num 11
##  $ totalPeriod   : num 20
##  $ from          : num 0
##  $ till          : num Inf
##  $ start         : num 0
##  $ fromSample    : num 1
##  $ transducerType: chr ""
##  $ sampleBits    : num 16
##  $ sRate         : num 200
##  $ range         : chr "-1000 : 1000 uV"
##  $ preFilter     : chr ""
##  $ fragments     :List of 6
##  - attr(*, "class")= chr "ebdfFSignal"

For the attributes startTime, signalNumber, label, isContinuous, isAnnotation, recordedPeriod, totalPeriod, from, till, start, fromSample, transducerType, sampleBits, sRate, range and preFilter see the previous section.

For a not continuously recorded signal the total period equals the start of the last data record plus its duration.

The fragments attribute contains the list of recorded fragments.

Signal fragment data

The data of a signal fragment in objects of class ‘ebdfFSignal’ encompass the following:

str(FDSignals$`sine 8.5 Hz`$fragments[[1]], max.level=1)

## List of 4
##  $ start         : num 0
##  $ fromSample    : num 1
##  $ recordingStart: num 0
##  $ signal        : num [1:200] 26.4 50.9 71.8 87.6 97.2 ...

The fromSample attribute contains the sample number of the first sample in this fragment (as if it were a continuous recording). The start attribute the sample time for this sample.

The ‘signal’ attribute contains the fragment’s sample values. These may be physical values (the default) or digital values (see above).

Annotation signals

The data for annotation signal objects of class ‘ebdfASignal’ encompass the following:

str(ASignals$`EDF Annotations`, max.level=1)

## List of 9
##  $ startTime   : POSIXct[1:1], format: "2000-01-01 14:15:16"
##  $ signalNumber: int [1:2] 1 3
##  $ label       : chr "EDF Annotations"
##  $ isContinuous: logi TRUE
##  $ isAnnotation: logi TRUE
##  $ totalPeriod : num 1.2
##  $ from        : num 0
##  $ till        : num Inf
##  $ annotations :'data.frame':    8 obs. of  6 variables:
##  - attr(*, "class")= chr "ebdfASignal"

For the attributes startTime, signalNumber, label, isContinuous, isAnnotation, totalPeriod, from, and till see the section for objects of class ‘ebdfCSignal’.

The annotations attribute contains a data frame with the individual annotations.

Annotation data

The data for a single annotation encompass the following:

str(ASignals$`EDF Annotations`$annotations, max.level=1)

## 'data.frame':    8 obs. of  6 variables:
##  $ record       : int  1 2 2 2 11 12 12 12
##  $ onset        : num  0.749 0.8 0.84 0.872 1.719 ...
##  $ duration     : num  NA NA NA 0.005 NA NA 0.005 NA
##  $ isRecordStart: logi  FALSE FALSE FALSE FALSE FALSE FALSE ...
##  $ annotation   : chr  "Test1" "Test2" "Test3" "Test4" ...
##  $ fromSignal   : int  3 1 1 1 3 1 1 1

The record attribute refers to the data record the annotation was read from.

The onset attribute contains the time of the annotation relative to the start of the recording.

The duration attribute contains the duration of the annotated event.

The isRecordStart indicates whether or not this annotation is the first one in a data record (and indicates the start time of the recording of that record).

The annotation attribute contains the annotations associated with the onset and duration.

The fromSignal attribute, if present, refers to the signal that contains the annotation. This attributed is present only if the annotations from different signals were merged into one ‘ebdfASignal’ object.

Next step: a quick look

One of the the first things you may want to do with the imported signals is to have look at them.

This can be acheived with one of the several plot packages available, e.g.:

- ‘plot’ (included in the base installation)

- ‘lattice', or

- 'ggplot2'

As an example, the function plotEdfSignals() uses ggplot2 and will plot one or more signals
over some period of time. The plot shown presents the period from 0.2 till 0.5 seconds of the ‘sine 8.5 Hz’ and the ‘sine 50 Hz’ signals in CSignals.

plotEdfSignals <- function (signals,labels, from=0, till=Inf) {
    nLabels <- length (labels)
    sRate   <- numeric (length = nLabels)
    fromS   <- integer (length = nLabels)
    tillS   <- integer (length = nLabels)
    sLength <- integer (length = nLabels)
    for (i in 1:nLabels) {
        sRate[i]    <- signals[[labels[i]]]$sRate
        fromS[i]    <- ceiling (sRate[i] * max (from, 0)) +1
        tillS[i]    <- ceiling (sRate[i] * till)
        tillS[i]    <- min (tillS[i], length(signals[[labels[i]]]$signal))
        sLength[i]  <- tillS[i] - fromS[i] + 1 
    }
    totLength  <- sum (sLength)
    cat (" totLength=",  totLength)
    time    <- numeric   (length = totLength)
    signal  <- numeric   (length = totLength)
    label   <- character (length = totLength)
    from <- 1
    for (i in 1:nLabels) {
        till <- from + sLength[i] - 1
        time  [from:till]   <- seq (from=fromS[i]-1, to=(tillS[i]-1)) / sRate[i]
        signal[from:till]   <- signals[[labels[i]]]$signal[fromS[i]:tillS[i]]
        label [from:till]   <- rep(labels[i], sLength[i])
        from <- till + 1
    }
    cat (" | from-1=", from-1,'\n')
    
    ggplotDF <- data.frame (time=time, signal=signal, label=label)
    ggplot (ggplotDF, aes(x=time, y=signal, colour=label)) + geom_line()
}

if (require(ggplot2)) {
    CSignals <- readEdfSignals (CHdr)
    plotEdfSignals (CSignals, labels=c('sine 8.5 Hz', 'sine 50 Hz'), from=.2, till=0.5)
}

##  totLength= 120 | from-1= 120

For details about ggplot2 see e.g. the ‘R Graphics cookbook’

Enjoy.

Acknowledgement

This package has used code from

edf.R version 0.3 (27-11-2013) from from Fabien Feschet,
http://data-auvergne.fr/cloud/index.php/s/WYmFEDZylFWJzNs
the work of Henelius Andreas as of July 2015,
https://github.com/bwrc/edf

References

Specification of EDF
http://www.edfplus.info/specs/edf.html
Specification of EDF+
http://www.edfplus.info/specs/edfplus.html
Specification of EDF++
http://195.154.67.227/en/contribute/edf/
Specification of BDF
see ‘Which file format does BioSemi use’ at
http://www.biosemi.com/faq/file_format.htm
Specification of BDF+
http://www.teuniz.net/edfbrowser/bdfplus%20format%20description.html

Other useful EDF related sources can be found at:
http://www.edfplus.info/downloads/ /

edfReader vignette

Jan Vis

2016-04-17

Introduction

EDF headers objects

Introduction

The ebdfHeader

The ebdfSHeader

EDF signal objects

Introduction

Reading the whole recording of all signals

Reading a selection of signals

Reading a selected period

Ordinary signals, continuously recorded

Ordinary signals, not continuously recorded

Annotation signals

Samples, time and periods.

The start time

Samples and time

Samples and periods

Alignment

The problem

Two basic models.

Alignment details

Parameters involved

Object details

Header details

Header attributes

Signal header attributes

Signal details

Ordinary signal objects of class ‘ebdfCSignal’

Ordinary signal objects of class ‘ebdfFSignal’

Signal fragment data

Annotation signals

Annotation data

Next step: a quick look

Acknowledgement

References