vitaldsp 0.2.2

A comprehensive toolkit for Digital Signal Processing in healthcare applications.

vitalDSP - Comprehensive Healthcare Digital Signal Processing Toolkit

A comprehensive Python toolkit for Digital Signal Processing (DSP) in healthcare applications

Advanced signal processing techniques • Machine learning algorithms • Production-ready web application

🚀 Launch Web Application | 📚 Documentation | 📖 Tutorials

---

🔥 Maintainer Note: I gave up (Claude Code takeover)

This repo has grown big enough that maintaining it manually started to feel inefficient and time-exhausting.
So yeah — I gave up doing it the old way.

From now on, I’m using Claude Code (Opus 4.6) to do an end-to-end review of the legacy codebase and drive large refactors and upgrades. Claude Code ROCKS (sorry for you — Grok, OpenAI, Gemini 😅).

What this means

• Expect major refactors and big structural changes
• There may be breaking changes (APIs, modules, file layouts, behaviors)
• I will mainly review final diffs + generated docs after Claude’s changes are implemented and merged

Stability recommendation

If you need a stable environment for production/research:

• pin a release version (don’t track main blindly)
• check Releases / Changelog before upgrading

If you hit regressions, please open an issue with:

• commit hash / version
• steps to reproduce
• minimal sample input (ECG/PPG snippet if possible)

---

🎯 Production-Ready Implementation

vitalDSP is a comprehensive, production-ready digital signal processing library with 50,000+ lines of code across 200+ files, featuring:

• ✅ Complete Signal Processing: All major physiological signal analysis capabilities
• ✅ Advanced Machine Learning: State-of-the-art ML/DL integration with 50+ features
• ✅ Production Web Application: Full-featured Dash-based web interface
• ✅ Robust Infrastructure: Enterprise-grade reliability and performance
• ✅ Comprehensive Testing: 500+ tests with extensive validation

Experience vitalDSP directly in your browser through our interactive web interface. No installation required - simply visit the application and start exploring the toolkit's capabilities.

🚀 Launch Web Application

Web Application Features

• Interactive Signal Analysis: Upload and analyze physiological signals
• Real-time Visualization: Dynamic plots with Plotly
• Multiple Analysis Pages: Time domain, frequency domain, filtering, physiological analysis
• Export Capabilities: Download results in multiple formats
• Sample Data: Built-in sample datasets for testing

Important Notes

This web application is hosted on Render's free tier with the following limitations:

• Cold start delay of a few seconds when the application spins up
• Automatic shutdown after 15 minutes of inactivity to conserve resources
• Recommended for testing and demonstration purposes only
• For production use or large datasets, please install the toolkit locally

Sample Data

The repository includes optimized sample datasets for web application testing:

• ECG Data: sample_data/ECG/ - Sample electrocardiogram signals
• PPG Data: sample_data/PPG/ - Sample photoplethysmography signals

---

🚀 Comprehensive Feature Set

Core Signal Processing

• Multi-Signal Support: ECG, PPG, EEG, respiratory signals
• Advanced Filtering: Butterworth, Chebyshev, Elliptic, Kalman filters
• Signal Transforms: FFT, Wavelet, Hilbert, STFT, DCT, MFCC
• Noise Reduction: Adaptive denoising, artifact removal
• Real-time Processing: Optimized for live signal analysis

Physiological Analysis

• Time Domain Features: HRV metrics, statistical features
• Frequency Domain: Spectral analysis, power spectral density
• Nonlinear Dynamics: Multi-scale entropy, fractal dimension
• Symbolic Dynamics: Pattern analysis, permutation entropy
• Transfer Entropy: Information flow analysis
• Cross-Signal Analysis: Multi-signal correlation and coherence

Advanced Computation

• Empirical Mode Decomposition (EMD): Adaptive signal decomposition
• Neural Network Filtering: Deep learning-based enhancement
• Anomaly Detection: Real-time anomaly identification
• Bayesian Analysis: Probabilistic signal processing
• Sparse Processing: Compressed sensing algorithms
• Reinforcement Learning: RL-based adaptive filtering

Machine Learning & AI

• Feature Extraction: 50+ features across 5 domains
• Deep Learning Models: CNN, LSTM, Transformer, Autoencoder
• Transfer Learning: Cross-domain adaptation
• Explainable AI: SHAP, LIME, GradCAM integration
• Pre-trained Models: Ready-to-use model library
• Model Training: Optimized training pipelines

