# Cross-dataset sAAD with causal HMM post-processing

A self-contained MATLAB example of **cross-dataset selective auditory attention decoding
(sAAD)**: it trains one backward (stimulus-reconstruction) decoder on the pooled trials of
several EEG datasets, evaluates it on a *different* dataset, applies a causal hidden Markov
model to the resulting decision sequence, and writes per-sample attention labels to CSV.

Because the decoder never sees a trial from the test dataset, the result measures how well
it **transfers to a new recording setup** — different room, montage, language, subjects.

> **If you use the HMM post-processing in your own work, please cite:**
>
> Heintz, N., Francart, T., & Bertrand, A. (2025). *Post-processing of EEG-based Auditory
> Attention Decoding Decisions via Hidden Markov Models.* arXiv:2506.24024.

## Run it

**`crossDatasetMain.m` is the main script — the only file you need to call.** It puts the
folder on the path itself, so just open it, edit the two marked settings, and run.

```matlab
>> crossDatasetMain
```

Inside it:

1. Set `dataRoot` to the folder holding your dataset folders, and `outRoot` to where the
   CSVs should go.
2. Pick the **TRAIN** block(s) and the one **TEST** block. They must not overlap; the code
   refuses if they do.
3. Run.

### Requirements

MATLAB R2019b or newer and the **Signal Processing Toolbox**. Nothing else — no Statistics
Toolbox, no EEGLAB, no external toolboxes.

### Kind reminders for spatial decoders

Currently, the training set contains the ground truth attended azimuth at each time stamp. However, we require you to only predict a binary label.

That is to say, you shall convert the label from attended azimuth to `0` if `attended azimuth<0`, representing left-hand attention, and `1` if `attended azimuth>0` for right hand attention.

In the final evaluation procedure, you shall predict the attended-direction-label in the same manner: `0` for left and `1` for right.

## What it produces

***We kindly remind you that, the submission format has not been determined yet. And the format stated followed may not be the final submission format.***


Three sets of CSV files under `outRoot`, all at **128 Hz**, one file per test subject:

```
<outRoot>/groundtruth/GTlabels_test_sample_001.csv   the reference
<outRoot>/plain/test_sample_001.csv                  window-by-window decoder
<outRoot>/causal/test_sample_001.csv                 causal HMM decoder
```

Every file has the same rows and the same three **0-based** columns:

```
time_index,label,trial
0,0,0
1,0,0
...
```

* `time_index` — sample index *within its trial*, restarting at 0 for each trial
* `label` — attended stream (`0` = first stream, `1` = second, or `0` for attended left, `1` for attended right)
* `trial` — trial index

The files are written at a fixed 128 Hz regardless of the rate the pipeline ran at, by
zero-order hold. Upsampling adds no information: a switch time is still only known to the
resolution the pipeline actually ran at. The rate is a format contract, so that predictions
from any method are comparable.

Once these files exist, the scorer needs nothing else — not the EEG, not the decoder, not
this codebase. **Predictions produced by any other method can be scored on exactly the same
footing** by writing them in this format.

## The causality constraint

Everything here obeys one rule:

> A decision for a sample may use only earlier data **from its own trial**, plus at most a
> configurable lookahead (`params.HMM.causality.lookaheadSeconds`, default `0` = strictly
> causal).

Three consequences, all deliberate:

* **The HMM runs once per trial**, not once per subject, so no chain carries state across a
  trial boundary.
* **A window's decision labels only samples after that window ended.** The first window of
  each trial therefore labels nothing, and those samples are filled with a single held
  random guess per block — the same guess for every decoder. Charging them as errors would
  bill the decoder for a gap in the evaluation grid rather than for a mistake; a deployed
  system must emit *something* there, and with no information a guess is the honest floor.
  `pred.nUndefined` reports how many samples that was, so the guessed fraction is never
  hidden.
* **Metrics are per sample, never per window.** Scoring on the window grid would both credit
  a decision for the samples it was computed from and round every switch onto the window
  grid, capping switch-timing resolution at the window length.

Only the **causal** (filtering) HMM posterior is computed. The smoothing posterior reads the
future, which the constraint forbids outright.

