Add BrainBERT: foundation model for intracranial (sEEG/iEEG) signals - #1104

BrainBERT(EEGModuleMixin, nn.Module): self-supervised foundation model for
intracranial (sEEG/iEEG) signals (Wang et al., ICLR 2023). The STFT is computed
inside forward so the model keeps the standard (batch, n_chans, n_times) input
signature. Modest ready-to-run defaults, with the released large config
documented; supports from_pretrained, reset_head and return_features.

Contract tests plus a parity gate: the in-model STFT is checked against the
scipy reference, and the input encoding + Transformer are checked bit-exact
against the upstream MaskedTFModel when BRAINBERT_SRC is available (skipped
otherwise so CI stays green without the external dependency).

Four changes, all answering the same objection: the port ran a plausible
variant of BrainBERT rather than the one the released checkpoint was
evaluated with.

STFT recipe. Upstream ships two, and they are not equivalent.
`preprocessors/stft.py` z-scores first and trims 10 frames per side;
`notebooks/demo.ipynb` trims 5 first and then z-scores. It is the former
that `conf/preprocessor/stft_pretrained.yaml` reaches through
`preprocessors/spec_pretrained.py`, so it is the former that produced the
published downstream numbers. The port implemented the notebook one. The
default is now the checkpoint's recipe, the other stays reachable through
`stft_clip` and `stft_zscore_before_clip`, and the docstring no longer
claims an equivalence that does not hold: on filtered noise the two
correlate at 0.999 but differ by up to 0.48 z-unit per bin and by 10
frames of sequence length.

NaN handling. Upstream zeroes NaNs that survive the statistics and
replaces a fully constant window by ones; without either, one bad sample
poisons the whole attention window. Both are ported, branch-free so
`torch.export` still traces the forward.

Pooling. Upstream averages the 10 encoder frames centred on the window of
a single electrode (`outputs[:, middle-5:middle+5].mean`); averaging every
frame appears in that same file only as a commented-out alternative. The
port averaged all frames and all channels. It now pools the centre frames
and then the channels, which is the identity at n_chans=1, so a
single-channel model reproduces the upstream feature exactly. A window too
short for the centre window is refused at construction rather than pooled
differently in silence.

Probe. `models/linear_wav_baseline.py` is `nn.Linear(input_dim, 1)` and
nothing else, so the head's LayerNorm is gone.

Also: `freq_cutoff` is renamed `idx_freq_cutoff`, since it is a bin index
and not a frequency (40 bins reach about 200 Hz, not 40); the positional
encoding refuses a sequence longer than its table instead of truncating
it; `normalizing` rejects unknown values; and the summary row moves into
alphabetical order with a 1 s window at 2048 Hz, the window the checkpoint
expects.

Towards #1097

`EEGModuleMixin.__init_subclass__` defaults `license` to `bsd-3-clause`
when a model does not declare one, and that value is what a
`push_to_hub` writes onto the model card. The upstream BrainBERT
repository ships no LICENSE file, so BSD-3 is a claim nobody can back.

The class now declares `license="unknown"`, which is what the re-hosted
weights at `braindecode/brainbert-pretrained` already say, and a test
pins it so the default cannot creep back in.

This mechanism only reached master in #1134, after this branch was
opened, which is why the omission was invisible until now.

Towards #1097

…ence

The previous STFT test reproduced the demo-notebook recipe and asserted
the port matched it, which is exactly the claim that was wrong: it
validated the port against the recipe the released checkpoint does not
use. Both recipes are now written out from the upstream sources and
checked, and a third test pins that they are *not* interchangeable, so a
future simplification cannot quietly collapse them.

The tolerance drops from 1e-4 to 5e-6. The residual is the float32 Hann
window (scipy builds it in float64) and measures 7.1e-7; at 1e-4 the test
could not have distinguished the two recipes it now separates.

New coverage: the pooled feature equals upstream's
`outputs[:, middle-5:middle+5].mean` on the same encoder output and
differs from the all-frames mean; the head carries no LayerNorm; a flat
channel stays finite; `normalizing="none"`, `clip=0` and an unknown
`normalizing` all behave; the declared licence is `unknown`.

Parity gate: `sys.path` is restored whatever happens, and the gate skips
rather than passing vacuously if `models` resolves anywhere other than
BRAINBERT_SRC. Verified green against a fresh clone of
github.com/czlwang/BrainBERT, not only skipped.

Towards #1097

The three settings that silently change what the pretrained encoder sees
are the sampling rate (an STFT bin is a fraction of sfreq, so the same 40
bins reach 205 Hz at 2048 Hz and 100 Hz at 1000 Hz), the normalisation
order (upstream ships two recipes) and the window length (the protocol
pools 10 centred frames). The example works through all three on BCI
Competition IV dataset 4, then reproduces the published downstream
protocol: frozen encoder, bare linear probe.

It also probes an untrained copy of the same architecture as a control.
The untrained encoder reaches 0.580 ROC-AUC against 0.629 for the
pretrained one and 0.500 for chance, so most of the headroom above
chance comes from the architecture rather than from the pretraining --
reporting the pretrained number alone would have overclaimed.

`activation` was typed `type[nn.Module]` and instantiated with
`activation()`. That is braindecode's house spelling (BIOT, LaBraM,
CBraMod all use it) and it stays the default, but `activation()` raises
a TypeError on the other forms `nn.TransformerEncoderLayer` itself
accepts: a string such as "gelu", a ready-made module, or a bare
callable like `torch.nn.functional.gelu`.

Fold the four forms in `_as_transformer_activation` instead: a class is
instantiated, everything else is forwarded untouched, and a class that
is not an nn.Module subclass is refused with a clear message rather
than failing later inside the encoder layer.

Widening the annotation to a union starting with str broke the shared
model config round-trip: pydantic matched the str branch first, so a
serialized "torch.nn.modules.activation.GELU" came back as that string
instead of the class, and test_config's json-serialization check failed
on BrainBERT alone.

The annotation goes back to type[nn.Module], which is what every other
braindecode constructor declares and what the config coder knows how to
decode. The runtime normalisation stays, so a string, a module instance
or a bare callable is still accepted -- it just is not the documented,
serializable form. A test pins the annotation, because test_config skips
when pydantic is absent and that is how this got through locally.

…ls/brainbert-port