mhrv.wfdb

download_wfdb()

mhrv.wfdb.download_wfdb(dest_base_dir)

Downloads the WFDB binaries for this OS. This function detects the current OS and attempts to download the approprate WFDB binaries. By default they will be downloaded into the folder ‘bin/wfdb’ under the current MATLAB directory.

Parameters

dest_base_dir – Optional. Directory to download into. Will be created if it doesn’t exist. A folder name ‘wfdb’ will be created inside. If this is not provided, defaults to the folder ‘bin/’ under the current MATLAB directory.

Returns

  • bin_path: Path the the directory containing the WFDB binaries that were downloaded.

download_wfdb_records()

mhrv.wfdb.download_wfdb_records(db_name, rec_names, outdir, varargin)

Downloads records from the PhysioBank database on PhysioNet.

Parameters
  • db_name – Name of database on physiobank, e.g. mitdb.

  • rec_names – A string or cell of strings containing a regex pattern to match against the record names from the specified database. Matching will be performed against the entire record name (as if regex is delimited by ^$). Empty array or string will match all records. See examples below.

  • outdir – The root directory to download to. A folder with the specified db_name will be created within it.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • base_url: Specify an alternative physiobank URL to download from.

Returns

  • dl_recs: Names of downloaded records.

  • dl_ann: Names of annotators for downloaded records.

  • dl_files: Paths to all downloaded files.

Examples:

  1. Download single record, mitdb/100 to folder db/mitdb:

    download_wfdb_records('mitdb', '100', 'db');
    
  2. Download three specific records from mitdb:

    download_wfdb_records('mitdb', {'100','200','222'}, 'db');
    
  3. Download all records starting with ‘1’ (e.g. 100, 101, 122…) from mitdb:

    download_wfdb_records('mitdb', '1\d+', 'db');
    
  4. Download records ‘123’, ‘124’ and any record ending with 0 from mitdb:

    download_wfdb_records('mitdb', {'12[3,4]', '\d+0'}, 'db');
    
  5. Download all records from mitdb:

    download_wfdb_records('mitdb', [], 'db');
    

ecgrr()

mhrv.wfdb.ecgrr(rec_name, varargin)

Calculate an RR-interval time series from PhysioNet ECG data. Detects QRS in a given sigal and calculates the RR intervals.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100 if the record files (both 100.dat and 100.hea) are in a folder named ‘db/mitdb’ relative to MATLABs pwd.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • ann_ext: Specify an annotation file extention to use instead of loading the record itself (.dat file). If provided, RR intervals will be loaded from the annotation file instead of from the ECG. Default: empty (don’t use annotation).

    • ecg_channel: Number of ecg signal in the record (default [], i.e. auto-detect signal).

    • from: Number of first sample to start detecting from (default 1)

    • to: Number of last sample to detect until (default [], i.e. end of signal)

    • plot: true/false whether to generate a plot. Defaults to true if no output arguments were specified.

Returns

  • rri: RR-intervals values in seconds.

  • trr: RR-interval times in seconds.

get_signal_channel()

mhrv.wfdb.get_signal_channel(rec_name, varargin)

Find the channel of a signal in the record matching a description. By default, if no description is specified it looks for ECG signal channels.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100 if the record files (both 100.dat and 100.hea) are in a folder named ‘db/mitdb’ relative to MATLABs pwd.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • sig_regex: A regular expression that should match the desired signal’s description in the header file.

    • comment_regex: A regular expression that matches the comment format in the header file.

Returns

  • chan: Number of the first channel in the signal that matches the description regex, or an empty array if no signals match.

  • Fs: Sampling frequency

  • N: Number of samples

get_wfdb_tool_path()

mhrv.wfdb.get_wfdb_tool_path(tool_name, base_search_path)

Returns the path to a wfdb tool, takes OS into account Looks for the given tool recursively under the current MATLAB directory (or a given directory), and then recursively under the folders in the $PATH environment variable. In case the tool is found, the containing directory path will be persisted to speed up the next search.

Parameters
  • tool_name – A string containg the name of the wfdb tool, e.g. ‘gqrs’, ‘wfdb-config’, ‘rdsamp’ etc. Should not include a file extension.

  • base_search_path – Optional. An absolute path to use as a base for searching for the tool. If not provided defaults to pwd().

Returns

  • tool_path - The path of the wfdb tool, including it’s os-specific file extension (e.g. .exe). In case the tool wasn’t found, an error will be raised.

gqrs()

mhrv.wfdb.gqrs(rec_name, varargin)