Quality Assessment

• Signal Quality Index: Comprehensive quality metrics
• SNR Estimation: Adaptive signal-to-noise ratio
• Artifact Detection: Multi-modal artifact identification
• Blind Source Separation: ICA-based separation
• Quality Screening: 3-stage quality assessment pipeline

Large Data Processing

• Advanced Data Loaders: Chunked and memory-mapped loading
• Parallel Processing: Multi-process optimization
• Memory Management: Adaptive memory strategies
• Error Recovery: Comprehensive error handling
• Dynamic Configuration: Zero hardcoded values
• Performance Optimization: Up to 420x speedup

Health Analysis

• Health Report Generation: Comprehensive health reports
• Clinical Interpretation: Automated interpretation engine
• Visualization: Advanced health report visualization
• Export Formats: Multiple output formats
• Template System: Customizable report templates

Web Application

• Interactive Dashboard: Real-time signal analysis
• Multi-page Interface: Comprehensive analysis tools
• Data Visualization: Advanced plotting with Plotly
• Export Functionality: Multiple output formats
• Configuration Management: Dynamic settings
• API Integration: FastAPI backend

---

📊 Performance Benchmarks

Signal Processing Performance

• Large File Loading: Up to 420x speedup for memory-mapped files
• Quality Screening: <10ms per 10-second segment
• Parallel Processing: Up to 9x speedup with multiprocessing
• Memory Efficiency: Up to 98% reduction in memory usage
• Feature Extraction: 50+ features in <1 second

Web Application Performance

• Page Load Time: <2 seconds for analysis pages
• Real-time Updates: <100ms callback response
• Data Visualization: Smooth interactive plots
• Export Speed: <5 seconds for comprehensive reports
• Memory Usage: <200MB for typical analysis

Machine Learning Performance

• Feature Extraction: 50+ features in <1 second
• Model Training: Optimized for physiological signals
• Inference Speed: Real-time prediction capability
• Transfer Learning: Fast domain adaptation
• Explainability: <5 seconds for SHAP analysis

These files are specifically sized for the web application's free tier limitations.

Core Features

Signal Processing Modules

Filtering and Preprocessing

• Traditional filters: Moving average, Gaussian, Butterworth, and Chebyshev filters
• Advanced ML-inspired filters for noise reduction and signal enhancement
• Adaptive filtering techniques for dynamic signal conditions
• Preprocessing utilities for signal normalization and baseline correction

Transform Methods

• Fourier Transform (FFT) for frequency domain analysis
• Discrete Cosine Transform (DCT) for signal compression
• Wavelet Transform for time-frequency analysis
• Signal fusion methods for multi-sensor data integration

Time-Domain Analysis

• Advanced peak detection algorithms for ECG and PPG signals
• Envelope detection and signal demodulation
• Zero Crossing Rate (ZCR) calculation
• Advanced segmentation techniques for signal partitioning

Advanced Processing Methods

• Empirical Mode Decomposition (EMD) for non-linear signal analysis
• Sparse signal processing for compressed sensing applications
• Bayesian optimization for parameter tuning
• Machine learning-based feature extraction

Specialized Healthcare Modules

Neuro-Signal Processing (Coming Soon)

• EEG band power analysis for brain activity monitoring
• Event-Related Potential (ERP) detection
• Cognitive load measurement algorithms

Respiratory Analysis

• Automated respiratory rate calculation from various signal types
• Sleep apnea detection and classification
• Multi-sensor fusion for comprehensive respiratory monitoring
• Breathing pattern analysis and anomaly detection

Signal Quality Assessment

• Signal-to-Noise Ratio (SNR) calculation and monitoring
• Comprehensive artifact detection and removal algorithms
• Adaptive quality assessment methods
• Real-time signal quality metrics

Monitoring and Alert Systems

• Real-time anomaly detection for critical health parameters
• Multi-parameter monitoring with correlation analysis
• Intelligent alert systems with customizable thresholds
• Historical trend analysis and reporting

Installation

vitalDSP can be installed using two different methods depending on your needs:

Method 1: Install from PyPI (Recommended)

For the most stable and tested version, install directly from the Python Package Index:

Basic Installation (core functionality without deep learning):

pip install vitalDSP

With TensorFlow (for deep learning models):

