Skip to contents

I/O of WFDB-compatible signal & header files from EP recording systems

Source: R/wfdb-io.R
wfdb_io.Rd

This function allows for WFDB files to be read from any WFDB-compatible system, and also allows writing out WFDB-compatible files from specific EP recording systems, as indicated in the details section. Writing WFDB leads to creation of both a dat (signal) and hea (header) file. These are both required for reading in files as well.

Usage

write_wfdb(
  data,
  record,
  record_dir = ".",
  header = NULL,
  info_strings = list(),
  units = c("digital", "physical"),
  ...
)

read_wfdb(
  record,
  record_dir = ".",
  annotator = NULL,
  begin = 0,
  end = NA_integer_,
  interval = NA_integer_,
  units = c("digital", "physical"),
  channels = character(),
  ...
)

read_signal(
  record,
  record_dir = ".",
  header = NULL,
  begin = 0,
  end = NA_integer_,
  interval = NA_integer_,
  units = c("digital", "physical"),
  channels = character(),
  ...
)

read_header(record, record_dir = ".", ...)

Arguments

data

Can either be an egm object, or a data.frame (or similar) object. The function will appropriately set defaults based on the type.

  • egm = Will extract signal and header data directly from object, and thus is simplest to convert to a WFDB format

  • signal_table = This is a customized data.table class that has an invariant column containing sample information.

  • data.frame or data.table = Must have a column that represents a time point or index, and columns that represent signal values (preferably integers)

record

String that will be used to name the WFDB record. Cannot include extensions, and is not a filepath. alphanumeric characters are acceptable, as well as hyphens (-) and underscores (_)

record_dir

File path of directory that should be used read and write files. Defaults to current directory.

header

A header file is an optional named list of parameters that will be used to organize and describe the signal input from the data argument. If the type is given, specific additional elements will be searched for, such as the low or high pass filters, colors, or other signal attributes. At minimum, the following elements are required (as cannot be calculated):

  • frequency = sample frequency in Hertz as integer

  • label = vector of names for each channel as character

  • start_time = date/time object

info_strings

A list of strings that will be written as an appendix to the header file, usually containing information about the channels, (e.g. list of colors, extra labels, etc).

units

A character string representing either digital (DEFAULT) or physical units that should be used for signal values.

  • "digital" = Returns raw ADC (analog-to-digital converter) counts as stored in the .dat file. These are integer values representing the digitized signal without any scaling applied. Use this to preserve exact round-trip fidelity.

  • "physical" = Returns signal values converted to physical units (e.g., mV) using the formula: physical = (digital - baseline) / gain, where baseline and gain are specified in the header file. This is the human-readable format for analysis.

...

Additional arguments to be passed to the function

annotator

String that is the name of a WFDB-compatible annotation type, serving as the extension for the file that is written containing that annotation. Please see read_annotation() and write_annotation() for further details.

begin, end, interval

Timepoint as an integer (representing seconds), which is converted to an index position based on sampling frequency. The default is to start at the beginning of the record. If end or interval are given, the earlier of the two will be returned. The end argument gives a time index to read until. The interval argument is the length of time past the start point.

channels

Either the signal/channel in a character vector as a name or number. Allows for duplication of signal or to re-order signal if needed. If nothing is given, will default to all channels available.

Value

Depends on if it is a reading or writing function. For writing, will output an WFDB-based object reflecting the function. For reading, will output an extension of a data.table object reflecting the underlying function (e.g. signal_table() will return an object of class).

Details

The begin, end, and interval arguments are converted into sample positions using the sampling frequency declared in the WFDB header. The reader first determines the starting sample from begin, then gives precedence to interval (when supplied) before falling back to end. Any request that extends beyond the recorded range is clamped so that the caller still receives all available data without a hard failure.

Functions

  • write_wfdb(): Writes out signal and header data into a WFDB-compatible format from R. The units parameter indicates whether the input signal data is in digital (raw ADC counts) or physical units. When units="physical", the function automatically converts to digital units using the inverse formula: digital = (physical * gain) + baseline before writing to disk.

  • read_wfdb(): Reads a multicomponent WFDB-formatted set of files directly into an egm object. This serves to pull together read_signal(), read_header(), and read_annotation() for simplicity.

  • read_signal(): Specifically reads the signal data from the WFDB binary format, returning a signal_table object for evaluation in the R environment

  • read_header(): Specifically reads the header data from the WFDB header text format, returning a header_table object for evaluation in the R environment

Recording systems

Type of signal data, as specified by the recording system, that are currently supported.