README.md

---
license: mit # Choose: mit, apache-2.0, cc-by-nc-4.0, etc.
language: en
library_name: pytorch-lightning
tags:
- pytorch
- pytorch-lightning
- timeseries
- forecasting
- headache-prediction
- custom-code
pipeline_tag: tabular-classification # Or potentially text-classification if input format allows
# datasets:
# - your-dataset-name # Optional: If using a dataset on the Hub
metrics:
- f1
- accuracy
- precision
- recall
- roc_auc # or auc
---

# Headache Prediction Model (Time Series Transformer)

## Model Description

This repository contains a model trained to predict the probability of experiencing a headache for the **next 5 days**. It utilizes a **Transformer Encoder** architecture implemented using PyTorch and PyTorch Lightning.

The model takes into account the previous **14 days** of historical data, including:
* Weather features (temperature, humidity, pressure, precipitation)
* Engineered features (pressure change, day of week)
* User-reported diary features (stress level, sleep hours)
* Lagged headache occurrences (status from day-1 to day-4)
* Static user features (age, gender, chronic condition)

**Developed by:** [Your Name / Organization]
**Model Version:** [e.g., v1.1 - corresponding to the uploaded checkpoint]

## Intended Uses & Limitations

* **Intended Use:** To provide a daily forecast of headache risk for the subsequent 5 days, based on a user providing the required 14-day historical sequence and static features. Can be used for personal awareness or potentially integrated into health tracking applications.
* **Limitations:**
    * Requires a **complete, chronologically ordered sequence of 14 days** of input data ending on the day *before* the first prediction day.
    * Requires the **specific input features** listed in `config/settings.py` (`MODEL_INPUT_FEATURES` and `STATIC_FEATURES_USED`).
    * Requires the **custom Python code** provided in this repository (`headache_model.py`, `base_model.py`, `config/settings.py`) to load and run the model correctly.
    * Depends heavily on the **`scalers.pkl`** file for correct input preprocessing. Using data outside the distribution seen during training may yield poor results.
    * Trained on [**Describe your training data source briefly - e.g., synthetic data, specific user group data**]. Performance may vary significantly on data from different sources or demographics.
    * The model provides probabilities; a **threshold** (default 0.5 or 0.6 used in training eval) must be applied for binary yes/no predictions, impacting the Precision/Recall trade-off.

## How to Use

**1. Installation:**

Ensure you have Python 3.9+ and install the necessary libraries. It's recommended to use the versions specified in `requirements.txt`.

```bash
# Clone the repository (includes code, config, requirements)
git lfs install # Run once per machine if not done before
git clone [https://huggingface.co/YourUsername/YourRepoName](https://huggingface.co/YourUsername/YourRepoName) # Replace with your Repo ID
cd YourRepoName

# Install dependencies
pip install -r requirements.txt