EDFPlus.jl

Julia for handling BDF+ and EDF+ EEG and similar signal data files.

Heavily influenced by the C EEG library edflib.

Data Structs and Functions

Structs:

mutable struct ChannelParam      # this structure contains all the relevant EDF-signal parameters of one signal
    label::String                  # label (name) of the signal, eg "C4" if in 10-20 labeling terms
    transducer::String             # signal transducer type
    physdimension::String          # physical dimension (uV, bpm, mA, etc.)
    physmax::Float64               # physical maximum, usually the maximum input of the ADC
    physmin::Float64               # physical minimum, usually the minimum input of the ADC
    digmax::Int                    # digital maximum, usually the maximum output of the ADC, cannot be higher than 32767 for EDF or 8388607 for BDF
    digmin::Int                    # digital minimum, usually the minimum output of the ADC, cannot be lower than -32768 for EDF or -8388608 for BDF
    smp_per_record::Int            # number of samples of this signal in a datarecord
    prefilter::String              # channel prefiltering settings if any
    reserved::String               # header reserved ascii text, 32 bytes
    offset::Float64                # offset of center of physical data value from center of digital values
    bufoffset::Int                 # bytes from start of record to start of this channel (zero for first channel)
    bitvalue::Float64              # physical data value of one unit change in digital value
    annotation::Bool               # true if is an annotation not a binary mapped signal data channel
    ChannelParam() = new("","","",0.0,0.0,0,0,0,"","",0.0,0,0.0,false)
end

Parameters for each channel in the EEG record.

mutable struct Annotation
    onset::Float64
    duration::String
    annotation::Array{String,1}
    Annotation() = new(0.0,"",[])
    Annotation(o,d,arr) = new(o, d, typeof(arr) == String ? [arr] : arr)
end

These are text strings within the file denoting a time, optionally duration, and a list of notes about the signal at that particular time in the recording. The first onset time of the annotation channel gives a fractional second offset adjustment of the start time of that record, which is specified in whole seconds in the header.

mutable struct BEDFPlus                   # signal file data for EDF, BDF, EDF+, and BDF+ files
    ios::IOStream                         # file handle for the file containing the data
    path::String                          # file pathname
    writemode::Bool                       # true if is intended for writing to file
    version::String                       # version of the file format
    edf::Bool                             # EDF?
    edfplus::Bool                         # EDF+?
    bdf::Bool                             # BDF?
    bdfplus::Bool                         # BDF+?
    discontinuous::Bool                   # discontinuous (EDF+D?)
    filetype::FileStatus                  # @enum FileStatus as above
    channelcount::Int                     # total number of EDF signal bands in the file INCLUDING annotation channels
    file_duration::Float64                # duration of the file in seconds expressed as 64-bit floating point
    startdate_day::Int                    # startdate of study, day of month of startdate of study
    startdate_month::Int                  # startdate month
    startdate_year::Int                   # startdate year
    starttime_subsecond::Float64          # starttime offset in seconds, should be < 1 sec in size. Only used by EDFplus and BDFplus
    starttime_second::Int                 # this is in integer seconds, the field above makes it more precise
    starttime_minute::Int                 # startdate and time, minutes
    starttime_hour::Int                   # 0 to 23, midnight is 00:00:00
    # next 11 fields are for EDF+ and BDF+ files only
    patient::String                       # contains patientfield of header, is always empty when filetype is EDFPLUS or BDFPLUS
    recording::String                     # contains recordingfield of header, is always empty when filetype is EDFPLUS or BDFPLUS
    patientcode::String                   # empty when filetype is EDF or BDF
    gender::String                        # empty when filetype is EDF or BDF
    birthdate::String                     # empty when filetype is EDF or BDF
    patientname::String                   # empty when filetype is EDF or BDF
    patient_additional::String            # empty when filetype is EDF or BDF
    admincode::String                     # empty when filetype is EDF or BDF
    technician::String                    # empty when filetype is EDF or BDF
    equipment::String                     # empty when filetype is EDF or BDF
    recording_additional::String          # empty when filetype is EDF or BDF
    datarecord_duration::Float64          # duration of one datarecord in units of seconds
    datarecords::Int64                    # number of datarecords in the file
    startdatestring::String               # date recording started in dd-uuu-yyyy format
    reserved::String                      # reserved, 32 byte string
    headersize::Int                       # size of header in bytes
    recordsize::Int                       # size of one data record in bytes, these follow header
    annotationchannel::Int                # position in record of annotation channel
    mapped_signals::Array{Int,1}          # positions in record of channels carrying data
    signalparam::Array{ChannelParam,1}    # Array of structs which contain the per-signal parameters
    annotations::Array{Array{Annotation,1},1} # Array of lists of annotations
    EDFsignals::Array{Int16,2}    # 2D array, each row a record, columns are channels including annotations
    BDFsignals::Array{Int32,2}    # Note that either EDFsignals or BDFsignals is used
    BEDFPlus() = new(IOStream("nothing"),"",false,"",false,false,false,false,false,READ_ERROR,0,0.0,0,0,0,0.0,0,0,0,
                        "","","","","","","","","","","",0.0,0,"","",0,0,0,
                        Array{Int,1}(undef,0),Array{ChannelParam,1}(undef,0),
                        Array{Array{Annotation,1},1}(undef,0),Array{Int16,2}(undef,0,0),Array{Int32,2}(undef,0,0))