## Input data format

Two files per subject, in the extended CND format:

| File                                                 | Variable   | Contents                          |
| ---------------------------------------------------- | ---------- | --------------------------------- |
| `<dataRoot>/<DATASET>/dataCND/pre_dataSub<N>.mat`  | `neural` | EEG + per-sample attention labels |
| `<dataRoot>/<DATASET>/dataCND/pre_dataStim<N>.mat` | `stim`   | per-trial stimulus features       |

Fields used:

**`neural`** — `fs` (Hz); `data` (`cell{1 x nTrials}`, each `[time x channels]`, time on
dimension 1); `chanlocs` (struct array with `.labels`, needed for label-based channel
selection); `attendedStream` (`cell{1 x nTrials}`, each `[time x 1]`, the **1-based index of
the attended stream at each sample**, `0` = undefined).

**`stim`** — `fs` (must equal `neural.fs`); `data` (`cell{nFeatures x nTrials}`, **rows are
features, columns are trials**); `names` (cellstr; candidate streams are the entries ending
in `_stream<k>`, e.g. `envelope_stream1`, `envelope_stream2`, ordered by `k`, where `k` is
stream *identity* — never "attended vs unattended").

Datasets are pooled only if they agree on sampling rate, on `stim.names` exactly, and on the
selected channel labels and their order. That is what `params.preprocessing.channelSelection`
is for: the default list is the intersection of the Biosemi and NeuroScan montages, which is
what lets recordings from different hardware be pooled at all. Channels a dataset lacks
become zero columns, with a warning.

## Pipeline

```
runCrossDataset            train on the pooled training trials, decode every test window
generateSyntheticSwitches  impose switches on fixed-attention test trials  (optional)
runHMMPostprocessor        causal HMM re-decode, mapped onto the sample grid
exportPredictions          write the CSVs
```

### `runCrossDataset`

Fits from **summed sufficient statistics** (`X'X`, `X'y`, and two Ledoit-Wolf accumulators)
rather than stacked data matrices, so memory stays bounded by one subject no matter how many
datasets are pooled. Returns per-window correlations, per-sample ground truth, and the usual
accuracy table.

### `generateSyntheticSwitches` (optional)

Most public AAD datasets hold attention **fixed within a trial** and only alternate the
attended talker *between* trials — which is not a switch. On such data the switch-timing
metrics have nothing to measure.

This imposes switches at random times inside each test trial by swapping the two streams'
correlations *and* labels together. Which stream is attended is a property of the label, not
of the EEG, so swapping both preserves exactly how well the decoder separates the streams —
**the plain decoder's accuracy is provably unchanged, and the function asserts it.** Only the
temporal structure changes, which is precisely what the switch metrics measure.

> **Report any switch-timing number obtained this way as SYNTHETIC.** It measures how fast
> the decoder *would* react to a switch, on data where no switch physically happened. A
> window straddling a synthetic switch is assigned wholly to one side, so SDT carries an
> irreducible uncertainty of up to half a decision window from the synthesis itself. That
> uncertainty is identical for every algorithm scored on the same synthesised data, so it
> does not bias comparisons — but do not read an SDT difference smaller than half a window
> as meaningful.

Set `switchOpts = []` in the main script to skip this and report accuracy only. The function
prints how many switches it actually placed and how many trials were too short to host one —
check that line.

### `runHMMPostprocessor`

The plain decoder decides each window on its own, so a noisy window is simply lost. Attention
does not flicker at 1 Hz, and the sequence carries information the per-window argmax throws
away. This models the attended stream as the hidden state of a rarely-switching Markov chain
and re-decides every window from the sequence so far.

**Hyperparameters are fixed, not fitted.** The switch probability (0.001/s) and the assumed
attended-minus-unattended correlation gap are taken from Heintz et al. and the AAD
literature, and are never tuned on this data. The normalisation constants are fixed from the
*training* datasets. Nothing at all is estimated from the test set, so the numbers are an
honest external validation.

## Parameters

Set in `crossDatasetMain.m`:

```matlab
params.Leeg           = [0, 0.4];   % decoder lag window (s), post-stimulus
params.bias           = false;      % append a constant column to the design
params.windowLengths  = 1;          % decision window length (s)
params.windowHop      = [];         % s between window starts; [] = no overlap
params.regularization = struct('name', 'none');   % 'lwcov' | 'none' | 'ridge' (+ .lambda)
params.preprocessing  = struct('normEEG', 'zscore', 'normFeatures', 'zscore', ...
                               'channelSelection', {channelsToSelect}, ...
                               'reReference', 'CAR', 'targetFs', 32);

params.HMM = struct('switchProbability', 0.001, ...  % per second
                    'meanDiff',          0.2);       % assumed attended - unattended gap
```

Two settings deserve care:

* **`windowLengths`** — leave at `1` unless you also supply your own HMM normalisation
  constants (`params.HMM.sigmaGlobal` / `.meanGlobal`). The spread of a correlation depends
  strongly on how much data went into it, so the built-in constants are only valid at the 1 s
  window they were derived at. `runHMMPostprocessor` warns if you run at another length.
* **`windowHop`** — leave empty when reporting the HMM. Overlapping windows repeat the same
  evidence and break the emission independence the HMM assumes; that is left uncorrected on
  purpose, since tempering the likelihood would mean tuning a published method. Overlap
  remains fine for the plain decoder, whose windows are scored independently.

Two traps in `preprocessing`, both reported with an explicit error rather than silently:

* A cellstr for `channelSelection` must be brace-wrapped inside `struct(...)` —
  `struct('channelSelection', {labels}, ...)` — or MATLAB builds a struct *array*.
* Channel **selection** matches labels case-insensitively, but re-referencing to a *named*
  channel matches case-sensitively against the dataset's own spelling.

## Files

| File                             | Role                                                                   |
| -------------------------------- | ---------------------------------------------------------------------- |
| **`crossDatasetMain.m`** | **The main script. Start here — it is the only file you call.** |
| `runCrossDataset.m`            | Train the decoder, decode every test window.                           |
| `generateSyntheticSwitches.m`  | Impose synthetic switches on fixed-attention trials.                   |
| `runHMMPostprocessor.m`        | Causal HMM re-decode, expanded onto the sample grid.                   |
| `exportPredictions.m`          | Write the CSV label files.                                             |
| `expandToSamples.m`            | Map window decisions onto samples, causally.                           |
| `loadSubject.m`                | Read one subject's CND files and apply all preprocessing.              |
| `evaluateWindows.m`            | Windowing, per-window correlations, argmax decision.                   |
| `timeDelayEmbedding.m`         | Build the lagged design matrix from the EEG.                           |
| `computeTrialCovariances.m`    | Per-trial sufficient statistics.                                       |
| `computeLedoitWolf.m`          | Ledoit-Wolf shrinkage covariance from those statistics.                |
| `trainLinearDecoder.m`         | Solve for the decoder (`none` / `ridge` / `lwcov`).              |
| `resolveChannelSet.m`          | Named channel montages. Add your own here.                             |
| `aggregateOverTestSets.m`      | Subject-equal within a test set, test-set-equal across them.           |
| `defaultParams.m`              | Defaults for anything left unset.                                      |
| `reportAccuracy.m`             | Print the subjects × window-lengths table.                            |
| `HMM/forwardBackward.m`        | The HMM itself (forward filtering; Heintz et al.).                     |
| `HMM/computeLikelihood.m`      | Gaussian emission likelihoods for the HMM.                             |

## Citation

The HMM post-processing implements the method of:

> Heintz, N., Francart, T., & Bertrand, A. (2025). *Post-processing of EEG-based Auditory
> Attention Decoding Decisions via Hidden Markov Models.* arXiv:2506.24024.

**Please cite this paper if you use the HMM post-processing in your own work.**

`HMM/forwardBackward.m` and `HMM/computeLikelihood.m` are by Nicolas Heintz
(nicolas.heintz@kuleuven.be). The surrounding pipeline is by Simon Geirnaert, KU Leuven
(Dept. of Electrical Engineering, ESAT).
