PlayHack ML — AthleteGuard

A competition-focused, fully local machine-learning prototype for the PlayHack ML track. The supplied case asks the model to use a 30-day observation window to predict injury in the following 30-day risk window, including injury occurrence, onset day, and recovery duration.

What this build contains

• Supervised training using the supplied train_labels.csv (3,000 labeled athletes).
• Observation-window-only feature engineering across daily activity, hourly steps, calories, intensity, heart rate, sleep, weight, training sessions, and athlete metadata.
• Temporal features for recent-vs-early workload, trends, short rolling load peaks, training spikes, sleep debt, intensity exposure, and cross-domain stress.
• Candidate-model benchmarking with free/open-source scikit-learn models.
• F1-tuned injury classification threshold.
• Separate onset-day and recovery-duration regressors.
• Competition-format submission validation.
• Persisted trained models (*.joblib) and global classifier feature importance.
• Streamlit dashboard with Dashboard, Athlete Explorer, Analytics, Model Performance, and Methodology views.
• No paid APIs or cloud services are required.

Project structure

PlayHack_ML_Final/
├── app.py
├── run.py
├── requirements.txt
├── MODEL_CARD.md
├── README.md
├── docs/
│   ├── ARCHITECTURE.md
│   └── SUBMISSION_CHECKLIST.md
├── src/
│   ├── data.py
│   ├── features.py
│   ├── models.py
│   ├── evaluation.py
│   ├── explainability.py
│   └── pipeline.py
├── data/
│   ├── train/                 # 9 labeled-observation CSVs
│   ├── test/                  # 9 test-observation CSVs
│   └── train_labels.csv
├── reference/
│   ├── Playhack.pdf
│   ├── example_submission.csv
│   └── SOURCE_NOTES.md
├── outputs/
│   ├── submission.csv
│   ├── athlete_predictions.csv
│   ├── test_features.csv
│   ├── risk_report.csv
│   ├── model_benchmark.csv
│   ├── feature_importance.csv
│   ├── metrics.json
│   ├── model_info.json
│   ├── classifier.joblib
│   ├── onset_model.joblib
│   └── recovery_model.joblib
└── tests/

Run on macOS / VS Code

Open this folder in VS Code and create/activate the virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Train, evaluate and generate the final submission:

python3 run.py

Launch the dashboard:

streamlit run app.py

Open the local URL printed by Streamlit, typically http://localhost:8501.

Run tests:

python3 -m pytest -q

Competition outputs

outputs/submission.csv contains the required fields:

• athlete_id
• injured_in_risk_window
• onset_day_offset
• recovery_duration

The pipeline validates that injury predictions are 0/1, injured athletes have onset days in 1–30 and positive recovery duration, and non-injured athletes have zeroed timing fields.

Current local validation result

After the latest feature/model pass and a fixed stratified 80/20 holdout on the supplied 3,000 labeled athletes:

Metric	Value
Injury F1	0.6967
Precision	0.9431
Recall	0.5524
PR-AUC	0.7718
ROC-AUC	0.7635
Onset MAE	2.65 days
Recovery MAE	2.85 days
Selected classifier	ExtraTrees (tuned)
Selected threshold	0.435
Onset model	HistGradientBoosting
Recovery model	ExtraTrees

These are local holdout measurements only; they are not leaderboard scores.

Dashboard

The Streamlit interface is designed for a competition demo rather than raw dataframe inspection:

• Dashboard: cohort KPIs, risk mix, prediction mix, high-risk table, score distribution, and submission download.
• Athlete Explorer: search/select an athlete, risk score, expected timing, profile, and descriptive monitoring signals.
• Analytics: risk by sport and global feature importance.
• Model Performance: F1, precision, recall, ROC-AUC, PR-AUC, model benchmark and confusion matrix, plus timing MAE/skill.
• Methodology: observation-to-prediction flow, leakage controls, data domains, and evaluation explanation.

APIs

None are required. The prototype runs completely locally using free/open-source Python libraries. No paid plan, cloud API, or external inference service is needed.

Responsible-use note

This is a competition prototype for predictive risk estimation and model evaluation. Its scores are model outputs, not medical diagnoses or causal explanations.