Introduction

Welcome to the vital_sqi library! This introduction provides an overview of the library’s purpose, the physiological signals it processes, and the Signal Quality Indexes (SQIs) it computes. vital_sqi is optimized for use alongside our VitalDSP library, creating a powerful ecosystem for analyzing and processing physiological signals.

Background

Signal quality is a crucial aspect of physiological signal processing. In real-world scenarios, signals such as ECG (Electrocardiogram) and PPG (Photoplethysmogram) are often corrupted by noise, artifacts, or other distortions that affect their utility for clinical or analytical purposes. vital_sqi quantifies signal quality using robust, automated methods to ensure reliable downstream analyses.

When combined with VitalDSP, you can perform advanced signal processing, such as filtering, transformations, and feature extraction, before applying vital_sqi’s comprehensive SQI metrics for signal quality assessment.

The library offers a suite of Signal Quality Indexes (SQIs) that fall into three domains: 1. Statistical domain: Evaluates statistical properties of the signal. 2. Signal processing domain: Assesses signal characteristics based on transformations and filters. 3. Dynamic time warping domain: Measures similarity between signals based on time-alignment.

—

ECG Signals

Electrocardiogram (ECG) signals measure the electrical activity of the heart and are widely used for diagnosing cardiovascular conditions. Key features of ECG signals include: - P wave: Represents atrial depolarization. - QRS complex: Represents ventricular depolarization and is critical for heart rate analysis. - T wave: Represents ventricular repolarization.

ECG signals are prone to noise from muscle activity, electrode placement, and movement artifacts. vital_sqi, especially when used with VitalDSP, helps assess ECG signal quality for improved reliability in clinical settings.

—

PPG Signals

Photoplethysmogram (PPG) signals measure blood volume changes in the microvascular bed of tissue. They are commonly used in wearable devices to monitor heart rate, blood oxygen saturation, and other vital signs.

PPG signals are affected by: - Motion artifacts: Caused by patient movement or device placement. - Ambient light: Can distort readings in optical sensors. - Physiological noise: Such as respiration and muscle activity.

By combining VitalDSP’s preprocessing and artifact removal tools with vital_sqi’s quality assessment metrics, you can ensure high-quality signals for more accurate physiological measurements.

—

SQI Indexes

Signal Quality Indexes (SQIs) quantify the reliability of physiological signals. These metrics fall into three domains:

1. Statistical Domain: - Metrics based on statistical properties of the signal. - Examples: Kurtosis, Skewness, Perfusion Index.

2. Signal Processing Domain: - Metrics derived from signal transformations and characteristics. - Examples: Entropy, Signal-to-Noise Ratio, Zero Crossing Rate, Mean Crossing Rate.

3. Dynamic Time Warping Domain: - Metrics based on time-alignment and similarity between signals. - Example: Dynamic Time Warping (DTW).

Below is a summary of the SQIs supported by the library:

References: - [1] Optimal Signal Quality Index for Photoplethysmogram Signals, Mohamed Elgendi et al. - [2] Dynamic Time Warping for Signal Quality Assessment - [3] Statistical Metrics for ECG Signal Analysis

—

Detailed SQI Descriptions

• Perfusion Index (`perfusion`):

  • Measures the ratio of pulsatile to non-pulsatile blood flow.

  • Useful for evaluating the strength of the PPG signal.

  • See: vital_sqi.sqi.standard_sqi.perfusion_sqi()

• Kurtosis (`kurtosis`):

  • Measures the sharpness or peakedness of the signal distribution.

  • See: vital_sqi.sqi.standard_sqi.kurtosis_sqi()

• Skewness (`skewness`):

  • Evaluates the asymmetry of the signal distribution.

  • See: vital_sqi.sqi.standard_sqi.skewness_sqi()

• Entropy (`entropy`):

  • Quantifies the randomness or complexity of the signal.

  • Commonly used for assessing the regularity of physiological signals.

  • See: vital_sqi.sqi.standard_sqi.entropy_sqi()

• Signal-to-Noise Ratio (`signal_to_noise`):

  • Measures the ratio of signal power to noise power.

  • See: vital_sqi.sqi.standard_sqi.signal_to_noise_sqi()

• Zero Crossings Rate (`zero_crossings_rate`):

  • Calculates the rate at which the signal crosses zero.

  • Indicative of high-frequency components or noise.

  • See: vital_sqi.sqi.standard_sqi.zero_crossings_rate_sqi()

• Mean Crossing Rate (`mean_crossing_rate`):

  • Similar to zero crossings but uses the mean as the reference point.

  • See: vital_sqi.sqi.standard_sqi.mean_crossing_rate_sqi()

• Dynamic Time Warping (`DTW`):

  • Aligns two signals temporally and computes a similarity score.

  • Particularly useful for time-series comparisons.

  • See: vital_sqi.sqi.dtw_sqi.dtw_sqi()

• Clipping (`clipping`):

  • Fraction of samples at or near the amplitude rail (saturation detection).

  • Returns 0.0 for a clean signal; >0.05 indicates heavy saturation.

  • See: vital_sqi.sqi.standard_sqi.clipping_sqi()

