# huyle — STQD v1 classifier experiment (EEG-sAAD)

**Purpose.** Replace only the *direct classifier* in `experiments/decoder_lodo` with a stimulus-conditioned temporal query decoder (STQD), without changing the existing 5-second reconstruction decoder, data splits, original evaluation scorer, or downstream evidence/HMM protocol.

**Important:** This is a **research experiment implementation**, not a confirmed improvement and not a finished blind-test submission. No LODO, AASD or Carta scores are provided with this source package; those require the user's prepared datasets, existing decoder evidence, and GPU training. The current archive was developed from the `decoder_lodo.zip` snapshot dated **2026-10-16**, not a live inspection of a server checkout. Check local upstream changes before execution.

## Layout and ownership

Install **as a sibling** of `decoder_lodo`:

```text
/root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/
├── .venv/
├── reports/eda_full/scripts/            # supplies common, scorer, e1_switch, trial_index, ...
├── baselines/python/SuperHugeAAD/       # original backbone/scoring dependencies
└── experiments/
    ├── decoder_lodo/                    # UNMODIFIED baseline; caches and decoder evidence live here
    │   ├── cache/eaP_n5_t60/
    │   ├── cache/glimpseonorm/
    │   ├── folds/<decoder experiments>/
    │   └── results/research/<decoder external evidence>.pkl
    ├── external_data/                   # original extra training and external eval datasets
    └── huyle/                           # THIS archive
        ├── stqd_model.py                # completely new model; variants / shapes
        ├── direct_classifier.py         # modified legacy trainer / pretraining / fold evaluation
        ├── eval_external_clf.py         # modified all-5 external classifier evaluation
        ├── run_all.py                   # one-shot suite, restartable phases, ONE main log
        ├── summarize_results.py         # per-variant, LODO, and external summary tables
        ├── common_exp.py                # local results; read-only upstream cache/evidence fallback
        ├── decoders.py, run_experiment.py, score.py, ...  # source-compatible copies
        ├── tests/                       # model/gradient/swap/interface tests
        ├── logs/huyle_run.log           # single consolidated stdout+stderr+epoch log
        ├── models/                      # huyle-only pretrained/all5 weights
        ├── folds/                       # huyle-only classifier folds
        └── results/                     # huyle-only JSON, CSV, external/fusion evidence
```

The new experiment **does not overwrite** `decoder_lodo`. `common_exp.cache_path` reads baseline preprocessing caches when there is no local cache. `common_exp.fold_file` reads preexisting decoder folds from the baseline when absent locally, but unique `huyle_` experiment names ensure newly trained classifier folds are written only into `huyle/folds/`.

The included `decoders.py`, `score.py`, `fuse_general.py`, `fuse_external.py`, `eval_external.py` and other files are source-level copies of the archived baseline, to preserve file schema and original metrics. `fuse_external.py` can reuse the legacy external **decoder** evidence while reading new huyle **classifier** evidence. Core dependencies (`common.py`, `scorer.py`, `e1_switch.py`, SuperHuge source) must already be available in their original parent-repository locations; they were not contained in the archived `decoder_lodo.zip`.

## Exact STQD v1 computation

- EEG `[B,320,58]` -> channel/spatial projection + 3 residual temporal dilated blocks -> `[B,320,64]` -> stride-4 average-pooling -> EEG memory `[B,80,64]`.
- Speech `[B,320,2,3]` -> original per-window, per-speaker/per-feature standardization -> shared speaker-wise processing. Separate envelope/onset/dominance stems `[24,24,16]` -> width 64 -> 3 residual temporal blocks -> stride-4 -> candidate queries `[B,2,80,64]`.
- EEG memory supplies keys/values. Each candidate's speech sequence supplies queries. Four-head cross-attention returns `[B,2,80,64]`. A soft relative-time prior centers the EEG-response offset at +0.20 s with width 0.55 s; it is a **hypothesis**, not a proven physiology model or hard mask.
- Read target token 72 (`288 // 4`) -> candidate scores `[B,2]` from one shared head -> scalar `score[0] - score[1]`. Exact speaker-swap antisymmetry is verified by tests.
- Output contract: one signed logit per 10-second window (positive = first candidate attended); original 0.25-s hop schedule, evidence schema and `DEC_OFFSET=3` unchanged.