pip install vitalDSP[tensorflow]

With PyTorch (alternative deep learning backend):

pip install vitalDSP[pytorch]

With Explainability Tools (SHAP, LIME for model interpretation):

pip install vitalDSP[explainability]

Deep Learning Bundle (TensorFlow + PyTorch):

pip install vitalDSP[dl-all]

Complete Installation (all optional dependencies):

pip install vitalDSP[all]

This method provides:

• Stable, tested releases
• Automatic dependency management
• Easy updates with pip install --upgrade vitalDSP

Method 2: Install from Source

For the latest development features and contributions, install directly from the GitHub repository:

Step 1: Clone the Repository

git clone https://github.com/Oucru-Innovations/vital-DSP.git

Step 2: Navigate to the Project Directory

cd vital-DSP

Step 3: Install the Package

Basic installation:

python setup.py install

Or for development installation:

pip install -e .

With specific optional dependencies:

# TensorFlow support
pip install -e .[tensorflow]

# PyTorch support
pip install -e .[pytorch]

# Explainability tools (SHAP, LIME)
pip install -e .[explainability]

# All deep learning frameworks
pip install -e .[dl-all]

# Complete installation
pip install -e .[all]

Or install dependencies separately using requirements files:

# Base installation
pip install -e .

# Add TensorFlow
pip install -r requirements-tensorflow.txt

# Add PyTorch
pip install -r requirements-pytorch.txt

# Add explainability tools
pip install -r requirements-explainability.txt

# Add all optional dependencies (for development)
pip install -r requirements-dev.txt

System Requirements

• Python 3.9 or higher
• NumPy >= 1.19.2
• SciPy >= 1.5.2
• Scikit-learn >= 0.23.2
• Plotly >= 4.14.3
• Dash >= 2.0.0 (for web applications)
• FastAPI >= 0.68.0 (for API endpoints)

Optional Dependencies

Deep Learning Frameworks

TensorFlow >= 2.8.0 (for deep learning models including autoencoders, LSTM, CNN, etc.)

• Python 3.8-3.12: tensorflow>=2.8.0,<2.17.0 (recommended)
  • On Windows/Linux: tensorflow>=2.8.0,<2.17.0
  • On macOS with Apple Silicon (M1/M2): tensorflow-macos>=2.8.0,<2.17.0
  • On macOS with Intel: tensorflow>=2.8.0,<2.17.0
• Python 3.13+: TensorFlow is not officially supported yet
  • Option 1 (Recommended): Use Python 3.11 or 3.12 for stable TensorFlow support
  • Option 2 (Experimental): Install TensorFlow nightly build: pip install tf-nightly

PyTorch >= 2.0.0 (alternative deep learning backend)

• Supports Python 3.8-3.13+
• Better compatibility with newer Python versions
• Install with: pip install vitalDSP[pytorch]
• Provides same deep learning capabilities as TensorFlow backend

Model Explainability

SHAP >= 0.41.0 (SHapley Additive exPlanations)

• For understanding model predictions
• Feature importance analysis
• Model-agnostic explanations

LIME >= 0.2.0 (Local Interpretable Model-agnostic Explanations)

• For explaining individual predictions
• Works with any machine learning model
• Easy-to-understand local explanations

Install explainability tools with: pip install vitalDSP[explainability]

Notes

• Deep learning frameworks are optional and only required if you plan to use advanced models in vitalDSP.ml_models
• Core signal processing and traditional ML features work without deep learning frameworks
• Python 3.13 Users: PyTorch is recommended over TensorFlow for better compatibility
• You can install both frameworks with: pip install vitalDSP[dl-all]

Healthcare Applications

vitalDSP is designed to address real-world healthcare challenges across multiple domains:

Clinical Monitoring

• Remote Patient Monitoring: Continuous analysis of ECG and PPG signals for real-time health insights
• Vital Signs Tracking: Automated extraction of heart rate, respiratory rate, and other critical parameters
• Chronic Disease Management: Long-term monitoring for patients with cardiovascular and respiratory conditions

Diagnostic Applications

• Stress and Anxiety Assessment: Heart rate variability analysis for psychological state evaluation
• Sleep Disorder Detection: Comprehensive sleep apnea detection using respiratory signal analysis
• Cardiovascular Screening: Early detection of arrhythmias and other cardiac abnormalities

Research and Development

