| --- |
| title: UPDRS API |
| emoji: 🧠 |
| colorFrom: blue |
| colorTo: purple |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| --- |
| |
| # Parkinson's Disease Motor UPDRS Prediction API |
|
|
| A production-style FastAPI service that predicts **motor UPDRS score** from a voice sample and patient metadata. |
|
|
| The service: |
|
|
| - accepts audio uploads (`wav`, `mp3`, `ogg`, `webm`), |
| - converts them to WAV when needed, |
| - extracts clinical voice biomarkers using Praat, |
| - loads a trained ensemble model from Hugging Face, |
| - returns a numeric UPDRS motor prediction. |
|
|
| --- |
|
|
| ## 1) What this API does |
|
|
| Given: |
|
|
| - `age` |
| - `sex` (`male` or `female`) |
| - `test_time` |
| - `audio_file` |
|
|
| The API returns: |
|
|
| - `prediction` (float): estimated motor UPDRS score. |
|
|
| --- |
|
|
| ## 2) Project structure |
|
|
| ```text |
| UPDRS_API/ |
| ├── main.py |
| ├── requirements.txt |
| ├── Dockerfile |
| ├── README.md |
| ├── routers/ |
| │ └── analyze_router.py |
| ├── services/ |
| │ └── voice_analyze_service.py |
| ├── ml/ |
| │ └── model_predictor.py |
| ├── utils/ |
| │ ├── file_handler.py |
| │ └── voice_data_extraction.py |
| └── schema/ |
| └── patient_inputs.py |
| ``` |
|
|
| ### Responsibilities |
|
|
| - **main.py**: app startup, CORS, lifespan hook, route registration. |
| - **routers/analyze_router.py**: request validation and endpoint definitions. |
| - **services/voice_analyze_service.py**: end-to-end orchestration. |
| - **utils/file_handler.py**: upload persistence + ffmpeg conversion. |
| - **utils/voice_data_extraction.py**: Praat/parselmouth feature extraction. |
| - **ml/model_predictor.py**: model download/cache and inference. |
| |
| --- |
| |
| ## 3) API endpoints |
| |
| | Method | Path | Purpose | |
| | ------ | ---------------- | -------------------------------------------- | |
| | GET | `/` | Basic welcome/status message | |
| | GET | `/health` | Health + model cache state | |
| | POST | `/analyze/test` | Echo/debug endpoint for multipart form input | |
| | POST | `/analyze/voice` | Main prediction endpoint | |
| |
| ### `GET /health` response |
| |
| ```json |
| { |
| "status": "ok", |
| "models_loaded": true |
| } |
| ``` |
| |
| --- |
| |
| ## 4) Main prediction endpoint |
| |
| ### `POST /analyze/voice` |
| |
| Content type: `multipart/form-data` |
| |
| | Field | Type | Validation | |
| | ------------ | ------ | ------------------ | |
| | `age` | int | `10 < age < 120` | |
| | `sex` | string | `male` or `female` | |
| | `test_time` | float | `> 0` | |
| | `audio_file` | file | required | |
| |
| ### Example response |
| |
| ```json |
| { |
| "prediction": 18.42 |
| } |
| ``` |
| |
| --- |
| |
| ## 5) How prediction works (pipeline) |
| |
| 1. Request arrives at `POST /analyze/voice`. |
| 2. Audio file is written to a temp file. |
| 3. Non-WAV formats are converted to WAV via `ffmpeg`. |
| 4. Praat/parselmouth extracts acoustic and nonlinear features. |
| 5. `sex` is encoded (`male=1`, `female=0`). |
| 6. Features are combined with `age` and `test_time`. |
| 7. Features are ordered/scaled according to `feature_names.pkl` and `scaler.pkl`. |
| 8. Ensemble model predicts UPDRS. |
| 9. Temp file is always cleaned up. |
| |
| --- |
| |
| ## 6) Extracted voice features |
| |
| The service extracts these features: |
| |
| - **Jitter** |
| - `Jitter(%)` |
| - `Jitter(Abs)` |
| - `Jitter:RAP` |
| - `Jitter:PPQ5` |
| - `Jitter:DDP` |
|
|
| - **Shimmer** |
| - `Shimmer` |
| - `Shimmer(dB)` |
| - `Shimmer:APQ3` |
| - `Shimmer:APQ5` |
| - `Shimmer:APQ11` |
| - `Shimmer:DDA` |
|
|
| - **Noise/Harmonics** |
| - `NHR` |
| - `HNR` |
|
|
| - **Nonlinear dynamics** |
| - `RPDE` |
| - `DFA` |
| - `PPE` |
|
|
| --- |
|
|
| ## 7) Model details |
|
|
| - Model repo: https://huggingface.co/xplorers/parkinsons-updrs-model |
| - Artifacts downloaded on startup: |
| - `ensemble_model.pkl` |
| - `feature_names.pkl` |
| - `scaler.pkl` |
| - Models are cached in-memory (`_cache`) after first load. |
|
|
| --- |
|
|
| ## 8) Environment variables |
|
|
| Create a `.env` file in the project root (optional but recommended): |
|
|
| ```env |
| HF_TOKEN=your_huggingface_access_token |
| ``` |
|
|
| `main.py` calls `load_dotenv()`, so `.env` is loaded automatically. |
|
|
| --- |
|
|
| ## 9) Local development setup |
|
|
| ### Prerequisites |
|
|
| - Python 3.11+ (recommended for this codebase) |
| - `ffmpeg` installed and available in PATH |
|
|
| ### Install |
|
|
| ```bash |
| python -m venv venv |
| source venv/bin/activate |
| pip install -r requirements.txt |
| ``` |
|
|
| ### Run |
|
|
| ```bash |
| uvicorn main:app --reload --host 0.0.0.0 --port 8000 |
| ``` |
|
|
| Open: |
|
|
| - Swagger UI: http://127.0.0.1:8000/docs |
| - ReDoc: http://127.0.0.1:8000/redoc |
|
|
| --- |
|
|
| ## 10) Docker usage |
|
|
| Build image: |
|
|
| ```bash |
| docker build -t updrs-api . |
| ``` |
|
|
| Run container: |
|
|
| ```bash |
| docker run --rm -p 7860:7860 --env HF_TOKEN=$HF_TOKEN updrs-api |
| ``` |
|
|
| Container entrypoint uses: |
|
|
| ```bash |
| uvicorn main:app --host 0.0.0.0 --port 7860 |
| ``` |
|
|
| --- |
|
|
| ## 11) cURL examples |
|
|
| ### Health check |
|
|
| ```bash |
| curl http://127.0.0.1:8000/health |
| ``` |
|
|
| ### Voice prediction |
|
|
| ```bash |
| curl -X POST "http://127.0.0.1:8000/analyze/voice" \ |
| -F "age=63" \ |
| -F "sex=male" \ |
| -F "test_time=12.5" \ |
| -F "audio_file=@./sample.wav" |
| ``` |
|
|
| --- |
|
|
| ## 12) Error handling and troubleshooting |
|
|
| ### 401 Unauthorized from Hugging Face |
|
|
| Cause: gated/private model repository. |
|
|
| Fix: |
|
|
| 1. Ensure your account has access to the model page. |
| 2. Set `HF_TOKEN` in environment or `.env`. |
| 3. Restart the API. |
|
|
| ### `ffmpeg` conversion failure |
|
|
| Cause: `ffmpeg` missing or unsupported input file. |
|
|
| Fix: |
|
|
| - Install `ffmpeg` (system package). |
| - Test source file manually with `ffmpeg -i <file>`. |
|
|
| ### Models not loaded |
|
|
| `predict_parkinson()` raises runtime error if startup download failed. |
|
|
| Fix: |
|
|
| - Check server startup logs. |
| - Verify internet access and token permissions. |
|
|
| --- |
|
|
| ## 13) License |
|
|
| This project includes a `LICENSE` file at the repository root. Review it before distribution or production use. |
|
|
