📚 What is ECG2HRV?

A pipeline to derive heart rate variability (HRV) features from electrocardiogram (ECG) data.

Usage Instructions

0 (Optional but recommeded) Set up Virtual Environment

1 Install Pipeline Dependencies

In order to use the pipeline, you need to install some dependencies the pipeline relies on. Run the following command to install the dependencies defined in requirements.txt. You can get the file from this repository.

%pip install -r requirements.txt

2 Instantiate Pipeline

from transformers import pipeline

ecgk2hrv_pipeline = pipeline(model = "hubii-world/ecg-to-hrv-pipeline", trust_remote_code=True)

3 Pipeline Parameters & Supported File Formats

Overiew: Parameters

The pipeline provides a variety of different parameters that can be set to adjust the preprocessing behavior. The following sections explain the individual parameters in detail and provide illustrative examples.

Mandatory Parameters

In general, the pipeline relies on 2 mandatory parameters the user has to set for every parameter execution:

Parameter name	Type	Default value	Description
`inputs`	str or np.array or list or pd.Series	No default value	The input that should be processed by the pipeline
`feature_domains`	list[str]	['time', 'freq', 'non_lin']	The domains the pipeline should calculate features for.
`sampling_rate`	int	1000	The sampling rate of the continuous cardiac signal in which peaks occur

Optional Parameters

Besides the mandatory parameters, the pipeline offers multiple optional parameters that may be necessary to set in order to compute correct HRV features:

Parameter name	Type	Default value	Description
`baseline`	str or np.array or list or pd.Series	None	Baseline ECG signal used for normalization
`normalization_method`	str	None	Method used for signal normalization
`cleaning_method`	str	'pantompkins1985'	Method used for signal cleaning
`peak_detection_method`	str	'pantompkins1985'	Method used for R-Peak detection in ECG signal

3.1 `inputs`

The inputs parameter represents the data the pipeline should process to HRV-Features. The pipeline supports values of type str, np.array, list and pd.Series as input.

When providing the inputs as string, it has to represent a file path to a file containing the data to process. Supported file formats are .txt.

Alternatively, you can also provide the data directly to the pipeline in form of a np.array, list or pd.Series.

Example: Provide input as file path

file_path = "./Example_data/ECGExample.txt"
result = ecgk2hrv_pipeline(inputs=file_path, sampling_rate=1000)
result.head()

3.2 `feature_domains`

The feature_domains parameter controls which domain features the pipeline calculates. The domains are provided to the pipeline as an array of keys. Supported keys are:

Key	Description
'time'	pipeline calculates time-domain HRV metrics
'freq'	pipeline calculates frequency-domain HRV metrics
'non_lin'	pipeline calculates non-linear HRV indices

For additional information regarding the calculated features, consult the NeuroKit2 documentation. Per default, the pipeline will calculate features for all three domains.

Example: Feature domains

In the following code, the pipeline only calculates time- and non-lin HRV indices for the provided data.

file_path = "./Example_data/ECGExample.txt"
result = ecgk2hrv_pipeline(inputs=file_path, feature_domains=['time', 'non_lin'], sampling_rate=1000)
result.head()

3.3 `sampling_rate`

The sampling_rate (Hz) represents the rate with which the sensor sampled data from the patient. It has to be provided as integer. In the example above, you can see a configuration where the sampling_rate is set to 1000.

The default rate is 1000 Hz, meaning that the sensor sampled 1000 values per second.

3.4 `baseline`

baseline can be used to provide a second ECG signal the pipeline uses as normalization baseline. Similiar to inputs, baseline can be provided either as file path to a .txt file, or directly as np.array, list or pd.Series.

3.5 `normalization_method`

normalization_method specifies, how the baseline signal is used for normalization. Two methods are currently supported: 'difference' and 'relative'.

'difference' subtracts the HRV features of the baseline signal from the features calculated based on inputs.

'relative' devides the HRV features calculated for inputs by the features derived from baseline.

Evidently, you only need to specify a normalization_method if you provide a baseline signal.

Example: Relative normalization

In the following code, the pipeline only calculates fequency and non-lin HRV indices for the provided data and normalizes the features using a baseline signal and relative normalization.

file_path_input = "./Example_data/ECGExample.txt"
file_path_baseline = "./Example_data/ECGBaseline.txt"
result = ecgk2hrv_pipeline(inputs=file_path_input, feature_domains=['freq', 'non_lin'], sampling_rate=1000, baseline=file_path_baseline, normalization_method='relative')
result.head()

3.6 `cleaning_method`

cleaning_method specifies the method used to clean the raw ECG signal provided to the pipeline through inputs. The default cleaning method applied is 'pantompkins1985'. For further information regarding the default cleaning method and other parameter values supported, consult the NeuroKit2 documentation.

Although in general it is highly recommended to apply data cleaning, explicitly setting cleaning_method to None will lead to the pipeline not conducting any cleaning steps.

3.7 `peak_detection_method`

peak_detection_method specifies the method used to detect R-Peaks in the cleaned ECG signal. The default peak detection method applied is 'pantompkins1985'. For further information regarding the default peak detection method and other parameter values supported, consult the NeuroKit2 documentation.

Example: Data cleaning & R-Peak detection

In the following code, the pipeline applies a cleaning method used in Visibility Graph Based Detection as well as FastNVG as peak detection algorithm.

file_path = "./Example_data/ECGExample.txt"
result = ecgk2hrv_pipeline(inputs=file_path, sampling_rate=1000, cleaning_method='vg', peak_detection_method='emrich2023')
result.head()

3.8 Supported file formats

As already mentioned in Section 3.1, the pipeline can process .txt files

When using a .txt file, the pipeline only supports the column separator '\t'. Make sure your data file matches this requirement before providing it to the pipeline.

Example: Provide .txt file to pipeline

The same can be done using a .txt file.

file_path = "./Example_data/ECGExample.txt"
result = rpeak2hrv_pipeline(inputs=file_path, sampling_rate=1000)
result.head()