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/	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/	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/	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/.

# 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 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 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:

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:

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>/.