Update model card

README.md

@@ -18,128 +18,123 @@ metrics:
 
 # Parameter-Efficient Adaptation of Facial Expression Recognition Models for Driver Monitoring
 
-Trained weights for the MSc thesis of Ayush Tiwari, BTU Cottbus-Senftenberg, 2026.
+Trained weights for the MSc thesis by **Ayush Tiwari**, BTU
+Cottbus-Senftenberg, 2026.
 
-A ViT-B/16 (`vit_base_patch16_224.augreg_in21k_ft_in1k`) is first fine-tuned on a
-six-class subset of FER+ (Stage 1). Five adaptation strategies then transfer it
-to the KMU-FED in-vehicle expression corpus under ten-fold cross-validation
-(Stage 2): full fine-tuning, a linear probe, SSF, LoRA and AdaptFormer.
+[Code and training instructions](https://github.com/headless-start/parameter-efficient-dfer)
+· [Weight files](https://huggingface.co/headless-start/parameter-efficient-dfer/tree/main)
+· [Author profile](https://huggingface.co/headless-start)
 
-This repository holds every checkpoint the reported results come from: the
-Stage-1 backbone and the ten fold checkpoints of each strategy's selected
-configuration, 51 checkpoints in total, together with the per-fold metrics,
-per-frame predictions and selection records. No image data is included.
+The code repository is currently a private preview; its link becomes accessible
+to everyone when the code is published. The weights here are public.
 
-Classes, in output order: `angry, disgust, fear, happy, sad, surprise`.
+A public ImageNet-pretrained ViT-B/16 is fine-tuned on six-class FER+ (Stage 1),
+then its encoder is adapted to KMU-FED with a fresh classifier (Stage 2).
+Five strategies are provided: full fine-tuning, linear probe, AdaptFormer,
+LoRA and SSF.
 
-## Results
-
-### Stage 1: FER+ (six classes)
-
-Learning rate selected from {1e-5, 3e-5, 1e-4} on the official validation split;
-the test split was evaluated once, for the selected checkpoint.
-
-| Learning rate | Epoch kept | Val. accuracy | Test accuracy | Test UAR | Test weighted F1 |
-|---|---|---|---|---|---|
-| 1e-5 | 28 | 94.36 | 93.21 | 81.40 | 93.13 |
-
-### Stage 2: KMU-FED, ten-fold cross-validation
-
-Mean over the ten held-out folds (110 frames each); ± is the standard deviation
-across folds, reported as spread only.
-
-| Strategy | Selected configuration | Trainable parameters | Accuracy (%) | UAR (%) | Weighted F1 (%) |
-|---|---|---|---|---|---|
-| LoRA | lr 1e-3, rank 4 | 152,070 (0.177%) | 99.00 ± 2.59 | 98.56 | 98.83 |
-| AdaptFormer | lr 1e-3, bottleneck 64 (reduction factor 12) | 1,194,246 (1.373%) | 98.45 ± 2.43 | 98.21 | 98.40 |
-| SSF | lr 3e-3 | 210,438 (0.245%) | 97.91 ± 2.88 | 97.48 | 97.75 |
-| Full fine-tuning | lr 3e-5 | 85,803,270 (100%) | 97.55 ± 4.11 | 96.87 | 97.25 |
-| Linear probe | lr 3e-3 | 4,614 (0.005%) | 93.27 ± 6.83 | 92.76 | 92.42 |
-
-### How to read these numbers
-
-- Folds are contiguous per-class blocks of frames, so the same drivers appear in
-  training and test. The results describe familiar drivers, not unseen ones.
-- Each fold keeps the epoch with the highest accuracy on its own held-out block,
-  and each strategy's configuration was chosen by mean accuracy over the same ten
-  folds. Both choices make the estimates optimistic. There is no separate
-  validation split at Stage 2.
-- One seed (42) was used throughout.
-
-## Repository layout
-
-```text
-stage1/
-  best.ckpt              full ViT-B/16 fine-tuned on FER+ (sha256 3094f103c17bd135...)
-  results.json           validation history and test metrics
-  study.json             the three learning-rate candidates and the selection rule
-stage2/<strategy>/
-  selection.json         every candidate's ten-fold mean accuracy and the selected configuration
-  search_summary.json    summary of the strategy's search
-  fold_00 ... fold_09/
-    best.ckpt            retained checkpoint for that fold
-    results.json         metrics, per-class recall, confusion matrix, training history
-    predictions.json     label, prediction and probabilities for every held-out frame
-load_weights.py          loads any checkpoint into the model of the code release
-```
+## Contents
 
-`<strategy>` is one of `full_ft`, `linear_probe`, `ssf`, `lora`, `adaptformer`.
-The Stage-1 and full fine-tuning checkpoints contain the whole network (343 MB).
-The linear probe, SSF, LoRA and AdaptFormer checkpoints contain only the
-trained parameters and the classification head (0.02 to 4.8 MB), which are
-applied on top of the Stage-1 encoder.
+There are **51 checkpoints**: one selected FER+ model and ten held-out-fold
+models for each selected KMU-FED strategy. Per-fold results, predictions and
+search-selection summaries accompany the weights. No image data is included.
 
-## Usage
+| Path | Contents |
+|---|---|
+| `stage1/best.ckpt` | Complete FER+-adapted model |
+| `stage2/<strategy>/fold_00/` … `fold_09/` | Fold weights, results and predictions |
+| `stage2/<strategy>/selection.json` | Search scores and selected configuration |
+| `load_weights.py` | Loader for the accompanying code release |
 
-The checkpoints are PyTorch files with the weights under the `model` key.
-`load_weights.py` builds the matching model with `methods.py` from the thesis
-code release, so copy it next to that code:
+Full fine-tuning stores complete networks. The other Stage-2 strategies store
+trained parameters and their classifier; the loader combines them with the
+Stage-1 encoder. There is no separately trained all-data deployment model.
 
-```python
-from load_weights import load_stage2
+## Results
 
-model = load_stage2("lora", fold=0)   # downloads stage1/best.ckpt as well
+FER+ six-class test: **93.21% accuracy**, **81.40% UAR**, **93.13% weighted F1**.
+The learning rate (1e-5) and epoch (28) were selected on the official validation
+split; the selected model was tested once.
+
+KMU-FED values below are **fold means**; accuracy ± is sample standard deviation
+across ten folds. The thesis and code README instead report **pooled weighted
+F1**, which differs from averaging fold F1 scores.
+
+| Strategy | Selected setting | Trainable parameters | Accuracy (%) | UAR (%) | Fold-mean weighted F1 (%) |
+|---|---|---:|---:|---:|---:|
+| Full fine-tuning | lr 3e-5 | 85,803,270 | 97.55 ± 4.11 | 96.87 | 97.25 |
+| Linear probe | lr 3e-3 | 4,614 | 93.27 ± 6.83 | 92.76 | 92.42 |
+| AdaptFormer | lr 1e-3, width 64 (reduction 12) | 1,194,246 | 98.45 ± 2.43 | 98.21 | 98.40 |
+| LoRA | lr 1e-3, rank 4 | 152,070 | 99.00 ± 2.59 | 98.56 | 98.83 |
+| SSF | lr 3e-3 | 210,438 | 97.91 ± 2.88 | 97.48 | 97.75 |
+
+Both the retained epoch and configuration were selected on the reported folds,
+so these are optimistic, best-observed estimates. Folds share drivers and
+sequences; they measure familiar-driver performance. Fold spread is descriptive,
+with one base seed (42) and deterministic fold-specific initialisation. The study
+does not establish equivalence, condition-specific robustness, the benefit of
+the intermediate FER+ stage, or inference speed.
+
+## Use the weights
+
+Install the accompanying code release's requirements and run from its root
+directory. The loader needs its `methods.py`, `data.py` and `experiment.py`;
+the checkpoint files alone are not a Transformers pipeline.
+
+Download the helper at the verified weight revision:
+
+```bash
+python - <<'PY'
+from huggingface_hub import hf_hub_download
+hf_hub_download(
+    "headless-start/parameter-efficient-dfer", "load_weights.py",
+    revision="92a70a21dc4810e346d7daf7b4e3c04b7dc721bb",
+    local_dir="runs/released",
+)
+PY
 ```
 
-Inputs are face crops converted to three-channel grayscale, resized to 224 x 224
-with bicubic interpolation and normalised with mean and standard deviation 0.5
-(`build_transform(False, kmufed=True)` in `data.py`). KMU-FED frames were cropped
-offline with MTCNN before training.
-
-The loader was checked against the saved predictions: for every strategy and
-every fold it reproduces the stored prediction for all 110 held-out frames.
+```python
+import sys
+import torch
+from PIL import Image
+from data import build_transform
+from experiment import CLASS_NAMES
 
-Checkpoints are pickled PyTorch files and need `torch.load(..., weights_only=False)`;
-load them only from this repository.
+sys.path.insert(0, "runs/released")
+from load_weights import load_stage2
 
-## Training summary
+model = load_stage2("lora", fold=0)
+with Image.open("face_crop.jpg") as image:
+    x = build_transform(False, kmufed=True)(image.convert("RGB"))[None]
+with torch.inference_mode():
+    predicted = model(x).argmax(1).item()
+print(CLASS_NAMES[predicted])
+```
 
-| | Stage 1 | Stage 2 |
-|---|---|---|
-| Data | FER+ six-class subset: 17,651 train / 2,004 val / 2,047 test | KMU-FED, 1,106 frames; 996 train / 110 test per fold |
-| Labels | official FER+ cross-entropy targets (train), majority vote (evaluation) | hard labels |
-| Epochs | 120 | 60 per fold |
-| Optimiser | AdamW, weight decay 0.05, 2 warmup epochs then cosine to 1e-7 | same |
-| Batch, precision | 32, mixed precision | same |
-| Augmentation | grayscale flip, rotation ±15°, translation, scale 0.90-1.10, shear, blur, erasing | same, rotation ±30° and scale 0.75-1.15 |
-| Search | learning rate | learning rate, then rank (LoRA) or bottleneck width (AdaptFormer) at the selected rate |
+The loader downloads the required weights and returns an evaluation-mode model.
+Use `load_stage1()` for FER+ or `load_stage2(method, fold)` for KMU-FED;
+methods are `full_ft`, `linear_probe`, `adaptformer`, `lora`, `ssf`, and folds
+are zero-based (`0`–`9`). Class order is `angry, disgust, fear, happy, sad,
+surprise`. Inputs must be face crops; preprocessing makes three-channel grayscale,
+resizes to 224 × 224 with bicubic interpolation and normalises with mean/std 0.5.
 
-## Data and licence
+These original-format weights are for inference through the helper, not
+`--resume` inputs for the standalone training scripts. Hosted result JSONs also
+use the original format; the code release's plotter reads its own training
+outputs. The supplied loader retains adapter modules rather than merging them.
 
-The weights are released for non-commercial research under CC BY-NC 4.0. They
-were trained on FER+ (FER2013 images with the Microsoft FER+ labels) and on
-KMU-FED, which is available from its authors on request; the terms of those
-datasets and of the pretrained ViT checkpoint continue to apply. The Stage-2
-models were trained and evaluated on a small number of drivers and are not
-suitable for any decision about a real person.
+## Licence and citation
 
-## Citation
+Weights: **CC BY-NC 4.0**. The code release is MIT-licensed. Dataset and
+pretrained-weight terms remain with their providers. These are research models
+evaluated on a small driver corpus, without validation for operational use.
 
 ```bibtex
 @mastersthesis{tiwari2026peft_dfer,
   author = {Ayush Tiwari},
-  title  = {Parameter-Efficient Adaptation of Facial Expression Recognition Models for Driver Monitoring},
+  title = {Parameter-Efficient Adaptation of Facial Expression Recognition Models for Driver Monitoring},
   school = {Brandenburgische Technische Universit{\"a}t Cottbus-Senftenberg},
-  year   = {2026}
+  year = {2026}
 }
 ```