Skip to content

README.md

Latest commit

 

History

History
325 lines (249 loc) · 8.3 KB

README.md

File metadata and controls

325 lines (249 loc) · 8.3 KB
Raw

Parkinson's Disease Detection System

A complete end-to-end machine learning pipeline for detecting Parkinson's disease from voice audio recordings (.wav files).

📋 Overview

This system extracts acoustic features from voice recordings and uses machine learning classifiers to distinguish between:

  • Healthy individuals (label: 0)
  • Parkinson's Disease patients (label: 1)

🎯 Features

  • Feature Extraction: MFCC, Chroma, Spectral Centroid, Spectral Bandwidth, Spectral Rolloff, Zero Crossing Rate
  • Multiple Models: Random Forest, Logistic Regression, SVM
  • Dimensionality Reduction: PCA with configurable variance retention
  • Production Ready: Saved models, scalers, and preprocessing pipelines
  • Terminal Prediction: Easy-to-use command-line interface

📁 Project Structure

final-project/
├── feature_extraction.py    # Extract audio features and create CSV
├── train.py                 # Train models without PCA
├── pca_train.py             # Train models with PCA
├── predict.py               # Terminal-based prediction
├── utils.py                 # Helper functions
├── generate_sample_data.py  # Generate synthetic test data
├── requirements.txt         # Python dependencies
├── README.md               # This file
│
├── dataset/                # Audio data directory
│   ├── healthy/           # Healthy control .wav files
│   └── parkinson/         # Parkinson's patient .wav files
│
├── models/                 # Saved models and preprocessors
│   ├── RandomForest_no_pca.joblib
│   ├── LogisticRegression_no_pca.joblib
│   ├── SVM_no_pca.joblib
│   ├── RandomForest_pca.joblib
│   ├── LogisticRegression_pca.joblib
│   ├── SVM_pca.joblib
│   ├── scaler_no_pca.joblib
│   ├── scaler_pca.joblib
│   └── pca_model.joblib
│
├── plots/                  # Generated visualizations
│   ├── confusion_matrix_*.png
│   ├── accuracy_comparison_*.png
│   ├── feature_importance_*.png
│   └── pca_explained_variance.png
│
├── features.csv            # Extracted features
├── model_results.csv       # Model performance metrics
└── best_model.txt          # Best performing model

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Generate/Prepare Data

Option A: Generate synthetic test data

python generate_sample_data.py --output_dir ./dataset --samples 200

Option B: Use your own dataset

Place your .wav files in the following structure:

dataset/
├── healthy/
│   ├── sample1.wav
│   ├── sample2.wav
│   └── ...
└── parkinson/
    ├── sample1.wav
    ├── sample2.wav
    └── ...

3. Extract Features

python feature_extraction.py --data_dir ./dataset --output features.csv

4. Train Models (Without PCA)

python train.py --data features.csv --output_dir ./models

5. Train Models (With PCA)

python pca_train.py --data features.csv --output_dir ./models --variance 0.95

6. Make Predictions

# Use best model automatically
python predict.py --file path/to/audio.wav

# Use specific model
python predict.py --file audio.wav --model RandomForest

# Verbose output
python predict.py --file audio.wav --verbose

# Record from microphone and predict (NEW!)
python predict.py --record

# Record 5 seconds and predict
python predict.py --record --duration 5

🎤 Record Your Own Voice

Built-in Recording (Recommended)

# Install PyAudio first (see installation below)

# Record 3 seconds and predict immediately
python predict.py --record

# Record 5 seconds and predict
python predict.py --record --duration 5

External Recording

macOS (QuickTime):

  1. Open QuickTime Player
  2. File → New Audio Recording
  3. Record your voice (say "ahhh" for 3-5 seconds)
  4. Save as .wav file
  5. python predict.py --file my_recording.wav

Linux (arecord):

arecord -d 3 -r 22050 -c 1 -f S16_LE my_voice.wav
python predict.py --file my_voice.wav

