{"id":48577764,"url":"https://github.com/chaman2003/parkinson-detection","last_synced_at":"2026-04-08T16:03:31.150Z","repository":{"id":327413054,"uuid":"1095911975","full_name":"chaman2003/parkinson-detection","owner":"chaman2003","description":"Al-powered Parkinson's Disease Detection System leveraging smartphone sensors (voice and motion) for real-time analysis. Combines ensemble machine learning models (SVM, Random Forest, Gradient Boosting, XGBoost) with advanced feature extraction to provide accurate early detection, sub-second processing, and detailed reporting. ","archived":false,"fork":false,"pushed_at":"2025-12-03T16:55:56.000Z","size":26317,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-06T17:46:31.147Z","etag":null,"topics":["ai","flask","html-css-javascript","librosa","ml","numpy","pandas","pydup","python","scikit-learn"],"latest_commit_sha":null,"homepage":"https://parkinson-detection.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chaman2003.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-13T17:21:15.000Z","updated_at":"2025-12-03T16:55:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chaman2003/parkinson-detection","commit_stats":null,"previous_names":["chaman2003/parkinson-detection"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chaman2003/parkinson-detection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaman2003%2Fparkinson-detection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaman2003%2Fparkinson-detection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaman2003%2Fparkinson-detection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaman2003%2Fparkinson-detection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chaman2003","download_url":"https://codeload.github.com/chaman2003/parkinson-detection/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaman2003%2Fparkinson-detection/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31562697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","flask","html-css-javascript","librosa","ml","numpy","pandas","pydup","python","scikit-learn"],"created_at":"2026-04-08T16:03:27.598Z","updated_at":"2026-04-08T16:03:31.142Z","avatar_url":"https://github.com/chaman2003.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 Parkinson's Disease Detection System\n\nAdvanced AI-powered Parkinson's disease detection using voice and motion analysis.\n\n\u003cdiv align=\"center\"\u003e\n\n[![Python](https://img.shields.io/badge/Python-3.13+-blue.svg)](https://www.python.org/)\n[![Flask](https://img.shields.io/badge/Flask-2.3+-green.svg)](https://flask.palletsprojects.com/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n[Features](#features) • [Tech](#tech-stack) • [Install](#installation) • [Usage](#usage) • [API](#api) • [Deploy](#deployment)\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\nA web application that detects Parkinson's disease through AI analysis of voice and motion patterns. Uses ensemble ML models (SVM, Random Forest, XGBoost) on 130+ voice features and 12 motion features for accurate detection with real-time streaming analysis and comprehensive reporting.\n\n---\n\n## Features\n\n| Voice Analysis | Motion Analysis | Backend | Frontend |\n|---|---|---|---|\n| MFCC (Mel-Frequency Cepstral Coefficients) | Tremor detection (4-6 Hz) | Flask API with streaming | PWA (Progressive Web App) |\n| Spectral analysis (Centroid, Rolloff, Bandwidth) | Stability metrics \u0026 jerk analysis | Ensemble ML (SVM + RF + GB + XGBoost) | Real-time feature visualization |\n| Prosodic features (Pitch, Jitter, Shimmer) | Acceleration data (X, Y, Z axes) | Optimized feature extraction | Excel/CSV report export |\n| Voice quality (HNR, Harmonicity) | Frequency domain analysis | CORS enabled with ngrok | Mobile-ready responsive design |\n| Energy \u0026 temporal metrics | Pattern recognition \u0026 statistical analysis | Multiple test modes (voice, tremor, both) | Multi-sample averaging |\n\n---\n\n## Tech Stack\n\n**Frontend**: HTML5, CSS3, JavaScript, Web Audio API, Device Motion API, PWA  \n**Backend**: Flask 2.3.3, NumPy, SciPy, Pandas, scikit-learn, XGBoost  \n**ML Models**: Ensemble Voting (SVM + Random Forest + Gradient Boosting + XGBoost)  \n**Audio Processing**: soundfile, ffmpeg, scipy signal processing  \n**Infrastructure**: ngrok (elease-unmeaning-mireille.ngrok-free.dev), Vercel (optional)\n\n---\n\n## Installation\n\n### Prerequisites\n- Python 3.13.5 or higher (3.14+ not supported due to numba)\n- Modern browser (Chrome 88+, Firefox 85+, Safari 14+, Edge 88+)\n- ngrok (https://ngrok.com/download)\n- ffmpeg (https://ffmpeg.org/download.html)\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/chaman2003/parkinson-detection.git\ncd parkinson-detection\n\n# Install backend dependencies\ncd backend\npip install -r requirements.txt\n\n# First run will auto-train models (2-5 minutes)\n```\n\n---\n\n## Usage\n\n### One-Command Setup\n\n**Windows:**\n```powershell\n.\\backend.ps1\n```\nThis automatically starts both backend and ngrok tunnel.\n\n### Manual Setup\n\n**Terminal 1 - Backend (Required):**\n```bash\ncd backend\npython app.py\n# Runs on http://localhost:5000\n# Models will auto-train on first run (2-5 minutes)\n```\n\n**Terminal 2 - Frontend (Optional for local testing):**\n```bash\ncd frontend\npython server.py 8000\n# Runs on http://localhost:8000\n```\n\n**Terminal 3 - ngrok (For mobile access):**\n```bash\n./ngrok http --domain=elease-unmeaning-mireille.ngrok-free.dev 5000\n```\n\n### Access Points\n| Service | URL | Purpose |\n|---------|-----|---------|\n| Frontend (Local) | http://localhost:8000 | Desktop testing |\n| Backend API | http://localhost:5000/api | Data processing |\n| Backend Health | http://localhost:5000/api/health | Status check |\n| Mobile/Remote | https://elease-unmeaning-mireille.ngrok-free.dev | Via tunnel |\n| ngrok Dashboard | http://127.0.0.1:4040 | Request monitoring |\n\n---\n\n## Project Structure\n\n```\nparkinson-detection/\n├── backend/\n│   ├── app.py                       # Flask API (main entry point)\n│   ├── train.py                     # Model training script\n│   ├── custom_scaler.py             # Data normalization\n│   ├── feature_mapper.py            # Feature format mapping\n│   ├── requirements.txt             # Python dependencies\n│   ├── utils/\n│   │   ├── ml_models.py             # ML Pipeline \u0026 ensemble models\n│   │   ├── audio_features_optimized.py    # Voice feature extraction (130+ features)\n│   │   ├── tremor_features_optimized.py   # Motion feature extraction (12 features)\n│   │   ├── data_loader.py           # Dataset handling\n│   │   ├── data_storage.py          # Recording storage\n│   │   ├── dataset_matcher.py       # Sample matching\n│   │   └── __pycache__/\n│   ├── datasets/\n\t│   │   ├── voice_dataset/           # Voice recordings (healthy, parkinsons)\n│   │   ├── voice_labels.csv         # Voice labels \u0026 metadata\n│   │   └── tremor_simplified.csv    # Tremor features dataset\n│   ├── models/                      # Trained ML models (.pkl files)\n│   ├── recorded_data/               # User recordings \u0026 results\n│   └── uploads/                     # Temporary upload storage\n│\n├── frontend/\n│   ├── index.html                   # Main application interface\n│   ├── server.py                    # Development server\n│   ├── js/\n│   │   ├── app.js                   # Core application logic\n│   │   ├── config.js                # Backend URL configuration\n│   │   ├── excel-export.js          # Report generation\n│   │   ├── sensor-test.js           # Sensor testing utilities\n│   │   └── sw.js                    # Service worker (PWA)\n│   ├── css/\n│   │   ├── styles.css               # Main styles\n│   │   └── quality-indicators.css   # Real-time quality UI\n│   ├── assets/                      # Icons \u0026 images\n│   ├── manifest.json                # PWA manifest\n│   └── favicon.ico                  # App icon\n│\n├── backend.ps1                      # Windows startup script\n└── README.md                        # This file\n```\n\n---\n\n## Backend Architecture\n\n```\nUser Test (Voice/Motion/Both)\n    ↓\n[Audio/Motion Data Upload]\n    ↓\n[Conversion \u0026 Normalization]\n    ├─→ WebM→WAV conversion\n    └─→ Motion data validation\n    ↓\n[Feature Extraction - Parallel Processing]\n    ├─→ Voice: MFCC, Spectral, Prosodic, Quality (130 features)\n    └─→ Motion: Magnitude, Frequency Domain, Time Domain (12 features)\n    ↓\n[Silence/Idle Detection]\n    ├─→ Voice: RMS, ZCR, spectral analysis\n    └─→ Motion: Acceleration thresholds\n    ↓\n[Feature Selection \u0026 Scaling]\n    ├─→ Voice: Select 25 most important features\n    └─→ Motion: Map to training format\n    ↓\n[Ensemble ML Prediction]\n    ├─→ SVM Classifier\n    ├─→ Random Forest (100 trees)\n    ├─→ Gradient Boosting (100 estimators)\n    └─→ XGBoost (100 estimators)\n    ↓\n[Voting \u0026 Averaging]\n    ├─→ Soft voting (probability averaging)\n    └─→ Confidence score calculation\n    ↓\n[Results \u0026 Storage]\n    ├─→ JSON response with predictions\n    ├─→ Store recordings \u0026 features\n    └─→ Dataset matching for known samples\n    ↓\n[Streaming Response to Frontend]\n    └─→ Real-time progress updates\n```\n\n### Voice Features (130+)\n- **MFCC** (52 features): 13 coefficients × 4 statistics (mean, std, min, max)\n- **Spectral** (28 features): Centroid, Bandwidth, Rolloff, Contrast, Flatness\n- **Prosodic** (24 features): Pitch (mean/std/min/max/range), Jitter, Shimmer, RMS, Energy\n- **Quality** (18 features): HNR, Voice Quality Index, Harmonicity, Noisiness\n- **Temporal** (8 features): ZCR, Duration, Onset Strength\n- **Harmonic** (8 features): Harmonic/Percussive separation\n\n### Motion Features (12)\n- **Magnitude Statistics** (12): Mean, Std Dev, RMS, Energy, Peaks Rate, SSC Rate, FFT Dom Freq, FFT Power, FFT Energy, FFT Entropy, Sample Entropy, DFA\n- Calculated from X, Y, Z acceleration data\n- Tremor frequency analysis in 4-6 Hz band\n\n### ML Models\n| Model | Characteristics | Role |\n|-------|---|---|\n| **SVM** | High-dimensional classification, kernel-based | Strong baseline |\n| **Random Forest** | Ensemble of decision trees, feature importance | Robust voting member |\n| **Gradient Boosting** | Sequential tree building, error correction | Advanced patterns |\n| **XGBoost** | Optimized gradient boosting, GPU support | Superior performance |\n| **Voting Ensemble** | Soft voting on probabilities | Final prediction (89-94% accuracy) |\n\n---\n\n## Frontend Features\n\n### Testing Interface\n```\nTest Mode Selection\n├── Voice Only (10-30 seconds)\n├── Tremor/Motion Only (15 seconds)\n└── Both Combined\n\nReal-Time Monitoring\n├── Voice: Audio waveform, level, pitch, quality\n├── Motion: Acceleration data, tremor frequency, stability\n└── Quality indicators for data validation\n\nResults Display\n├── Overall confidence score (0-100%)\n├── Component scores (voice/motion patterns)\n├── Risk level assessment (Low/Moderate/High)\n├── Detailed feature breakdown\n└── Dataset matching (when available)\n\nExport Options\n├── Simple PDF report\n├── Detailed Excel with charts\n└── Session history (if enabled)\n```\n\n### Progressive Web App\n- Offline support via Service Worker\n- Responsive design (mobile-first)\n- One-click installation on home screen\n- Caching strategy for performance\n\n---\n\n## API Documentation\n\n### Base URLs\n- **Local**: `http://localhost:5000/api`\n- **Production**: `https://elease-unmeaning-mireille.ngrok-free.dev/api`\n\n### Main Endpoints\n\n#### 1. Health Check\n```http\nGET /api/health\n```\n**Response:**\n```json\n{\n  \"status\": \"healthy\",\n  \"timestamp\": \"2025-11-26T19:15:00.000Z\",\n  \"version\": \"1.0.0\"\n}\n```\n\n#### 2. Streaming Analysis (Recommended)\n```http\nPOST /api/analyze-stream\nContent-Type: multipart/form-data\nParameters:\n  - audio: \u003cWAV/WebM file\u003e\n  - motion_data: \u003cJSON string\u003e\n  - test_mode: \"voice\" | \"tremor\" | \"both\"\n```\n**Response**: Server-Sent Events (real-time progress)\n```\ndata: {\"status\": \"validating\", \"message\": \"🔍 Validating data...\", \"progress\": 10}\ndata: {\"status\": \"processing\", \"message\": \"🎤 Extracting voice features...\", \"progress\": 25}\n...\ndata: {\"status\": \"complete\", \"results\": {...}, \"progress\": 100}\n```\n\n#### 3. Model Information\n```http\nGET /api/models/info\n```\n**Response:**\n```json\n{\n  \"models\": {\n    \"voice_analysis\": {\n      \"type\": \"ensemble\",\n      \"algorithms\": [\"SVM\", \"Random Forest\", \"Gradient Boosting\", \"XGBoost\"],\n      \"features\": [\"MFCC\", \"Spectral\", \"Prosodic\", \"Voice Quality\"],\n      \"trained_on\": \"Real voice dataset\"\n    },\n    \"tremor_analysis\": {\n      \"type\": \"ensemble\",\n      \"algorithms\": [\"SVM\", \"Random Forest\", \"Gradient Boosting\", \"XGBoost\"],\n      \"features\": [\"Frequency Domain\", \"Time Domain\", \"Statistical\"],\n      \"trained_on\": \"Real tremor dataset\"\n    }\n  },\n  \"version\": \"2.0.0\"\n}\n```\n\n#### 4. Storage Statistics\n```http\nGET /api/storage/stats\n```\n\n---\n\n## How It Works\n\n### Step-by-Step Flow\n1. **User opens app** → Browser loads PWA, requests permissions\n2. **Selects test mode** → Voice, Tremor, or Both\n3. **Records data**\n   - Voice: 10-30 seconds of clear speech (\"Ahhh\" sound)\n   - Tremor: 15 seconds holding phone steady\n4. **Frontend captures** → Audio blob + motion events\n5. **Backend processing**\n   - Convert audio to WAV (if needed)\n   - Extract 130+ voice features in parallel\n   - Extract 12 motion features from acceleration\n   - Check for silence/idle (insufficient data)\n6. **ML prediction**\n   - Scale features with trained scalers\n   - Run through 4 ensemble models\n   - Soft vote on confidence\n7. **Results returned**\n   - Prediction: Affected / Not Affected\n   - Confidence: 0-100%\n   - Detailed features \u0026 insights\n8. **Display \u0026 export**\n   - Show results screen\n   - Optional Excel report generation\n\n### Quality Assurance\n- **Audio validation**: RMS level, voiced content, SNR\n- **Motion validation**: Sampling rate, magnitude thresholds, data completeness\n- **Feature validation**: NaN/Inf checks, range validation\n- **Model confidence**: Only show results above quality thresholds\n\n---\n\n## Model Training\n\n### Automatic Training\nModels auto-train on first backend startup:\n```\n[First-Time Setup]\nStep 1: Loading voice samples... (Found 83 samples)\nStep 2: Extracting audio features... (2-3 minutes)\nStep 3: Loading tremor dataset... (Found 117 samples)\nStep 4: Training ML models... (1-2 minutes)\n✅ MODEL TRAINING COMPLETE!\n```\n\n### Manual Training\n```bash\ncd backend\npython train.py\n# Generates: voice_model.pkl, tremor_model.pkl, scalers, feature_names\n```\n\n### Custom Dataset\nPlace your data in:\n- `datasets/voice_dataset/{healthy,parkinsons}/` (audio files)\n- `datasets/tremor_simplified.csv` (tremor features)\n- Run `python train.py` to retrain\n\n---\n\n## Deployment\n\n### Local (Windows)\n```powershell\n.\\backend.ps1\n```\n\n### Local (Linux/Mac)\n```bash\n# Terminal 1: Backend\ncd backend \u0026\u0026 python app.py\n\n# Terminal 2: Frontend\ncd frontend \u0026\u0026 python -m http.server 8000\n\n# Terminal 3: ngrok tunnel\n./ngrok http 5000\n```\n\n### Cloud Deployment\n\n**Vercel (Frontend):**\n1. Push code to GitHub\n2. Connect repo to Vercel\n3. Set environment variable: `VITE_API_URL=https://your-backend.com`\n\n**Heroku (Backend):**\n1. Create `Procfile`: `web: cd backend \u0026\u0026 python app.py`\n2. Add buildpack for Python\n3. Deploy with `git push heroku main`\n\n**AWS Lambda (Backend):**\n1. Package backend as ZIP\n2. Create Lambda function\n3. Set API Gateway trigger\n4. Environment: 512MB memory, 30s timeout\n\n---\n\n## System Requirements\n\n| Component | Minimum | Recommended |\n|-----------|---------|-------------|\n| **Python** | 3.13.5 | 3.13.5 (latest) |\n| **RAM** | 2GB | 4GB+ |\n| **Storage** | 500MB | 1GB |\n| **Browser** | Chrome 88+ | Latest stable |\n| **Microphone** | Required | Internal/USB |\n| **Motion Sensor** | Mobile only | Any device |\n\n### Known Issues\n- ❌ Python 3.14+: numba incompatible\n- ⚠️ Windows 7: Edge cases with audio codecs\n- ⚠️ Slow internet: Consider reducing sample rate\n\n---\n\n## Troubleshooting\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Backend not connecting | Port 5000 in use | `netstat -ano \\| findstr :5000` then kill PID |\n| \"Insufficient Activity\" error | Audio too quiet or silent | Speak clearly, increase microphone volume |\n| ngrok error | ngrok not found | Download from ngrok.com, extract to project root |\n| Microphone denied | Browser permissions | Go to Settings → Privacy → Allow microphone |\n| Models not training | Dataset missing | Check `datasets/` folder contents |\n| \"Port 5000 in use\" | Previous session running | Restart computer or kill Python processes |\n| Feature extraction slow | Large audio file | Keep recordings under 30 seconds |\n\n---\n\n## Contributing\n\n1. Fork repository: `https://github.com/chaman2003/parkinson-detection/fork`\n2. Create feature branch: `git checkout -b feature/your-feature`\n3. Make changes and test locally\n4. Commit with clear messages: `git commit -m 'Add: descriptive message'`\n5. Push: `git push origin feature/your-feature`\n6. Open Pull Request with description\n\n**Development Setup:**\n```bash\ngit clone https://github.com/YOUR_USERNAME/parkinson-detection.git\ncd parkinson-detection\n# Create venv\npython -m venv venv\nsource venv/bin/activate  # or venv\\Scripts\\activate on Windows\npip install -r backend/requirements.txt\n```\n\n---\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n✅ Free for commercial and personal use  \n✅ Modify and redistribute  \n⚠️ Include license notice in distributions\n\n---\n\n## Roadmap\n\n| Feature | Status | Timeline |\n|---------|--------|----------|\n| Voice \u0026 tremor analysis | ✅ Complete | Released |\n| ML ensemble models | ✅ Complete | Released |\n| Real-time streaming | ✅ Complete | v1.1 |\n| Excel export | ✅ Complete | v1.1 |\n| Multiple test modes | ✅ Complete | v1.1 |\n| User accounts \u0026 history | 🔜 Planned | v2.0 |\n| Deep learning (CNN/LSTM) | 🔜 Planned | v2.0 |\n| Wearable integration | 🔜 Planned | v2.5 |\n| Mobile app (React Native) | 🔜 Planned | v3.0 |\n\n---\n\n## Support \u0026 Contact\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/chaman2003/parkinson-detection/issues)\n- **Email**: chaman2003@gmail.com\n- **Repository**: [github.com/chaman2003/parkinson-detection](https://github.com/chaman2003/parkinson-detection)\n\n---\n\n## Disclaimer\n\n⚠️ **This is a research/educational tool. NOT for clinical diagnosis.**\n- Use under professional medical guidance only\n- Results should be validated by healthcare professionals\n- Not a substitute for medical diagnosis or treatment\n- Always consult qualified healthcare providers\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**🧠 Made with ❤️ for Parkinson's Research \u0026 Detection**\n\n**Star ⭐ if you find this helpful!**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaman2003%2Fparkinson-detection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchaman2003%2Fparkinson-detection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaman2003%2Fparkinson-detection/lists"}