PhysioDSP

A comprehensive Python library for processing and analyzing physiological sensor data. PhysioDSP provides algorithms for activity recognition, ECG and heart rate analysis, HRV (Heart Rate Variability) scoring, and digital signal processing from wearable sensors.

Features

• Activity Analysis: ENMO (Euclidean Norm Minus One), personalized Activity Score, activity intensity detection, Step Counting, energy expenditure estimation (coming soon)
• ECG Processing: QRS peak detection, heart rate calculation, inter-beat interval analysis
• HRV Scoring: Advanced heart rate variability scoring with trend analysis and stability metrics
• Balance Tests: Postural sway analysis with stabilometric indices and 95% confidence ellipse
• Sleep Analysis: Sleep quality and duration metrics (coming soon)
• Sensor Support: Accelerometer, gyroscope, magnetometer, and ECG data processing
• Digital Signal Processing: Convolution and filtering utilities for physiological signals
• Type-Safe Design: Built with Pydantic for robust data validation
• Configurable Algorithms: Each algorithm includes customizable settings and parameters

Installation

pip install physiodsp

Requirements

• Python >= 3.11
• NumPy >= 2.4.0
• Pandas >= 2.3.3
• SciPy >= 1.16.3
• Pydantic >= 2.12.0

Quick Start

Activity Analysis - ENMO

from physiodsp.io import read_mat
from physiodsp.activity.enmo import ENMO, ENMOSettings
from physiodsp.sensors.imu.accelerometer import AccelerometerData

# Load data from .mat file
data = read_mat("sensor_data.mat")

# Create accelerometer data
accel_data = AccelerometerData(
    timestamps=data['timestamps'],
    x=data['x'],
    y=data['y'],
    z=data['z'],
    fs=64  # 64 Hz sampling frequency
)

# Initialize and run ENMO algorithm
enmo = ENMO(settings=ENMOSettings(window_len=1, aggregation_window=60))
result = enmo.run(accel_data)

# Get results
print(result.biomarker)  # DataFrame with timestamps and ENMO values
result.aggregate(method='mean')  # Aggregate results

Activity Analysis - Step Count

from physiodsp.activity.step_count import StepCount, StepCountSettings
from physiodsp.sensors.imu.accelerometer import AccelerometerData

# Initialize and run Step Count algorithm
sc = StepCount(settings=StepCountSettings(bout_merge_gap_s=5.0))
result = sc.run(accel_data)

# Get results
print(f"Total steps: {result.total_steps}")
print(result.biomarker.head())  # DataFrame with timestamps, step_count, cadence, etc.

ECG Peak Detection

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

# Create ECG data
ecg_data = EcgData(
    timestamps=timestamps,
    values=ecg_values,
    fs=250  # 250 Hz sampling frequency
)

# Initialize and run peak detector
detector = EcgPeakDetector()
result = detector.run(ecg_data)

# Get heart rate and inter-beat intervals
print(result.biomarker)  # DataFrame with RR intervals and heart rate

Balance Test - Sway

from physiodsp.balance_tests.sway import Sway, SwaySettings
from physiodsp.sensors.imu.accelerometer import AccelerometerData

# Create accelerometer data (X = medio-lateral, Z = antero-posterior)
accel_data = AccelerometerData(
    timestamps=timestamps,
    x=x_values,  # medio-lateral axis
    y=y_values,  # vertical axis
    z=z_values,  # antero-posterior axis
    fs=50  # 50 Hz sampling frequency
)

# Initialize and run sway algorithm
sway = Sway(settings=SwaySettings(filter_order=4, filter_high_freq=2.5))
result = sway.run(accel_data, sensor_height=1.0)  # sensor height in meters

# Get stabilometric indices and ellipse metrics
print(result.biomarker)

HRV Scoring

from physiodsp.hrv.hrv_score import HrvScore, HrvScoreSettings
from physiodsp.sensors.hrv import HrvData

# Create HRV data (RMSSD values)
hrv_data = HrvData(
    timestamps=timestamps,
    values=rmssd_values
)

# Calculate HRV score
hrv = HrvScore(settings=HrvScoreSettings(window_len=30, method="sigmoid"))
result = hrv.run(hrv_data)

# Get HRV score (0-100)
print(result.biomarker_agg)  # DataFrame with HRV score

Core Modules

activity/

• ENMO ✅ (unit tested): Euclidean Norm Minus One - physical activity metric from accelerometer
• Zero Crossing ✅ (unit tested): Activity intensity detection
• Time Above Threshold ✅ (unit tested): Vigorous activity quantification
• PIM ✅ (unit tested): Proportional Integration Mode - multi-axis activity processing
• Step Count ✅ (unit tested): Robust step detection and cadence estimation from wrist-worn accelerometers
• Activity Score ✅ (unit tested): Personalized 0-100 daily activity and recovery score with baseline personalization
• Energy Expenditure (coming soon): Calorie burn estimation algorithms
• Activity Recognition (coming soon): Machine learning-based activity classification
• Sleep Metrics (coming soon): Sleep quality and duration analysis

sensors/

• IMU (Inertial Measurement Unit):
  • Accelerometer data processing
  • Gyroscope data processing
  • Magnetometer data processing
• ECG: Electrocardiogram signal handling
• HRV: Heart rate variability metrics

ecg/

• Peak Detector: QRS complex detection using filtering and peak detection

hrv/

• HRV Score: Comprehensive 0-100 HRV scoring with trend and stability analysis

balance_tests/

• Sway ✅ (unit tested): Postural sway analysis — stabilometric indices (average distance, RMS, total path, velocity) for the full, ML, and AP paths, plus 95% confidence ellipse metrics

io/

• MAT Reader ✅ (unit tested): Utility to load variables from MATLAB .mat files using read_mat()

dsp/

• Convolution: Signal processing utilities including moving averages

Algorithm Architecture

All algorithms follow a consistent architecture:

1. Settings: Pydantic-based configuration models for algorithm parameters
2. Algorithm Class: Inherits from BaseAlgorithm with a run() method
3. Data Models: Type-safe sensor data classes with validation
4. Results: Biomarkers stored in Pandas DataFrames for easy analysis

Development

Setup Development Environment

# Install development dependencies
pip install -r requirements-dev.txt

# Install test dependencies
pip install -r requirements-test.txt

Running Tests

pytest tests/

Contributing

Contributions are welcome! Please ensure:

• Code follows the existing project structure
• All new algorithms inherit from BaseAlgorithm
• Settings are defined using Pydantic models
• Tests are included for new functionality

License

[Add your license here]

References

• ENMO algorithm: based on accelerometer magnitude data
• ECG Peak Detection: Pan-Tompkins-like approach with filtering
• HRV Scoring: Z-score based with trend and stability analysis
• Step Count: Multi-stage pipeline with periodicity detection and adaptive peak thresholding