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.

```bash
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`

```bash
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.

```bash
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:

```bash
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:

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