scripts/README.md

CLARA Scripts

CLI scripts converted from notebooks/CLARA_HFM.ipynb for training and evaluating HFM.

Available Scripts

1) scripts/train_hfm.py

Train CLARA on HFM and save best checkpoint.

python3 scripts/train_hfm.py \
  --data-root data/HFM \
  --text-dir data/HFM/text \
  --output-dir outputs/hfm \
  --checkpoint-name clara_hfm.pt \
  --batch-size 32 \
  --max-epochs 50

2) scripts/evaluate_hfm.py

Evaluate one checkpoint on HFM test set with all variants from notebook:

• Raw
• Bias+Temp
• Top-2 Flip
• Affine Neutral

python3 scripts/evaluate_hfm.py \
  --checkpoint outputs/hfm/clara_hfm.pt \
  --data-root data/HFM \
  --text-dir data/HFM/text \
  --output-dir results/hfm

3) scripts/run_hfm_all.py

Run train then evaluate in one command.

python3 scripts/run_hfm_all.py \
  --data-root data/HFM \
  --text-dir data/HFM/text \
  --train-output-dir outputs/hfm \
  --results-dir results/hfm

HFM Data Preparation

If your HFM comes as 3 zip files in data/, extract with:

cd data
unzip -n HFM-20260303T020235Z-1-001.zip
unzip -n HFM-20260303T020235Z-1-002.zip
unzip -n HFM-20260303T020235Z-1-003.zip

Expected structure:

data/HFM/
├── image/
├── train/image/
├── val/image/ (or valid/image/)
├── test/image/
└── text/
    ├── train.txt
    ├── val.txt (or valid.txt)
    └── test.txt