run_scripts/README.md

# Reproducing FLARE paper experiments

Each top-level folder under `run_scripts/` is one paper setting. **Params YAML
files live alongside the scripts** in that folder.

## Naming convention

| Prefix | Role |
|--------|------|
| `0_*` | Training or preprocessing |
| `1_*` | Test / retrieval evaluation (+ `eval.py` metrics when a result pickle exists) |

Some settings split evaluation by candidate list (`cand_by_mass` vs
`cand_by_form`). Those use separate `1_run_test_*.sh` scripts that share the
same trained checkpoint but point at different params / candidate JSON files.

**Default eval path:** released checkpoint in `pretrained_models/` (override
with `FLARE_CHECKPOINT`).

**Full reproduction:** run `0_run_train.sh` in that folder, then the
appropriate `1_run_test_*.sh`.

---

## Directory layout

```
run_scripts/
├── msgym_main/                          # FLARE (main paper model)
│   ├── params.yaml                      # candidates by mass
│   ├── params_cand_by_form.yaml         # candidates by formula
│   ├── 0_run_train.sh                   # train FLARE
│   ├── 1_run_test_cand_by_mass.sh       # eval, mass candidates
│   └── 1_run_test_cand_by_form.sh       # eval, formula candidates
├── msgym_global/                        # global mean-pool baseline
│   ├── params_global.yaml
│   ├── 0_run_train.sh                   # train global contrastive model
│   ├── 1_run_test_cand_by_mass.sh       # eval, mass candidates
│   └── 1_run_test_cand_by_form.sh       # eval, formula candidates
└── msgym_cand_by_mass_msbuddy_pred_form/  # FLARE + msbuddy formulas (eval only)
    ├── params_predicted_formula.yaml
    ├── 0_preprocess_msgym/              # msbuddy annotation + subformulae
    │   ├── run.sh
    │   └── run_msbuddy.py
    └── 1_run_test.sh                    # eval with released FLARE checkpoint
```

---

## Experiment map

| Folder | Model | Train? | Params | Eval scripts |
|--------|-------|--------|--------|--------------|
| [`msgym_main/`](msgym_main/) | FLARE (`filipContrastive`) | `0_run_train.sh` | `params.yaml`, `params_cand_by_form.yaml` | `1_run_test_cand_by_mass.sh`, `1_run_test_cand_by_form.sh` |
| [`msgym_global/`](msgym_global/) | Global contrastive (`contrastive`) | `0_run_train.sh` | `params_global.yaml` | `1_run_test_cand_by_mass.sh`, `1_run_test_cand_by_form.sh` |
| [`msgym_cand_by_mass_msbuddy_pred_form/`](msgym_cand_by_mass_msbuddy_pred_form/) | FLARE + msbuddy formulas | preprocess only (`0_preprocess_msgym/run.sh`) | `params_predicted_formula.yaml` | `1_run_test.sh` |

---

## Quick start

### Main FLARE results (MassSpecGym)

Uses MIST-style subformulae under `data/subformulae_default/`.

```bash
# Optional: train from scratch
bash run_scripts/msgym_main/0_run_train.sh

# Eval with released checkpoint (default)
bash run_scripts/msgym_main/1_run_test_cand_by_mass.sh
bash run_scripts/msgym_main/1_run_test_cand_by_form.sh
```

### Global pooling baseline

```bash
bash run_scripts/msgym_global/0_run_train.sh          # optional
bash run_scripts/msgym_global/1_run_test_cand_by_mass.sh
bash run_scripts/msgym_global/1_run_test_cand_by_form.sh
```

Prefer `pretrained_models/flare_global.ckpt` when available; scripts fall back
to `flare.ckpt` with a warning.

### msbuddy predicted formulas (eval-only)

No training script — reuses the main FLARE checkpoint. Preprocess writes
gitignored artifacts under this folder's `0_preprocess_msgym/data/`.

```bash
bash run_scripts/msgym_cand_by_mass_msbuddy_pred_form/0_preprocess_msgym/run.sh
bash run_scripts/msgym_cand_by_mass_msbuddy_pred_form/1_run_test.sh
```

---

## Params files

Each experiment folder ships its own YAML. Paths inside are **relative to the
repository root** unless absolute. Override any file with `FLARE_PARAMS`:

```bash
export FLARE_PARAMS="$PWD/run_scripts/msgym_main/params.yaml"
```

| File | Used for |
|------|----------|
| `msgym_main/params.yaml` | FLARE training + mass-candidate eval |
| `msgym_main/params_cand_by_form.yaml` | Formula-candidate eval (same architecture) |
| `msgym_global/params_global.yaml` | Global contrastive train + eval |
| `msgym_cand_by_mass_msbuddy_pred_form/params_predicted_formula.yaml` | msbuddy subformulae + mass-candidate eval |

---

## Shared environment variables

| Variable | Purpose |
|----------|---------|
| `FLARE_REPO_ROOT` | Repository root (auto-detected by scripts) |
| `FLARE_PARAMS` | Override params YAML (default: co-located params in each folder) |
| `FLARE_CHECKPOINT` | Checkpoint for eval |
| `MASSSPECGYM_TSV` | MassSpecGym spectra TSV |
| `CANDIDATES_JSON` | Retrieval candidate list JSON |
| `SUBFORMULA_DIR` | Per-spectrum subformula JSON directory |
| `EXP_DIR` | Output directory under `experiments/` |
| `LIMIT` | (preprocess) limit spectra for a smoke test |
| `SKIP_ASSIGN` | (preprocess) annotate only; skip subformula assignment |

---

## Data layout (expected under repo `data/`)

Place MassSpecGym files yourself:

```
data/MassSpecGym.tsv
data/MassSpecGym_retrieval_candidates_mass.json
data/MassSpecGym_retrieval_candidates_formula.json
data/subformulae_default/   # one JSON per spectrum id (MIST-style)
```

Generate MIST-style subformulae with:

```bash
cd flare/subformula_assign
SPEC_FILES=$PWD/../../data/MassSpecGym.tsv \
OUTPUT_DIR=$PWD/../../data/subformulae_default \
bash run.sh
```

msbuddy outputs for the predicted-formula experiment land under
`run_scripts/msgym_cand_by_mass_msbuddy_pred_form/0_preprocess_msgym/data/`
(gitignored). Regenerate with `0_preprocess_msgym/run.sh` or host/download
those artifacts separately.

---

## Metrics

After `test.py`, eval scripts call `flare/eval.py <result_*.pkl> --ci --mces`
when a result pickle is present. Artifacts land in `experiments/<name>/`.