vitaldsp 0.2.1
A comprehensive toolkit for Digital Signal Processing in healthcare applications.
License: MIT
Requires Python: >=3.9


# vitalDSP - Comprehensive Healthcare Digital Signal Processing Toolkit

A comprehensive Python toolkit for Digital Signal Processing (DSP) in healthcare applications, featuring advanced signal processing techniques, machine learning algorithms, and a production-ready web application.

**[🚀 Launch Web Application](https://vital-dsp-1.onrender.com/)** | **[📚 Documentation](https://vital-dsp.readthedocs.io/)** | **[📖 Tutorials](https://colab.research.google.com/github/Oucru-Innovations/vital-DSP/blob/main/docs/source/notebooks/synthesize_data.ipynb)**

[![DOI](https://zenodo.org/badge/845712551.svg)](https://doi.org/10.5281/zenodo.14613751)
![GitHub stars](https://img.shields.io/github/stars/Oucru-Innovations/vital-DSP?style=social)
![Build Status](https://github.com/Oucru-Innovations/vital-DSP/actions/workflows/ci.yml/badge.svg)
[![Coverage Status](https://coveralls.io/repos/github/Oucru-Innovations/vital-DSP/badge.svg)](https://coveralls.io/github/Oucru-Innovations/vital-DSP)
![GitHub License](https://img.shields.io/github/license/Oucru-Innovations/vital-DSP)
![Python Versions](https://img.shields.io/badge/python-3.9%2B-blue)
[![Documentation Status](https://readthedocs.org/projects/vital-dsp/badge/?version=latest)](https://vital-dsp.readthedocs.io/en/latest/?badge=latest)
![PyPI Downloads](https://img.shields.io/pypi/dm/vitalDSP)
[![PyPI version](https://badge.fury.io/py/vitalDSP.svg)](https://badge.fury.io/py/vitalDSP)
[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Oucru-Innovations/vital-DSP/blob/main/docs/source/notebooks/synthesize_data.ipynb)
[![Deploy on Render](https://img.shields.io/badge/Deploy%20on-Render-46E3B7?style=flat&logo=render)](https://vital-dsp-1.onrender.com/)

## 🎯 **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](https://vital-dsp-1.onrender.com/)**

### 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):
```bash
pip install vitalDSP
```

**With TensorFlow** (for deep learning models):
```bash
pip install vitalDSP[tensorflow]
```

**With PyTorch** (alternative deep learning backend):
```bash
pip install vitalDSP[pytorch]
```

**With Explainability Tools** (SHAP, LIME for model interpretation):
```bash
pip install vitalDSP[explainability]
```

**Deep Learning Bundle** (TensorFlow + PyTorch):
```bash
pip install vitalDSP[dl-all]
```

**Complete Installation** (all optional dependencies):
```bash
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**
```bash
git clone https://github.com/Oucru-Innovations/vital-DSP.git
```

**Step 2: Navigate to the Project Directory**
```bash
cd vital-DSP
```

**Step 3: Install the Package**

Basic installation:
```bash
python setup.py install
```

Or for development installation:
```bash
pip install -e .
```

With specific optional dependencies:
```bash
# 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:
```bash
# 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**:
```bash
pip install vitalDSP
```

**With TensorFlow** (for deep learning models):
```bash
pip install vitalDSP[tensorflow]
```

Or install from source for the latest features:

```bash
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

```python
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](https://vital-dsp-1.onrender.com/)** - Perfect for exploring vitalDSP capabilities before local installation.

### Running the Web Application Locally

VitalDSP includes a production-ready web application with three deployment modes:

```bash
# 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](https://vital-DSP.readthedocs.io/en/latest/?badge=latest).

## Deployment Options

VitalDSP offers flexible deployment options for different use cases:

### 🐳 Docker Deployment (Recommended for Production)

**Quick Start with Docker Compose**:

```bash
# 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**:

```bash
# 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):

```bash
# 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](https://vital-dsp.readthedocs.io/en/latest/deployment.html) for detailed instructions on deploying to major cloud platforms.

### 🖥️ Local/Server Deployment

**Production Server Setup** (Ubuntu/Debian):

```bash
# 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](https://vital-dsp.readthedocs.io/en/latest/deployment.html)**.

## Interactive Examples

Explore vitalDSP capabilities through our interactive Jupyter notebooks on Google Colab:

### Core Functionality
- **[Synthetic Data & Peak Detection](https://colab.research.google.com/github/Oucru-Innovations/vital-DSP/blob/main/docs/source/notebooks/synthesize_data.ipynb)**: Learn peak detection algorithms with synthetic ECG and PPG signals
- **[Signal Quality Assessment](https://colab.research.google.com/github/Oucru-Innovations/vital-DSP/blob/main/docs/source/notebooks/signal_quality_index.ipynb)**: Comprehensive signal quality analysis, SNR calculation, and artifact detection

### Healthcare Applications
- **[Health Report Analysis](https://colab.research.google.com/github/Oucru-Innovations/vital-DSP/blob/main/docs/source/notebooks/health_report_analysis.ipynb)**: Generate comprehensive health reports from ECG and PPG data
- **[Respiratory Analysis](https://colab.research.google.com/github/Oucru-Innovations/vital-DSP/blob/main/docs/source/notebooks/respiratory_analysis.ipynb)**: Advanced respiratory rate calculation and sleep apnea detection

## Documentation

Comprehensive documentation is available through multiple channels:

- **[Online Documentation](https://vital-DSP.readthedocs.io/en/latest/)**: 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](CONTRIBUTING.md) 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](https://github.com/Oucru-Innovations/vital-DSP/discussions) for questions, ideas, and general discussion
- **Issue Tracker**: [Report bugs](https://github.com/Oucru-Innovations/vital-DSP/issues) 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](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:

```bibtex
@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}
}
```