Windows (Voice Recorder):

  1. Use Voice Recorder app
  2. Save as .wav
  3. python predict.py --file my_recording.wav

📝 Recording Tips for Best Results

Tip Recommendation
Environment Quiet room, minimal background noise
Distance 6-12 inches from microphone
What to say Sustain "ahhh" or "eee" for 3-5 seconds
Format .wav file (any sample rate, auto-converted)
Duration 3-5 seconds ideal

🔧 PyAudio Installation

# macOS
brew install portaudio
pip install pyaudio

# Linux
sudo apt-get install portaudio19-dev
pip install pyaudio

# Windows
pip install pyaudio
# Or download wheel from: https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyaudio

📊 Feature Extraction

The system extracts the following features using librosa:

Feature Type Description Count
MFCC Mean of each coefficient 20
MFCC Standard deviation of each coefficient 20
Chroma Mean of each chroma feature 12
Chroma Standard deviation of each chroma feature 12
Spectral Centroid Mean and Std 2
Spectral Bandwidth Mean and Std 2
Spectral Rolloff Mean and Std 2
Zero Crossing Rate Mean and Std 2
Total 72

🤖 Models

Without PCA

  • Random Forest: 100 estimators, max depth 10
  • Logistic Regression: L2 regularization, 1000 iterations
  • SVM: RBF kernel, C=1.0

With PCA

Same models trained on PCA-transformed features (95% variance retained)

📈 Output Files

model_results.csv

Contains performance metrics for all models:

  • Model name
  • PCA usage flag
  • Accuracy, Precision, Recall, F1 Score

best_model.txt

Name of the best performing model (by accuracy)

Plots

  • Confusion matrices for all 6 models
  • Accuracy comparison bar charts
  • Feature importance visualization
  • PCA explained variance (scree plot)

🎯 Prediction Output

==================================================
PARKINSON'S DISEASE DETECTION - PREDICTION
==================================================
Using Model: RandomForest_PCA
Prediction: Parkinson Detected
Confidence: 87.45%
==================================================

🔧 Configuration

Training Configuration (train.py, pca_train.py)

  • Test split: 15%
  • Random state: 42 (reproducible)
  • PCA variance: 90-95% (configurable)

Feature Extraction (feature_extraction.py)

  • Sample rate: 22050 Hz
  • MFCC coefficients: 20
  • Chroma features: 12

📝 Command Reference

Feature Extraction

python feature_extraction.py -d ./dataset -o features.csv

Training

# Without PCA
python train.py -d features.csv -o ./models

# With PCA
python pca_train.py -d features.csv -v 0.95

Prediction

# Basic
python predict.py -f audio.wav

# With specific model
python predict.py -f audio.wav -m SVM_PCA

# Verbose
python predict.py -f audio.wav -v

🔍 Exit Codes (predict.py)

Code Meaning
0 Healthy detected
1 Parkinson's detected
2 File not found
3 Invalid file format
4 Feature extraction failed
99 Unexpected error

📚 Dependencies

  • librosa >= 0.10.0
  • numpy >= 1.24.0
  • pandas >= 2.0.0
  • scikit-learn >= 1.3.0
  • matplotlib >= 3.7.0
  • seaborn >= 0.12.0
  • joblib >= 1.3.0
  • soundfile >= 0.12.0

⚠️ Important Notes

  1. Synthetic Data: The included generate_sample_data.py creates synthetic audio for testing. For production use, replace with real voice recordings from:

    • Healthy control group
    • Parkinson's disease patients

  2. Model Selection: The best model is automatically selected based on accuracy. Check best_model.txt to see which model is being used.

  3. Preprocessing Consistency: The same preprocessing pipeline (scaler + PCA) used in training is automatically applied during prediction.

  4. Reproducibility: All random operations use random_state=42 for reproducible results.

📄 License

MIT License

🤝 Contributing

This is a complete, production-ready system. Feel free to extend with:

  • Additional feature types
  • More classifiers
  • Deep learning models
  • Real-time audio processing
  • Web/GUI interface