PhysioDSP: A Python Library for Wearable Physiological Signal Processing

Processing physiological signals from wearables (e.g., ECG, accelerometer) is often fragmented: algorithms are scattered across papers, repositories, and ad‑hoc scripts, each with its own interface and data model.

Unified Framework

PhysioDSP is an open‑source Python package (installable via pip install physiodsp) that provides a consistent, extensible framework for physiological sensor data processing, emphasizing algorithmic consistency, type safety, and reproducibility.

Core Architecture

Each algorithm follows a common pattern: a Settings class (built on Pydantic) defines configurable parameters, an Algorithm class inherits from BaseAlgorithm and exposes a run() method, and results are returned as a Pandas DataFrame. Sensor data are wrapped in typed models such as AccelerometerData, EcgData, and HrvData, which perform schema validation upon instantiation.

from physiodsp.ecg.peak_detector import EcgPeakDetector
from physiodsp.sensors.ecg import EcgData

ecgd = EcgData(timestamps=timestamps, values=ecg_values, fs=250)
 detector = EcgPeakDetector()
 result = detector.run(ecgd)
print(result.biomarker)  # DataFrame with RR intervals and heart rate

Implemented Algorithms

The current release includes four functional modules:

activity/ – Implements ENMO, zero‑crossing rate, threshold‑time duration, and a proportional‑integral‑mode (PIM) algorithm for multi‑axis data. It also provides a personalized activity‑scoring scheme that outputs normalized daily activity and recovery indices (0–100) with baseline personalization.

ecg/ – Provides a Pan‑Tompkins‑style filtering and peak‑detection pipeline that returns timestamps, RR intervals, and instantaneous heart rate in a single DataFrame.

hrv/ – Calculates HRV scores by mapping RMSSD through a sigmoid to a 0–100 scale, incorporating trend and stability components via a sliding‑window approach for longitudinal monitoring.

dsp/ – Supplies convolution and filtering utilities that serve as the computational foundation for the above modules and can be used independently to build custom pipelines.

Sensor Support and Data Model

The sensor layer abstracts three IMU modalities (accelerometer, gyroscope, magnetometer) together with ECG and HRV time series. Each data class accepts raw NumPy arrays, timestamps, and sampling frequency, validates inputs with Pydantic, and presents a uniform interface to downstream algorithms. This separation enables new hardware or signal types to be added without modifying existing algorithm code. The library requires Python ≥ 3.11 and depends on NumPy, Pandas, SciPy, and Pydantic.

Conclusion and Future Work

Although still early (version 0.1.0b0), PhysioDSP already offers a usable foundation for physiological signal processing, covering activity analysis, ECG peak detection, and HRV scoring with a unified, testable architecture. Planned extensions include energy‑expenditure estimation, sleep‑quality metrics, and machine‑learning‑based activity recognition.

https://github.com/matteo-serafino/physiodsp