Wrapper for WFDB’s ‘gqrs’ and ‘gqpost’ tools. Finds the onset of QRS complexes in ECG signals given in PhysioNet format and returns them as a MATLAB vector.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100 if the record files (both 100.dat and 100.hea) are in a folder named ‘db/mitdb’ relative to MATLABs pwd.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • ecg_channel: Number of ecg signal in the record (default [], i.e. auto-detect signal).

    • gqconf: Filename or Path to a gqrs config file to use. This allows adapting the algorithm for different signal and/or animal types (default is ‘’, i.e. no config file). Note that if only a filename is provided, ‘gqrs’ will attempt to find the gqconf file on the MATLAB path.

    • gqpost: Whether to run the ‘gqpost’ tool to find erroneous detections (default false).

    • from: Number of first sample to start detecting from (default 1)

    • to: Number of last sample to detect until (default [], i.e. end of signal)

Returns

  • qrs: Vector of sample numbers where the an onset of a QRS complex was found.

  • outliers: Vector of sample numbers which were marked by gqpost as suspected false detections.

Note

If no output variables are given to the function call, the detected ECG signal and QRS complexes will be plotted in a new figure.

isrecord()

mhrv.wfdb.isrecord(rec_name, data_ext)

Checks if the given WFDB record name exists locally.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. ‘db/mitdb/100’. Can be an absolute or relative path (relative to the MATLAB pwd).

  • data_ext – Optional. The extension of the data file to look for. Defaults to ‘dat’ if not specfied.

Returns

  • isrecord: True if the given record path is valid, otherwise false. Valid means that e.g. both the files db/mitdb/100.dat (or another extension as specified in ‘data_ext’) and db/mitdb/100.hea exist if rec_name was ‘db/mitdb/100’).

qrs_compare()

mhrv.wfdb.qrs_compare(rec_name, varargin)

Compare R-peak detection algorithm to annotations. qrs_compare can run a r-peak detector on a given physionet record and compare the detections to an annotation file. The function assumes that the annotation file has the same record name, with a user-configurable file extension. The function supports both wfdb format and matlab’s ‘mat’ format for the annotation files. The comparison of the detected QRS locations to the reference annotations is performed by calculating a joint-accuracy measure (F1), based on the Sensitivity (SE) and Positive-predictivity (PPV) of the test detector’s annotations 1.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100 if the record files (both 100.dat and 100.hea) are in a folder named ‘db/mitdb’ relative to MATLABs pwd.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • tolerance: Threshold tolerance time, in seconds, for two peak detections to be considered equal.

    • ann_ext: Extension of annotation file.

    • ann_format: Format of annotation file. Can be wfdb or mat.

    • ecg_channel: Channel number of ecg signal in the record (default [], i.e. auto-detect signal).

    • qrs_detector: Name of qrs detector to use. Can be rqrs or gqrs.

    • plot: true/false whether to generate a plot. Defaults to true if no output arguments were specified.

Returns

  • sqi: Signal quality indices for the comparison between the detector and annotations.

1

Johnson, A. E. W., Behar, J., et al. (2015). Multimodal heart beat detection using signal quality indices. Physiological Measurement, 36, 1–15.

qrs_compare_set()

mhrv.wfdb.qrs_compare_set(set_dir, ann_ext, varargin)

Compares reference QRS detections to test detections on a set of wfdb records.

Parameters
  • set_dir – directory path containing the wfdb files and annotations

  • ann_ext – file extension of the annotation files.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • any parameter supported by qrs_compare() can be passed to this function.

    • plot: true/false whether to generate a plot. Defaults to true if no output arguments were specified.

Returns

  • sqis: A table containing quality indices for each of the input files.

  • stats: A table containing the Mean and Gross values for the quality indices over all files.

rdann()

mhrv.wfdb.rdann(rec_name, ann_ext, varargin)

Wrapper for WFDB’s ‘rdann’ tool. Reads annotation files in PhysioNet format and returns them as a MATLAB vector.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100 if the record files (both 100.dat and 100.hea) are in a folder named ‘db/mitdb’ relative to MATLABs pwd.

  • ann_ext – Extension of annotation file. E.g. use ‘qrs’ is the annotation file is mitdb/100.qrs.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • ’ann_types’: A double-quoted string of PhysioNet annotation types that should be read, e.g. ‘“N|”’ to read both annotations of type ‘N’ and type ‘|’. Default is empty, i.e. return annotations of any type.

    • from: Number of first sample to start detecting from (default 1)

    • to: Number of last sample to detect until (default [], i.e. end of signal)

    • plot: Whether to plot the all the channels and annotations in the file. Useful for debugging.

Returns

  • ann: A Nx1 vector with the sample numbers that have annotations.

  • ann_types: A Nx1 cell array with annotation types (strings, see PhysioNet documentation).

rdsamp()