• Clinical Trials: Standardized signal processing for multi-site research studies
• Biomarker Discovery: Advanced feature extraction for identifying new health indicators
• Algorithm Development: Robust platform for testing and validating new signal processing methods

Telemedicine and Digital Health

• Wearable Device Integration: Process data from smartwatches, fitness trackers, and medical devices
• Mobile Health Applications: Enable signal processing capabilities in smartphone-based health apps
• Telehealth Platforms: Provide backend processing for remote healthcare consultations

Quick Start

Installation

Install VitalDSP from PyPI (recommended for most users):

Basic Installation:

pip install vitalDSP

With TensorFlow (for deep learning models):

pip install vitalDSP[tensorflow]

Or install from source for the latest features:

git clone https://github.com/Oucru-Innovations/vital-DSP.git
cd vital-DSP
pip install -e .[tensorflow]  # Include [tensorflow] for deep learning support

Basic Usage Example

import vitalDSP as vdsp
import numpy as np
from vitalDSP.utils.peak_detection import PeakDetection
from vitalDSP.physiological_features.waveform import WaveformMorphology

# Load sample ECG data (default sampling rate: 128 Hz)
ecg_signal = np.load('sample_data/ECG_short.csv')

# Apply Butterworth filter
filtered_signal = vdsp.filtering.butterworth_filter(
    ecg_signal, 
    lowcut=0.5, 
    highcut=4, 
    fs=128, 
    order=4
)

# Create waveform morphology object for additional features
waveform = WaveformMorphology(filtered_signal, fs=128, signal_type="ECG")

Sample Data Information

The repository includes sample datasets with the following default sampling rates:

• ECG Data: 128 Hz sampling rate (sample_data/ECG_short.csv)
• PPG Data: 100 Hz sampling rate (sample_data/PPG_short.csv)

When working with these sample files, make sure to use the correct sampling rate in your analysis functions.

Interactive Web Application

Try vitalDSP without installation! Our web application serves as an interactive toolbox where you can:

• Upload your own physiological signals (ECG, PPG, respiratory)
• Apply various signal processing techniques through an intuitive interface
• Visualize results with interactive plots
• Experiment with different parameters and algorithms
• Generate health reports and analysis summaries

Launch Web Application - Perfect for exploring vitalDSP capabilities before local installation.

Running the Web Application Locally

VitalDSP includes a production-ready web application with three deployment modes:

# Option 1: Quick start (Normal mode)
python src/vitalDSP_webapp/run_webapp.py

# Option 2: Development mode (with auto-reload and debug logging)
python src/vitalDSP_webapp/run_webapp.py --debug

# Option 3: Production mode (optimized performance)
python src/vitalDSP_webapp/run_webapp.py --production

# Option 4: Interactive menu (Windows)
run_webapp.bat

# Option 5: Interactive menu (Linux/Mac)
bash run_webapp.sh

Access the application: Open your browser to http://localhost:8000

Command-line Options:

• --debug / -d: Enable debug mode with auto-reload
• --production / -p: Enable production mode (optimized)
• --port PORT: Custom port (default: 8000)
• --host HOST: Custom host (default: 0.0.0.0)
• --help / -h: Show help message

Advanced Usage

For comprehensive examples and detailed API documentation, please visit our official documentation.

Deployment Options

VitalDSP offers flexible deployment options for different use cases:

🐳 Docker Deployment (Recommended for Production)

Quick Start with Docker Compose:

# Clone repository
git clone https://github.com/Oucru-Innovations/vital-DSP.git
cd vital-DSP

# Deploy with Docker Compose (includes nginx)
docker-compose up -d

# Access at http://localhost:8000

Standard Docker:

# Build image
docker build -t vitaldsp:latest .

# Run container
docker run -p 8000:8000 -e PORT=8000 vitaldsp:latest

# Run with mounted volumes
docker run -p 8000:8000 \
  -v $(pwd)/uploads:/app/uploads \
  -v $(pwd)/logs:/app/logs \
  -e PORT=8000 \
  vitaldsp:latest

Production Docker (multi-stage build, optimized):

# Build production image
docker build -f Dockerfile.production -t vitaldsp:production .

# Run production container
docker run -p 8000:8000 vitaldsp:production

☁️ Cloud Deployment