For the control `stqd_cosine`, the separate encoders output the same shapes but the final scoring stage uses projected cosine similarity instead of cross-attention. `stqd_global_query` replaces the temporal speech queries with pooled candidate queries. This is deliberately a **controlled ablation**, not an alternative production system.

### Variants (full suite, two seeds by default)

| Name | Single change relative to `stqd_full` |
|---|---|
| `stqd_full` | Feature-specific stems, all three features, temporal cross-attention, soft time bias |
| `stqd_joint_stem` | Concatenate envelope/onset/dom into one joint speech input convolution |
| `stqd_env` | Envelope only |
| `stqd_env_onset` | Envelope + onset |
| `stqd_env_dom` | Envelope + signed relative dominance |
| `stqd_no_time_bias` | Remove cross-attention's relative-time prior |
| `stqd_global_query` | Pool each candidate to one query (global speaker query) |
| `stqd_cosine` | Use candidate-to-EEG embedding cosine scores instead of cross-attention |

**Not included in v1:** STFT/frequency input branch, raw-waveform wav2vec 2.0, SpikeWavformer, explicit domain-adversarial objective, and changes to reconstruction. All would introduce extra confounds for the first evaluation. We also do **not** load original VLAAI classifier checkpoints into STQD: their parameters and semantics are incompatible. Each STQD variant is pretrained on SparrKULee separately, unless `--pretrain-mode none` is deliberately selected for a from-scratch control.

## Prerequisites

Use the **existing project virtual environment** (must have PyTorch, NumPy, SciPy, Pandas, PyYAML, einops, joblib, and the original repository dependencies). A CUDA GPU is strongly recommended.

The original source data must have been prepared already:

```bash
cd /root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/experiments/decoder_lodo
../../.venv/bin/python build_ea_prior.py
../../.venv/bin/python prepare_data.py eaP_n5_t60
# Fuglsang / SparrKULee conversion and glimpse caches should already exist from the baseline.
# AASD/Carta converted caches should be under sibling experiments/external_data/.
```

The new suite expects precomputed reconstruction **LODO folds** for `vlaai_ws__eaP_n5_t60_aug_cluster_onset_dom_xFUG_ptSPK` and seeds `_s1`, `_s2`, `_s3` by default. It also requires the original decoder SparrKULee checkpoint for each seed if it needs to rebuild external decoder evidence. You can reduce `--decoder-seeds`, but then fusion is no longer strictly comparable to the documented four-decoder reference.

All official dataset metadata, original scoring modules and external dataset caches must remain in the original repository. The package does not contain actual EEG recordings, credentials or checkpoints.

## Run

```bash
cd /root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/experiments/huyle
PY=../../.venv/bin/python

# Model tests: shape, swap antisymmetry, gradients, original trainer interface
PYTHONPATH=. "$PY" -m unittest discover -s tests -v

# Optional: print the planned commands, without launching training
"$PY" run_all.py --dry-run

# Start/resume the complete suite: 8 variants × 2 seeds × 5 LODO folds,
# per-variant SparrKULee classifier pretraining, original reconstruction fusion,
# all-five classifier training and AASD/Carta real-switch evaluation.
PYTHONUNBUFFERED=1 "$PY" run_all.py
```

Output location: **`logs/huyle_run.log`** is the primary end-to-end training/result log. It includes every child process's stdout/stderr, each epoch's training/validation BCE and accuracy, fold scores, fusion tables and external switch results. Child scripts also save conventional per-experiment logs for compatibility with the old source.

Run a smaller **smoke experiment** first:

```bash
"$PY" run_all.py --variants stqd_full --seeds 0 --decoder-seeds 4 \
    --pretrain-epochs 26 --fine-epochs 2 --skip-external --skip-fusion
```

