vitalsqi-toolkit 0.1.2

A toolkit for signal quality analysis

Vital_sqi: Signal quality control of physiological signals

---

Overview

Vital_sqi is an open-source Python package for signal quality index (SQI) extraction and quality classification of ECG and PPG signals. The package enables streamlined signal quality control, essential for reliable health monitoring and clinical research.

Key Features:

1. Support for PPG and ECG signals in various formats, including wearable device data.
2. Implementation of state-of-the-art SQI extraction methods (e.g., statistical, HRV, waveform-based).
3. Rule-based quality classification using user-defined thresholds.
4. Pipelines for end-to-end processing, from data ingestion to SQI classification.
5. A GUI tool for defining rules and visualizing results interactively.

---

Prerequisites and Installation

The package supports Python 3.7 and 3.8. Install Vital_sqi using pip:

pip install vitalSQI-toolkit

Optional Dependencies:

• Dash for GUI applications.
• Plotly for visualization.
• Matplotlib for advanced plotting options.

For detailed dependencies, refer to the documentation.

---

Getting Started

The core of the package is built around three main classes:

1. SignalSQI Class

This class handles the main signal data and SQI extraction workflow. Attributes:

• signal: Waveform data (as a pandas DataFrame).
• sampling_rate: Sampling rate of the signal (user-defined or auto-inferred).
• sqis: SQI values calculated for signal segments.
• rules and ruleset: Lists of applied rules and the ruleset used for classification.

2. Rule Class

Defines individual SQI-based rules for classification. Example rule structure in JSON:

{
  "test_sqi": {
    "name": "test_sqi",
    "def": [
      {"op": ">", "value": "10", "label": "reject"},
      {"op": ">=", "value": "3", "label": "accept"},
      {"op": "<", "value": "3", "label": "reject"}
    ],
    "desc": "",
    "ref": ""
  }
}

3. Ruleset Class

Groups rules and defines the sequence for applying them to signal segments. The ruleset is defined in JSON format and can be customized to fit specific needs.ruleset object of class Ruleset contains a set of selected rules (selected from the list of rules in signal_obj.rule) and the order to apply them in quality assignment (see schema below). Notice that this is not a tree-based classification.

Pipelines

The package includes predefined pipelines for processing ECG and PPG signals.

Example: Extracting SQIs from ECG

from vital_sqi.pipeline.pipeline_highlevel import *
from vital_sqi.data.signal_sqi_class import SignalSQI
import os

file_in = os.path.abspath('tests/test_data/example.edf')
sqi_dict = os.path.abspath('tests/test_data/sqi_dict.json')
segments, signal_sqi_obj = get_ecg_sqis(file_in, sqi_dict, 'edf')

Example: Quality Classification for ECG

from vital_sqi.pipeline.pipeline_highlevel import *
import os
import tempfile

file_in = os.path.abspath('tests/test_data/example.edf')
sqi_dict = os.path.abspath('tests/test_data/sqi_dict.json')
rule_dict_filename = os.path.abspath('tests/test_data/rule_dict_test.json')
ruleset_order = {3: 'skewness_1', 2: 'entropy', 1: 'perfusion'}
output_dir = tempfile.gettempdir()

signal_obj = get_qualified_ecg(
    file_name=file_in,
    sqi_dict_filename=sqi_dict,
    file_type='edf',
    duration=30,
    rule_dict_filename=rule_dict_filename,
    ruleset_order=ruleset_order,
    output_dir=output_dir
)

---

GUI for Rules and Execution

Vital_sqi provides a GUI for creating rules, defining rulesets, and executing them interactively. The GUI helps users:

• Configure rules visually.
• Test and validate signal quality thresholds.
• Export results for further analysis.

Click here for the GUI guide.

Workflow Overview

1. Reading and Writing Signals

Supported formats:

• ECG: EDF, MIT, CSV.
• PPG: CSV.

2. Preprocessing and Segmentation

Available preprocessing steps:

• Trimming, tapering, and smoothing.
• Bandpass filtering.
• Segmentation by duration or by beat.

3. SQI Extraction

Four types of SQIs:

1. Statistical SQIs: Kurtosis, skewness, entropy, etc.
2. HRV-based SQIs: SDNN, SDSD, RMSSD, etc.
3. RR Interval-based SQIs: Ectopic, correlogram, etc.
4. Waveform-based SQIs: DTW, QRS energy, etc.

The function vital_sqi.pipeline_function.extract_sqi is used to extract a number of SQIs from segments. The requested SQIs are defined in a json file called SQI dictionary. We provide a dictionary template for all implemented SQIs, with default parameters, in vital_sqi/resource/sqi_dict.json.

4. Signal Quality Classification

• Rule-based classification using user-defined thresholds.
• Optimized rule application for performance.

Templates for rules and rulesets are available in the vital_sqi/resource directory.

The package allows making rule set from SQIs and user-defined thresholds for quality classification. A segment assigned as accept pass all rules in the set, otherwise reject. Rules in the set have ordered, which might help to improve speed.

We ran brute force threshold searching for an in-house PPG dataset (generated with Smartcare, doubly annotated by domain experts) to obtain a set of recommended thresholds, as found in resource/rule_dict.json.

---

Documentation

Find detailed tutorials, examples, and API references at: 🔗 Vital_sqi Documentation

---

Contributions

We welcome contributions from the community! Please refer to our CONTRIBUTING.md for guidelines.

---

References

• Optimal Signal Quality Index for Photoplethysmogram Signals
• [Other relevant papers and research articles]

---

License

Vital_sqi is licensed under the MIT License. See the LICENSE file for details.

---

Thank you for supporting Vital_sqi! For questions or issues, feel free to open an issue on GitHub.