end

Data struct for EDF, EDF+, BDF, and BDF+ EEG type signal files.

DataFormat

enum for types this package handles. Current format for a potential translation is also /same/.

FileStatus

enum for type or state of file: type of data detected, whether any errors

Functions:

loadfile(path::String, read_annotations=true)

Load a BDF+ or EDF+ type file. Takes a pathname. Will ignore annotations if second argument is set false. Returns a BEDFPlus structure including header and data.

writefile!(edfh, newpath; acquire=dummyacquire, sigformat=same)

Write to data in the edfh struct to the file indicated by newpath Returns the file handle of the file written, opened for reading NOTE: The header needs to be completely specified at function start except for the final number of records, which will be updated after all data records are written. For a system that is recording the data as it is written, the acquire(edfh) function should write the data according the the header parameters. Note that if the function converts from BDF to EDF or EDF to BDF, the edfh struct is changed.

epoch_iterator(edfh, epochsecs; channels, startsec, endsec, physical)

Make an iterator for EEG epochs of a given duration between start and stop times. Required arguments:

edfh: BEDFPlus struct
epochsecs: second duration of each epoch

Optional arguments:

channels: List of channel numbers for data, defaults to all signal channels
startsec: Starting position from 0 at start of file, defaults to file start
endsec: Ending position in seconds from start of file, defaults to file end
physical: Whether to return data as translated to the physical units, defaults to true

annotation_epoch_iterator(edfh, epochsecs; startsec, endsec)

Return an iterator for a group of annotations for a given epoch as in epoch_iterator

dummyacquire(edfh)

Dummy function for call in writefile! for optional acquire function If using package for data acquisition will need to custom write the acquire function for your calls to writefile!

channeltimesegment(edfh, channel, startsec, endsec, physical)

Get the channel's data between the time points

multichanneltimesegment(edfh, chanlist, startsec, endsec, physical)

Get an multichannel array of lists of datapoints over time segment Works best if all datapoint signal rates are the same

signalindices(edfh, channelnumber)

Get a pair of indices of a channel's bytes within each of the data records

digitalchanneldata(edfh, channelnumber)

Get a single digital channel of data in its entirety. Arguments:

edfh: the BEDFPlus struct
channelnumber: the channel number in the records

physicalchanneldata(edfh, channelnumber)

Get a single data channel in its entirely, in the physical units stated in the header Arguments:

edfh: the BEDFPlus struct
channelnumber: the channel number in the records– a channel in the mapped_signals list

samplerate(edfh, channel)

Get sample (sampling) rate (fs) on the channel in sec^-1 units

notchfilter(signals, fs, notchfreq=60, q = 35)

Notch filter signals in array signals, return filtered signals

highpassfilter(signals, fs, cutoff=1.0, order=4)

Apply high pass filter to signals, return filtered data

lowpassfilter(signals, fs, cutoff=25.0, order=4)

Apply low pass filter to signals, return filtered data

closefile!(edfh)

Close the file opened by loadfile and loaded to the BEDFPlus struct May therefore let GC release memory from read data in edfh

readdata!(edfh)

Helper function for loadfile, reads signal data into the BEDFPlus struct

signaldata(edfh)

Return which BEDFPlus variable holds the signal data

recordslice(edfh, startpos, endpos)

Get a slice of the data in the recording from one data entry position to another

bytesperdatapoint(edfh)

Return how many bytes used per data point entry: 2 for EDF (16-bit), 3 for BDF (24-bit) data.

datapointinterval(edfh, channel)

Time interval in fractions of a second between individual signal data points

recordindexat(edfh, secondsafterstart)

Index of the record point at or closest just before a given time from recording start Translates a values in seconds to a position in the signal data matrix, returns that record's position

signalat(edfh, secondsafter, channel)

Get the position in the signal data of the data point at or closest after a given time from recording start. Translates a value in seconds to a position in the signal channel matrix, returns that signal data point's 2D position as list

epochmarkers(edfh, secs)

Get a set of (start, stop) positional markers for epochs (sequential windows) given an epoch duration in seconds

checkfile!(edfh)

Check an input file to be valid EDF/BDF/+ format.

readannotations!(edfh)

Read the annotations of an input file into the EDFPlus struct.

translate24to16bits!(edfh)

Translate data in 24-bit BDF to 16-bit EDF format

translate16to24bits!(edfh)

Translate 16 bit data to 32-bit width, for change to 24-bit data for writefile!

addannotation!(edfh, onset, duration, description)

Add an annotation at the given onset timepoint IF there is room Note the description arg is expected to be a String or similar

latintoascii(str)

Change non-ascii characters to similar ascii chars

readBiosemiStatus(edfh)

Export BDF Status channel data.

Returns a Dict structure containing trigger data in the format:

Code: => vector of triggerbit (Int),
Index: => vector of index data (Int)
Onset: => vector of onset times (Float)
Duration: => vector of durations (Float)

Installation:

To install from a Julia REPL command line session:

using Pkg
Pkg.add("EDFPlus"))

Note that the test files include a 23 mb test file. You may need to allow extra time for that to download when installing.