This tests data loading and training, but the reduced budgets are not suitable for making scientific performance claims. For a comparable experiment restore the standard budgets. LODO is resume-aware by fold and pretraining is resume-aware by checkpoint; fusion can be rerun with `--force-fusion`. A crashed partial epoch does not resume at the minibatch level.

Possible flags:

```text
--variants stqd_full,stqd_cosine
--seeds 0,1,2,3
--pretrain-mode none              # controlled no-pretraining ablation; auto suffix _scratch
--run-tag _mycontrol             # give a new name to runs with altered settings
--skip-lodo / --skip-fusion / --skip-external
--require-existing-decoder-external # do not build original decoder external evidence
--force-fusion                    # append fusion scores again
--logfile logs/huyle_run.log
```

**Runtime warning:** full 8-variant × 2-seed suite is expensive. Each variant/seed needs SparrKULee pretraining, five LODO fine-tunings, and an all-five final classifier train. The runner intentionally runs tasks sequentially, avoiding uncontrolled concurrent GPU jobs. For shared servers, use the original `runners/jobqueue.py` if necessary, but ensure it captures the same stdout and leaves experiment directories independent.

## Results and scoring

Main outputs:

- `folds/direct_clf__eaP_n5_t60_huyle_<variant>_s<seed>/<DS>.pkl`: unchanged fold evidence/controls schema.
- `results/direct_clf__eaP_n5_t60_huyle_<variant>_s<seed>.json`: classifier-only LODO mean and per-dataset Acc, SDT, L, H, shortcut controls.
- `results/research/fuse_general.csv`: original reconstruction + STQD (train-domain LODO evidence; different alpha/pstay values).
- `results/research/ext_clf_{AASD,Carta2026}_huyle_<variant>_evidence_s<seed>.pkl`: **real** switch evidence from all-five-trained STQD models.
- `results/research/fuse_external.csv`: fused external results with source-fitted LDA/scales/HMM emission parameters.
- `results/huyle_classifier_summary.csv`, `results/huyle_lodo_fusion_summary.csv`, `results/huyle_real_switch_summary.csv`: readable post-run tables.

The `fuse_general.py` scorer fits evidence normalization/HMM emissions using the four non-held-out LODO datasets. `fuse_external.py` fits all downstream parameters on corpus evidence rather than external attention labels. AASD/Carta labels are used **only for reporting external performance**, not for choosing models in this implementation. If you use those outcomes to select architecture/hyperparameters, they are no longer an independent final test.

Our previous **H≈0.8003** is a historical synthetic-switch LODO reference, **not an STQD result** and not evidence of expected accuracy on AASD/Carta. Likewise, the historical real-switch H≈0.64 was evaluated under different conditions. Do not report numeric improvements until this code has completed the same scoring protocol.

## Practical correctness checks

1. Confirm positive `logit` means attended **column 0** in each LODO trial and after synthetic speech-column switches.
2. Confirm the speech feature ordering is exactly `env,onset,dom`. `dom` must be signed relative to the other stream; do not convert both dominance streams to magnitude spectra.
3. Check no anomalous above-chance `zero_eeg` / `shift_eeg` controls. These are computed for each held-out dataset in the retained legacy evaluator.
4. Check training validation loss and full LODO results across seeds; compare `stqd_cosine` and `stqd_full` with comparable budgets.
5. Read **both** AASD and Carta diagnostic scores at the fixed training-selected fusion/HMM settings, alongside the sensitivity grids.
6. Before any legal blind submission, rerun the actual end-to-end leakage test (including preprocessing and output expansion). The local boundary-window unit test is **not** a replacement. The user explicitly prioritized development metrics for this phase, so the package does not claim submission readiness.

## Limitations of local validation

The included tests were executed on synthetic inputs in this environment. They verify shape propagation, exact antisymmetry (up to floating-point roundoff), gradients, trainer invocation and window-count outputs. The complete server-only data preparation, original external dependencies, GPU pretraining, five held-out dataset training, scoring and real-switch evaluation **cannot** be executed in this sandbox. Any upstream changes after the archived snapshot must be reconciled against the actual server checkout.
