API Documentation

Import EDF to Onda

OndaEDF.jl prefers "self-service" import over "automagic", and provides functionality to extract Onda.Samples and Onda.Annotations from an EDF.File. These can be written to disk (with Onda.store / Onda.write_annotations) or manipulated in memory as desired.

OndaEDF.edf_to_onda_samples — Function
edf_to_onda_samples(edf::EDF.File; custom_extractors=())

Read signals from an EDF.File into a vector of Onda.Samples.

Collections of EDF.Signals are mapped as channels to Onda.Signals via simple "extractor" callbacks of the form:

edf::EDF.File -> (samples_info::Onda.SamplesInfo,
                  edf_signals::Vector{EDF.Signal})

edf_to_onda_samples automatically uses a variety of default extractors derived from the EDF standard texts; see src/standards.jl for details. The caller can also provide additional extractors via the custom_extractors keyword argument.

EDF.Signal labels that are converted into Onda channel names undergo the following transformations:

  • the label is whitespace-stripped, parens-stripped, and lowercased
  • trailing generic EDF references (e.g. "ref", "ref2", etc.) are dropped
  • any instance of + is replaced with _plus_ and / with _over_
  • all component names are converted to their "canonical names" when possible (e.g. "m1" in an EEG-matched channel name will be converted to "a1").

See the OndaEDF README for additional details regarding EDF formatting expectations.

OndaEDF.edf_to_onda_annotations — Function
edf_to_onda_annotations(edf::EDF.File, uuid::UUID)

Extract EDF+ annotations from an EDF.File for recording with ID uuid and return them as a vector of Onda.Annotations. Each returned annotation has a value field that contains the string value of the corresponding EDF+ annotation.

If no EDF+ annotations are found in edf, then an empty Vector{Annotation} is returned.

For a more "full-service" experience, OndaEDF.jl also provides functionality to write the extracted signals/annotations to disk:

OndaEDF.store_edf_as_onda — Function
store_edf_as_onda(path, edf::EDF.File, uuid::UUID=uuid4();
                  custom_extractors=(), import_annotations::Bool=true,
                  signals_prefix="edf", annotations_prefix=signals_prefix)

Convert an EDF.File to Onda.Samples and Onda.Annotations, store the samples in $path/samples/, and write the Onda signals and annotations tables to $path/$(signals_prefix).onda.signals.arrow and $path/$(annotations_prefix).onda.annotations.arrow. The default prefix is "edf", and if a prefix is provided for signals but not annotations both will use the signals prefix. The prefixes cannot reference (sub)directories.

Returns uuid => (signals, annotations).

Samples are extracted with edf_to_onda_samples, and EDF+ annotations are extracted with edf_to_onda_annotations if import_annotations==true (the default).

Collections of EDF.Signals are mapped as channels to Onda.Signals via simple "extractor" callbacks of the form:

edf::EDF.File -> (samples_info::Onda.SamplesInfo,
                  edf_signals::Vector{EDF.Signal})

store_edf_as_onda automatically uses a variety of default extractors derived from the EDF standard texts; see src/standards.jl for details. The caller can also provide additional extractors via the custom_extractors keyword argument.

EDF.Signal labels that are converted into Onda channel names undergo the following transformations:

  • the label is whitespace-stripped, parens-stripped, and lowercased
  • trailing generic EDF references (e.g. "ref", "ref2", etc.) are dropped
  • any instance of + is replaced with _plus_ and / with _over_
  • all component names are converted to their "canonical names" when possible (e.g. for an EOG matched channel, "eogl", "loc", "lefteye", etc. are converted to "left").

See the OndaEDF README for additional details regarding EDF formatting expectations.

Export EDF from Onda

OndaEDF.onda_to_edf — Function
onda_to_edf(signals, annotations=[]; kwargs...)

Return an EDF.File containing signal data converted from the Onda signals table and (optionally) annotations from an annotations table.

Following the Onda v0.5 format, both signals and annotations can be any Tables.jl-compatible table (DataFrame, Arrow.Table, NamedTuple of vectors, vector of NamedTuples) which follow the signal and annotation schemas (respectively).

Each EDF.Signal in the returned EDF.File corresponds to a channel of an Onda.Signal.

The ordering of EDF.Signals in the output will match the order of the rows of the signals table (and within each channel grouping, the order of the signal's channels).