mhrv.wfdb.rdsamp(rec_name, varargin)

Wrapper for WFDB’s ‘rdsamp’ tool. Reads channels in PhysioNet data files and returns them in a MATLAB matrix.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100 if the record files (both 100.dat and 100.hea) are in a folder named ‘db/mitdb’ relative to MATLABs pwd.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • chan_list: A list of channel numbers (starting from 1) to read from the record, e.g. to read the first three channels use [1, 2, 3]. Default is [], i.e. read all channels from the record.

    • from: Number of first sample to start detecting from (default 1)

    • to: Number of last sample to detect until (default [], i.e. end of signal)

Returns

  • t: A vector with the sample times in seconds.

  • sig: A matrix where is column is a different channel from the signal.

  • Fs: The sampling frequency of the data.

rqrs()

mhrv.wfdb.rqrs(rec_name, varargin)

R-peak detection in ECG signals, based on gqrs and gqpost. rqrs Finds R-peaks in PhysioNet-format ECG records. It uses the gqrs and gqpost programs from the PhysioNet WFDB toolbox, to find the QRS complexes. Then, it searches forward in a small window to find the R-peak.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100 if the record files (both 100.dat and 100.hea) are in a folder named ‘db/mitdb’ relative to MATLABs pwd.

  • varargin

    Pass in name-value pairs to configure advanced options:

    • ecg_channel: Number of ecg signal in the record (default [], i.e. auto-detect signal).

    • gqconf: Path to a gqrs config file to use. This allows adapting the algorithm for different signal and/or animal types (default is ‘’, i.e. no config file).

    • gqpost: Whether to run the ‘gqpost’ tool to find and remove possibly erroneous detections.

    • from: Number of first sample to start detecting from (default 1)

    • to: Number of last sample to detect until (default [], i.e. end of signal)

    • window_size_sec: Size of the forward-search window, in seconds.

    • plot: true/false whether to generate a plot. Defaults to true if no output arguments were specified.

Returns

  • qrs: Vector of sample numbers where the an onset of a QRS complex was found.

  • tm: Time vector (x-axis) of the input signal.

  • sig: The input signal values.

  • Fs: The input signals sampling frequency.

wfdb_header()

mhrv.wfdb.wfdb_header(rec_name)

Returns metadata about a WFDB record based on it’s header file.

Parameters

rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100 if the record files (both 100.dat and 100.hea) are in a folder named ‘db/mitdb’ relative to MATLABs pwd.

Returns

A struct with the following fields:

  • rec_name: The record name

  • Fs: Sampling frequency

  • N_samples: Number of samples

  • N_channels: Number of channels (different signals) in the record

  • channel_info: A cell array of length N_channels with the metadata about each channel

  • duration: A struct with the fields h,m,s,ms corresponding to duration fields - hours, miutes, seconds, milliseconds.

  • total_seconds: Records total duration in seconds.

Note

If no output arguments are given, prints record and channel info to console.

wrann()

mhrv.wfdb.wrann(rec_name, ann_ext, ann_idx, varargin)

Wrapper for WFDB’s ‘wrann’ tool. Write annotation files in PhysioNet format given a MATLAB vector.

Parameters
  • rec_name – Path and name of a wfdb record’s files e.g. db/mitdb/100. If a header file for the record doesn’t exist one will be created (but fs must be specified in varargin).

  • ann_ext – Extension of annotation file to write. E.g. use ‘qrs’ to write the annotation file mitdb/100.qrs.

  • ann_idx – A column vector of integer type containing sample indices of the annotations.

  • varargin

    Pass in name-value pairs to configure %advanced options:

    • fs: The sampling frequency of the signal which is being annotated. Pass this in if writing annotations for a record which doesn’t exist (i.e. a header file should be created).

    • comments: A cell array of strings which will bea written to the header file as comments (one per line). Will only be written when a new header file is craeted by this function.

    • type: Either a single character that will be used as the type for all annotations, or a cell array the same size ‘ann_idx’ containg a different annotation type per sample.

    • sub: Either a single number (-128 ~ 128) that will be used as the subtype attribute for all annotations, or a column vector the same size as ‘ann_idx’ containg a different subtype per sample.

    • chan: Either a single number (-128 ~ 128) that will be used as the chan attribute for all annotations, or a column vector the same size as ‘ann_idx’ containg a different chan per sample.

    • num: Either a single number (-128 ~ 128) that will be used as the num attribute for all annotations, or a column vector the same size as ‘ann_idx’ containg a different num per sample.

    • aux: Either a single string that will be used as the aux attribute for all annotations, or a string cell array the same size as ‘ann_idx’ containg a different aux per sample.

Returns

A cell array with the paths of files that were created.