Render.com (Currently deployed: https://vital-dsp-1.onrender.com/)

1. Fork the repository to your GitHub account
2. Sign up at https://render.com and create a new Web Service
3. Connect your GitHub repository
4. Configure:
   • Build Command: pip install -r requirements.txt && pip install -r requirements-tensorflow.txt && pip install -r src/vitalDSP_webapp/requirements.txt && pip install -e .
   • Start Command: gunicorn -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT vitalDSP_webapp.run_webapp:app
   • Environment: Python 3
5. Deploy!

AWS EC2 / Google Cloud / Azure:

See our comprehensive Deployment Guide for detailed instructions on deploying to major cloud platforms.

🖥️ Local/Server Deployment

Production Server Setup (Ubuntu/Debian):

# 1. Install dependencies
sudo apt update && sudo apt install -y python3.10 python3-pip python3-venv git gcc g++ nginx

# 2. Clone and setup
git clone https://github.com/Oucru-Innovations/vital-DSP.git
cd vital-DSP
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-tensorflow.txt
pip install -r src/vitalDSP_webapp/requirements.txt
pip install -e .

# 3. Run in production mode
python src/vitalDSP_webapp/run_webapp.py --production

# 4. (Optional) Setup as systemd service for auto-start
# See deployment guide for systemd configuration

Key Deployment Modes:

• Development: --debug (auto-reload, verbose logging)
• Testing: default mode (standard logging)
• Production: --production (optimized, minimal logging)

🔒 Security Considerations for Production

1. SSL/TLS: Use nginx or cloud provider SSL termination
2. Environment Variables: Store sensitive config in .env file
3. Firewall: Open only necessary ports (80, 443, SSH)
4. Regular Updates: Keep dependencies updated
5. Monitoring: Use health checks at /api/health

For detailed deployment instructions, troubleshooting, and best practices, see our Comprehensive Deployment Guide.

Interactive Examples

Explore vitalDSP capabilities through our interactive Jupyter notebooks on Google Colab:

Core Functionality

• Synthetic Data & Peak Detection: Learn peak detection algorithms with synthetic ECG and PPG signals
• Signal Quality Assessment: Comprehensive signal quality analysis, SNR calculation, and artifact detection

Healthcare Applications

• Health Report Analysis: Generate comprehensive health reports from ECG and PPG data
• Respiratory Analysis: Advanced respiratory rate calculation and sleep apnea detection

Documentation

Comprehensive documentation is available through multiple channels:

• Online Documentation: Complete API reference, tutorials, and examples
• Local Documentation: Build documentation locally using the files in the docs/ directory
• Jupyter Notebooks: Interactive examples in docs/source/notebooks/
• Code Examples: Sample implementations in the sample_data/analysis/ directory

Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your contributions help make vitalDSP better for everyone.

How to Contribute

1. Fork the Repository: Create your own fork of the vitalDSP repository
2. Create a Feature Branch: Work on your changes in a dedicated branch
3. Follow Guidelines: Read our CONTRIBUTING guidelines for coding standards and best practices
4. Test Your Changes: Ensure all tests pass and add new tests for new functionality
5. Submit a Pull Request: Create a detailed pull request describing your changes

Areas for Contribution

• Algorithm Improvements: Enhance existing signal processing algorithms
• New Features: Add support for new physiological signals or analysis methods
• Documentation: Improve tutorials, examples, and API documentation
• Testing: Expand test coverage and add performance benchmarks
• Web Interface: Enhance the web application with new features

Community and Support

Get Help

• GitHub Discussions: Join the conversation for questions, ideas, and general discussion
• Issue Tracker: Report bugs or request new features
• Documentation: Check our comprehensive documentation for detailed guides and examples

Stay Connected

• Star the Repository: Show your support by starring vitalDSP on GitHub
• Watch for Updates: Stay informed about new releases and features
• Share Your Work: Let us know how you're using vitalDSP in your projects

License

This project is licensed under the MIT License - see the LICENSE file for details.

The MIT License allows you to:

• Use vitalDSP commercially
• Modify and distribute the code
• Include it in proprietary software
• Use it in both open source and closed source projects

Citation

If you use vitalDSP in your research or projects, please cite our work:

@software{vitaldsp2024,
  title={vitalDSP: Healthcare Digital Signal Processing Toolkit},
  author={van-koha and Oucru-Innovations},
  year={2024},
  url={https://github.com/Oucru-Innovations/vital-DSP},
  doi={10.5281/zenodo.14613751}
}