• Baseline Wander (`baseline_wander`):

  • Ratio of sub-0.5 Hz STFT energy to total energy. High values indicate slow drift.

  • See: vital_sqi.sqi.standard_sqi.baseline_wander_sqi()

• Spectral SNR (`spectral_snr`):

  • 10*log10(in-band power / out-of-band power) in dB. Defaults to PPG band 0.5-4 Hz.

  • See: vital_sqi.sqi.standard_sqi.spectral_snr_sqi()

• Amplitude Consistency (`amplitude_consistency`):

  • Coefficient of variation of beat-to-beat peak amplitudes. Low CV = stable beats.

  • See: vital_sqi.sqi.rpeaks_sqi.amplitude_consistency_sqi()

• Band Energy SQIs (`lfe`, `qrse`, `hfe`, `vhfp`, `qrsa`):

  • Frequency-band energy metrics derived from the short-time Fourier transform.

  • lfe: low-frequency (0–0.5 Hz) STFT energy — indicates baseline wander.

  • qrse: QRS-band (5–25 Hz) STFT energy — captures ventricular activation.

  • hfe: high-frequency (>100 Hz) STFT energy — sensitive to electrode noise.

  • vhfp: very-high-frequency (>150 Hz) normalised power fraction.

  • qrsa: median QRS amplitude via vitalDSP WaveformMorphology.

  • See: vital_sqi.sqi.waveform_sqi

• RR Irregularity (`rr_irregularity`):

  • Mean absolute deviation of successive RR differences normalised by median RR.

  • More sensitive than SDNN for detecting ectopic beats and AF.

  • See: vital_sqi.sqi.hrv_sqi.rr_irregularity_sqi()

• Sample Entropy (`sample_entropy`):

  • Complexity/regularity of the NN interval series (Richman & Moorman, 2000).

  • Lower SampEn = more regular = better quality signal.

  • See: vital_sqi.sqi.hrv_sqi.sample_entropy_sqi()

• DFA (`dfa`):

  • Detrended Fluctuation Analysis short-range scaling exponent (alpha1).

  • Healthy sinus rhythm: alpha1 ~ 1.0-1.2; white noise: ~0.5.

  • See: vital_sqi.sqi.hrv_sqi.dfa_sqi()

• Hurst (`hurst`):

  • Hurst exponent via R/S analysis. H > 0.5 = persistent structured signal.

  • See: vital_sqi.sqi.hrv_sqi.hurst_sqi()

—

Peak Detection

vital_sqi bundles its own PeakDetector class (vital_sqi.common.rpeak_detection) so that peak-based SQIs work without any additional dependencies beyond vitalDSP.

PPG algorithms (9 methods): DEFAULT (vitalDSP WaveformMorphology), ADAPTIVE_THRESHOLD, COUNT_ORIG_METHOD, CLUSTERER_METHOD, SLOPE_SUM_METHOD, MOVING_AVERAGE_METHOD, BILLAUER_METHOD, AMPD_METHOD (Scholkmann 2012), and LOCAL_MAX_IBI.

ECG algorithms (4 methods): ECG_DEFAULT (vitalDSP WaveformMorphology), PAN_TOMPKINS (1985), HAMILTON (2002), ENGZEE (1979). All ECG algorithms use vitalDSP for Q/S/P/T morphology extraction, anchored to the R-peaks found by the selected algorithm.

Note

msq_sqi currently returns NaN and emits a RuntimeWarning for ECG signals. A meaningful ECG MSQ requires two independently calibrated R-peak detectors (e.g. Pan-Tompkins vs Hamilton) producing comparable indices. A future release will wire the ECG detector-switching API into msq_sqi to enable true ECG peak-agreement scoring.

—

Classification modes

After SQIs are computed, segments are labelled accept / reject by a rule engine. Three threshold-selection strategies are available (vital_sqi.pipeline.pipeline_functions.classify_segments(), auto_mode argument):

• Manual — use thresholds shipped in rule_dict.json verbatim. Best when applying externally calibrated bounds without adapting them to the current recording.

• Quantile (default) — replace each rule’s bounds with the empirical lower / upper quantiles (p5 / p95 by default) of the SQI values observed across all segments. Self-adapting per recording.

• Auto-tune — pick the per-rule quantile so the joint accept rate hits a user-specified target (default 85 %) under the independence approximation. Much more forgiving than plain Quantile when several rules are stacked.

A separate non-rule-based classifier — three-regime auto-detection (classify_segments_robust()) — is also available for cases where you don’t trust the rule definitions at all.

See SQI Pipeline and Calibration for the full math and a worked example.

Using vital_sqi with VitalDSP

While vital_sqi can be used as a standalone library, it works best when combined with VitalDSP. Here’s why: - Advanced Preprocessing: Use VitalDSP to filter, detrend, and denoise ECG and PPG signals before computing SQIs. - Feature Extraction: Combine VitalDSP’s feature engineering tools with SQIs for comprehensive signal analysis. - Seamless Integration: Both libraries are designed to complement each other, enabling end-to-end signal processing workflows.

—

Conclusion

vital_sqi is designed to provide robust tools for signal quality assessment, ensuring high reliability in both ECG and PPG analyses. When paired with VitalDSP, you gain access to a complete pipeline for signal processing and quality evaluation.

Ready to get started? Explore the installation and usage guides next!