# `ref_t_bm_stem20` — Complete Source Code (No Checkpoints)

This folder contains all **Python source files** implementing the `ref_t_bm_stem20` submission (Codabench ID 1047211, H=0.625).

---

## 📁 **Files (19 total)**

### Core Pipeline
| File | Role |
|------|------|
| `sub_fuse_multi.py` | **Main entry**: calibrate fusion+HMM on corpus → predict test sets |
| `sub_evidence.py` | Generate Layer 1 evidence (4 seeds × dec/clf/bmms) → `.pkl` |
| `stem_ensemble.py` | Reference LODO + real-set eval of all combos (classic LODO calibration) |
| `sub_convert.py` | Preprocess test CND → `eaP_n5_t60` cache (index.csv + .npz/trial) |
| `eval_stem_external.py` | `stem_ms96` impl: LogitTransformer, 24 ms features, causal Transformer |

### Shared / Utilities
| File | Exports |
|------|---------|
| `tb_members.py` | `t_score()` (rate-aux Transformer), `bm_mean()` (BMMS3), `x16()` |
| `sub_fuse.py` | `bvec()`, `write_predictions()` (128 Hz CSV), `load_evidence()` |
| `nested_stack_fusion.py` | `corpus_table()`, `join()` (evidence alignment) |
| `r1_acc_decision_grid.py` | `components()` (LDA weights for DEC/CLF streams) |
| `score.py` | `load_folds()`, `score_dataset()`, official scorer, `SCHED` |
| `e1_switch.py` | `integ_hmm()` (HMM forward), `synth_trial()` (synthetic switches) |
| `common_exp.py` | `EXP`, `DS_KEYS`, data loading utilities |
| `common.py` | `DS_KEYS`, `B64U`, `MONTAGES` (channel montages) |
| `prepare_data.py` | `CFG`, `causal_ea()`, `ea_prior()`, `zscore_trial()` |
| `build_glimpse.py` | `features()` (dom/orel/odiff from 128 Hz envelopes) |

### Model Definitions & Training
| File | Contains |
|------|----------|
| `decoders.py` | All architectures: `vlaai_ws`, DirectNet, BMMS3Enhanced, etc. |
| `direct_classifier.py` | DirectNet training (sw2, 10s, 3-block, pretrain, aug) |
| `run_experiment.py` | Decoder training (LODO, contrastive loss, SparrKULee pretrain) |

---

## 🔗 **Call Graph**

```
sub_fuse_multi.py (MAIN)
├── calibrate()
│   ├── stem_ensemble.COMBOS['ref_t_bm_stem20']
│   ├── score.load_folds()
│   ├── r1_acc_decision_grid.components()
│   ├── tb_members.t_score()
│   ├── tb_members.bm_mean()
│   ├── eval_stem_external.stem_streams()
│   └── e1_switch.integ_hmm()
│
├── predict()
│   ├── sub_fuse.load_evidence()
│   ├── tb_members.t_score()
│   ├── tb_members.bm_mean()
│   ├── eval_stem_external.stem_streams()
│   ├── e1_switch.integ_hmm()
│   └── sub_fuse.write_predictions()
│
sub_evidence.py
├── run_experiment.py (DEC)
├── direct_classifier.py (CLF + BMMS)
└── → evidence .pkl/trial/seed
│
sub_convert.py
├── prepare_data.build (eaP_n5_t60)
├── build_glimpse.features
└── → cache/index.csv + .npz/trial
```

---

## ⚠️ **Not Included (Required at Runtime)**

| Component | Location |
|-----------|----------|
| **DEC checkpoints** (4 seeds) | `models/all5_vlaai_ws_bestP_s{0..3}.pt` |
| **CLF checkpoints** (4 seeds) | `models/all5_direct_clf_w10b3sw2P_s{0..3}.pt` |
| **BMMS checkpoints** (4 seeds) | `models/all5_direct_clf_w10bmms3enhP_s{0..3}.pt` |
| **TR checkpoints** (4 seeds) | `results/research/nested_schedule_rate_aux/model_fusion_ALL_s{0..3}.pt` |
| **STEM checkpoints** (5 folds) | `../../eeg-thao_unzipped/eeg-thao/models/stem_ms96_image_split/stem_ms96__held-{AVGC,DTU,KUL,UHD,USTC}.pt` |
| **Calibration JSON** | `results/submission/calibration_ref_t_bm_stem20.json` (generated by `calibrate`) |
| **Evidence cache** | `results/submission/TEST_{NJU,DLAAD}/{dec,clf,bmms}_s{0..3}.pkl` (generated by `sub_evidence.py`) |

---

## 🚀 **Quick Start**

```bash
cd /root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/experiments/latest

# 1. Preprocess test sets (requires test CND data)
python sub_convert.py --data_dir ../../test_phase/nju/dataCND --name TEST_NJU
python sub_convert.py --data_dir ../../test_phase/dlaad/dataCND --name TEST_DLAAD

# 2. Generate Layer 1 evidence
GLIMPSE_THR=norm python sub_evidence.py TEST_NJU
GLIMPSE_THR=norm python sub_evidence.py TEST_DLAAD

# 3. Calibrate fusion + HMM (corpus only)
GLIMPSE_THR=norm python sub_fuse_multi.py calibrate --combo ref_t_bm_stem20

# 4. Predict test sets
GLIMPSE_THR=norm python sub_fuse_multi.py predict --combo ref_t_bm_stem20 --set TEST_NJU --out ../../test_phase/rebuild/nju
GLIMPSE_THR=norm python sub_fuse_multi.py predict --combo ref_t_bm_stem20 --set TEST_DLAAD --out ../../test_phase/rebuild/dlaad
```

---

## 📊 **Metric**

New κ-based scorer (since 07/11/2026):
```
κ = max(0, 2 × Acc - 1)
H = 2 × κ × L / (κ + L)
```

---

## 📝 **Reference**

- `new_README.md` (parent `experiments/` dir) — full submission documentation
- `CONTEXT_3_RULES.md` — challenge rules & metric definition