hubii-world/ecg-to-hrv-pipeline
📚 What is ECG2HRV?
A pipeline to derive heart rate variability (HRV) features from electrocardiogram (ECG) data.
Note: You already derived R-Peaks from the ECG signal? Use RPeaks2HRV to calculate HRV features!
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.txt2 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', 'nonlin'] | The domains the pipeline should calculate features for. | | `samplingrate` | 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()