""" EEGNet-GNN-Pos -- coordinate-conditioned graph conv (F1=6, F2=12) Standard EEGNet with Layer 2 replaced by a graph convolution over the electrode montage, where the montage geometry is a FIRST-CLASS INPUT rather than a way of building a fixed adjacency and then throwing the coordinates away. Temporal conv -> POS-GRAPH conv -> Separable conv -> Avg-pool + flatten -> flat (Layer 1) (Layer 2) (Layer 3) (Layer 4) OUT IDENTICAL THE SWAP IDENTICAL IDENTICAL What changed vs. eegnet_gnn.py (the index-lookup version) --------------------------------------------------------- 1. Readout is a FUNCTION OF POSITION, not a lookup table. old: node_weight = nn.Parameter(F_out, N) # column n means "C3" only # because ORDER[n] == "C3" new: node_weight = MLP(gamma(pos))^T # (F_out, N) computed from (x, y) Consequences: channel-order invariant, transfers to a different montage (different N) without changing a single learned parameter, and can express mirror symmetry because it sees that C3 and C4 are reflections of each other. 2. The conv itself is conditioned on position via FiLM: per-node scale and shift predicted from the coordinates. `pos_mode="bias"` gives the cheaper shift-only variant; `pos_mode="none"` reverts to the old behaviour for A/B. 3. Coordinate bug fixed. The old BCI_IV_2A_COORDS put the left hemisphere at x = -1, -3, -5 and the right at x = +2, +4, +6 -- the whole right side was shifted one unit outward. Second-hop adjacency was therefore NOT mirror symmetric (A_hat[C1, Cz] ~ 0.80 vs A_hat[C2, Cz] ~ 0.41), so left- and right-hand trials received different amounts of spatial smoothing. The corrected montage is symmetric; the old one is kept as BCI_IV_2A_COORDS_LEGACY so the effect can be measured. The readout stays SIGNED. That has not changed and must not change: a softmax over electrodes is a non-negative convex combination and cannot build the spatial high-pass (Laplacian-like) filter that isolates focal C3/C4 ERD. Dependencies: torch, huggingface_hub, safetensors. """ import math import numpy as np import torch import torch.nn as nn try: from huggingface_hub import PyTorchModelHubMixin as _HubMixin HAS_HFHUB = True except Exception: HAS_HFHUB = False class _HubMixin: # no-op so the file still runs without huggingface_hub def __init_subclass__(cls, **kwargs): super().__init_subclass__() # --------------------------------------------------------------------------- # 1. Electrode topology # --------------------------------------------------------------------------- # Mirror-symmetric 10-10 layout: odd numbers left (negative x), even numbers # right (positive x), matched magnitudes. C1/C2 are both 1 unit from Cz. BCI_IV_2A_COORDS = { "Fz": (0.0, 2.0), "FC3": (-3.0, 1.0), "FC1": (-1.0, 1.0), "FCz": (0.0, 1.0), "FC2": (1.0, 1.0), "FC4": (3.0, 1.0), "C5": (-5.0, 0.0), "C3": (-3.0, 0.0), "C1": (-1.0, 0.0), "Cz": (0.0, 0.0), "C2": (1.0, 0.0), "C4": (3.0, 0.0), "C6": (5.0, 0.0), "CP3": (-3.0, -1.0), "CP1": (-1.0, -1.0), "CPz": (0.0, -1.0), "CP2": (1.0, -1.0), "CP4": (3.0, -1.0), "P1": (-1.0, -2.0), "Pz": (0.0, -2.0), "P2": (1.0, -2.0), "POz": (0.0, -3.0), } # The old, asymmetric montage -- kept only so the fix can be A/B'd. BCI_IV_2A_COORDS_LEGACY = { "Fz": (0, 2), "FC3": (-3, 1), "FC1": (-1, 1), "FCz": (0, 1), "FC2": (2, 1), "FC4": (4, 1), "C5": (-5, 0), "C3": (-3, 0), "C1": (-1, 0), "Cz": (0, 0), "C2": (2, 0), "C4": (4, 0), "C6": (6, 0), "CP3": (-3, -1), "CP1": (-1, -1), "CPz": (0, -1), "CP2": (2, -1), "CP4": (4, -1), "P1": (-1, -2), "Pz": (0, -2), "P2": (2, -2), "POz": (0, -3), } BCI_IV_2A_ORDER = list(BCI_IV_2A_COORDS.keys()) # Fixed physical scale for normalising coordinates. Must NOT be derived from the # montage being used, or the same electrode would encode differently on a # 22-channel and a 64-channel cap and transfer would silently break. POS_SCALE = 5.0 def coords_to_tensor(coords, order): """dict {name: (x, y)} + name list -> (N, 2) float tensor, in montage order.""" return torch.tensor([[float(coords[e][0]), float(coords[e][1])] for e in order], dtype=torch.float32) def build_adjacency(coords=None, order=None, sigma=1.5, threshold=0.25, knn=None): """Distance-based adjacency. A_ij = exp(-d_ij^2 / (2 sigma^2)); far pairs -> 0.""" coords = BCI_IV_2A_COORDS if coords is None else coords order = BCI_IV_2A_ORDER if order is None else order pos = np.array([coords[e] for e in order], dtype=np.float32) diff = pos[:, None, :] - pos[None, :, :] dist = np.sqrt((diff ** 2).sum(-1)) A = np.exp(-(dist ** 2) / (2 * sigma ** 2)) np.fill_diagonal(A, 0.0) if knn is not None: keep = np.zeros_like(A) for i in range(A.shape[0]): nbrs = np.argsort(-A[i])[:knn] keep[i, nbrs] = A[i, nbrs] A = np.maximum(keep, keep.T) else: A[A < threshold] = 0.0 return torch.tensor(A, dtype=torch.float32) def normalize_adjacency(A): """A_hat = D^-1/2 (A + I) D^-1/2 (Kipf & Welling).""" N = A.shape[0] A = A + torch.eye(N, dtype=A.dtype, device=A.device) deg = A.sum(1) d_inv_sqrt = deg.pow(-0.5) d_inv_sqrt[torch.isinf(d_inv_sqrt)] = 0.0 return torch.diag(d_inv_sqrt) @ A @ torch.diag(d_inv_sqrt) def neighbours_of(electrode, A=None, order=None): order = BCI_IV_2A_ORDER if order is None else order if A is None: A = build_adjacency() i = order.index(electrode) return [order[j] for j in range(len(order)) if A[i, j] > 0 and j != i] def mirror_permutation(coords=None, order=None, tol=1e-6): """Index permutation that reflects the montage across the midline. perm[i] = index of the electrode at (-x_i, y_i). Midline electrodes map to themselves. Returns None if the montage is not mirror-symmetric. Two uses: (a) asserting the adjacency is left/right symmetric -- the check that catches the legacy coordinate bug; (b) left/right flip augmentation in training, where you permute channels AND swap the left/right-hand labels. """ coords = BCI_IV_2A_COORDS if coords is None else coords order = BCI_IV_2A_ORDER if order is None else order pos = np.array([coords[e] for e in order], dtype=np.float64) perm = [] for x, y in pos: hit = np.where((np.abs(pos[:, 0] + x) < tol) & (np.abs(pos[:, 1] - y) < tol))[0] if len(hit) != 1: return None perm.append(int(hit[0])) return perm # --------------------------------------------------------------------------- # 2. Positional encoding --- (x, y) -> a vector the network can condition on # --------------------------------------------------------------------------- class PositionEncoder(nn.Module): """Fourier features over 2-D montage coordinates. Raw (x, y) alone is a poor conditioning signal: a linear layer reading it can only produce weights that vary linearly across the scalp, so it cannot express a focal C3 bump. Sinusoids at several spatial frequencies let a small MLP build localised patterns -- the same reason NeRF and transformers use them. out_dim = 2 + 4 * n_freq """ def __init__(self, n_freq=4, scale=POS_SCALE): super().__init__() self.n_freq = n_freq self.scale = scale self.out_dim = 2 + 4 * n_freq self.register_buffer("freqs", math.pi * (2.0 ** torch.arange(n_freq, dtype=torch.float32))) def forward(self, pos): """pos: (N, 2) raw coordinates -> (N, out_dim).""" p = pos / self.scale # roughly [-1, 1] ang = p.unsqueeze(-1) * self.freqs # (N, 2, n_freq) feats = [p, ang.sin().flatten(1), ang.cos().flatten(1)] return torch.cat(feats, dim=-1) class CoordReadout(nn.Module): """Spatial readout weights as a FUNCTION of electrode position. This is the whole point of the file. The old layer held an (F_out, N) tensor of free parameters; column n meant "C3" only because ORDER[n] happened to be "C3". Here the same (F_out, N) matrix is PRODUCED from coordinates: node_weight[:, n] = mlp(gamma(x_n, y_n)) / sqrt(N) so the model learns a continuous spatial field over the scalp instead of a per-index table. Output is unconstrained in sign -- a softmax here would reintroduce the non-negativity that makes focal C3/C4 contrast impossible. The 1/sqrt(N) scaling keeps the readout's output variance stable when the same weights are applied to a montage with a different electrode count. """ def __init__(self, pos_dim, out_features, hidden=16): super().__init__() self.mlp = nn.Sequential( nn.Linear(pos_dim, hidden), nn.Tanh(), nn.Linear(hidden, out_features), ) # Match the old lookup table's init scale, randn/sqrt(N). PyTorch's default # Linear init would make the produced weights ~5x smaller than that, which # is a slow start for no reason. Tanh outputs have std ~0.5, so a final # weight std of 2/sqrt(hidden) puts the pre-scaling output at unit std. nn.init.normal_(self.mlp[-1].weight, std=2.0 / math.sqrt(hidden)) nn.init.zeros_(self.mlp[-1].bias) def forward(self, pos_feat): """pos_feat: (N, pos_dim) -> (F_out, N).""" N = pos_feat.shape[0] return self.mlp(pos_feat).t() / math.sqrt(N) # --------------------------------------------------------------------------- # 3. THE SWAP --- Layer 2 as a position-conditioned graph convolution # --------------------------------------------------------------------------- class GraphConvLayerPos(nn.Module): """Topology- AND geometry-aware replacement for EEGNet's depthwise spatial conv. Input : (B, F_in, N, T) Output: (B, F_out, 1, T) H = FiLM_pos( A_hat X W ) + X W_res (message passing + residual) H = ELU(BatchNorm(H)) out = H x node_weight(pos) (signed readout -> 1 "node") A_hat is a non-negative smoother, i.e. a spatial LOW-pass filter, while the discriminative motor-imagery feature is focal ERD -- a spatial HIGH-pass pattern. The residual path carries un-smoothed node features through so the readout does not have to invert the smoothing to recover focal detail. Positional conditioning enters twice: * FiLM -- per-node scale and shift predicted from (x, y), so the transform applied at C4 can differ from the one applied at C3. Note that A_hat cannot do this: C3's and C4's neighbourhoods are isomorphic, so message passing alone treats the two hemispheres identically. * readout -- see CoordReadout. """ def __init__(self, in_features, out_features, coords=None, order=None, readout="coord", residual=True, learn_adjacency=False, pos_mode="film", n_freq=4, pos_hidden=16, sigma=1.5, threshold=0.25): super().__init__() coords = BCI_IV_2A_COORDS if coords is None else coords order = BCI_IV_2A_ORDER if order is None else order A_hat = normalize_adjacency(build_adjacency(coords, order, sigma, threshold)) self.N = A_hat.shape[0] if learn_adjacency: self.A_hat = nn.Parameter(A_hat.clone()) else: self.register_buffer("A_hat", A_hat) self.register_buffer("pos", coords_to_tensor(coords, order)) # (N, 2) self.encoder = PositionEncoder(n_freq=n_freq) P = self.encoder.out_dim self.lin = nn.Linear(in_features, out_features, bias=False) # the "W" self.residual = residual if residual: self.res = nn.Linear(in_features, out_features, bias=False) self.pos_mode = pos_mode if pos_mode == "film": self.film = nn.Sequential(nn.Linear(P, pos_hidden), nn.Tanh(), nn.Linear(pos_hidden, 2 * out_features)) nn.init.zeros_(self.film[-1].weight) # start as identity: gamma=0, beta=0 nn.init.zeros_(self.film[-1].bias) elif pos_mode == "bias": self.film = nn.Sequential(nn.Linear(P, pos_hidden), nn.Tanh(), nn.Linear(pos_hidden, out_features)) nn.init.zeros_(self.film[-1].weight) nn.init.zeros_(self.film[-1].bias) elif pos_mode != "none": raise ValueError(f"unknown pos_mode '{pos_mode}'") self.bn = nn.BatchNorm2d(out_features) self.act = nn.ELU() self.readout = readout if readout == "coord": self.node_readout = CoordReadout(P, out_features, hidden=pos_hidden) elif readout == "lookup": # the previous version's free (F_out, N) table -- index-based, kept for A/B self.node_weight = nn.Parameter( torch.randn(out_features, self.N) / math.sqrt(self.N)) elif readout not in ("mean", "attention"): raise ValueError(f"unknown readout '{readout}'") if readout == "attention": self.att = nn.Linear(out_features, 1) self.out_features = out_features def _pos_feat(self): return self.encoder(self.pos) # (N, P) def spatial_patterns(self): """(F_out, N) spatial weights actually in use, for plotting on the montage.""" with torch.no_grad(): if self.readout == "coord": return self.node_readout(self._pos_feat()).cpu() if self.readout == "lookup": return self.node_weight.detach().cpu() raise RuntimeError("spatial_patterns() needs readout='coord' or 'lookup'") def pattern_at(self, xy): """Evaluate the learned spatial field at ARBITRARY coordinates (M, 2). Only possible with readout='coord'. The lookup readout is defined solely at the N training electrodes and has nothing to say about the gaps. """ if self.readout != "coord": raise RuntimeError("pattern_at() needs readout='coord'") xy = torch.as_tensor(xy, dtype=torch.float32, device=self.pos.device) with torch.no_grad(): # undo the 1/sqrt(N) so a dense grid is comparable to the electrodes return (self.node_readout(self.encoder(xy)) * math.sqrt(xy.shape[0])).cpu() def forward(self, x): B, F_in, N, T = x.shape h = x.permute(0, 3, 2, 1) # (B, T, N, F_in) agg = torch.einsum("ij,btjf->btif", self.A_hat, h) # pull from neighbours out = self.lin(agg) # (B, T, N, F_out) if self.pos_mode != "none": pf = self.film(self._pos_feat()) # (N, *) if self.pos_mode == "film": gamma, beta = pf.chunk(2, dim=-1) # (N, F_out) each out = out * (1.0 + gamma) + beta else: out = out + pf if self.residual: out = out + self.res(h) # keep focal per-electrode detail out = out.permute(0, 3, 2, 1) # (B, F_out, N, T) out = self.act(self.bn(out)) # collapse the N electrodes -> 1 if self.readout == "mean": pooled = out.mean(dim=2, keepdim=True) elif self.readout == "coord": w = self.node_readout(self._pos_feat()) # (F_out, N) pooled = torch.einsum("bfnt,fn->bft", out, w).unsqueeze(2) elif self.readout == "lookup": pooled = torch.einsum("bfnt,fn->bft", out, self.node_weight).unsqueeze(2) else: # attention -- softmax over electrodes, NON-NEGATIVE, kept only to show it fails s = out.permute(0, 3, 2, 1) a = torch.softmax(self.att(s), dim=2) pooled = (s * a).sum(2).permute(0, 2, 1).unsqueeze(2) return pooled # (B, F_out, 1, T) class DepthwiseSpatial(nn.Module): """Standard EEGNet Layer 2 (the thing being swapped out) -- kept for A/B.""" def __init__(self, F1, F2, n_channels): super().__init__() assert F2 % F1 == 0, ( f"F2={F2} must be a multiple of F1={F1} (depth multiplier D = F2/F1).") self.conv = nn.Conv2d(F1, F2, (n_channels, 1), groups=F1, bias=False) self.bn = nn.BatchNorm2d(F2) self.act = nn.ELU() def forward(self, x): return self.act(self.bn(self.conv(x))) class SeparableConv(nn.Module): def __init__(self, in_ch, out_ch, kernel): super().__init__() self.depthwise = nn.Conv2d(in_ch, in_ch, (1, kernel), padding="same", groups=in_ch, bias=False) self.pointwise = nn.Conv2d(in_ch, out_ch, 1, bias=False) def forward(self, x): return self.pointwise(self.depthwise(x)) # --------------------------------------------------------------------------- # 4. Feature extractor --- Layers 1-4, returns the flat vector (no head) # --------------------------------------------------------------------------- class EEGNetGNNPos(nn.Module, _HubMixin, license="mit", pipeline_tag="feature-extraction", tags=["eeg", "bci", "motor-imagery", "eegnet", "graph-neural-network", "positional-encoding", "feature-extraction", "pytorch"]): """EEGNet with a switchable, position-conditioned spatial layer. Everything except Layer 2 is stock EEGNet-8,2 proportions: (1,64) temporal conv, two-stage (1,4) -> (1,8) pooling, separable conv. With the defaults (F1=6, F2=12, n_times=1000) flat_dim is 372, matching the index-lookup version so the two can be compared with an identical head. """ def __init__(self, n_times=1000, coords=None, order=None, F1=6, F2=12, kern_length=64, sep_kern=16, spatial="graph", readout="coord", residual=True, learn_adjacency=False, pos_mode="film", n_freq=4, pos_hidden=16, sigma=1.5, threshold=0.25, pool1=4, pool2=8, dropout=0.25): super().__init__() coords = BCI_IV_2A_COORDS if coords is None else coords order = BCI_IV_2A_ORDER if order is None else order # config.json round-trips tuples as lists -- normalise so both work coords = {k: (float(v[0]), float(v[1])) for k, v in coords.items()} order = list(order) missing = [e for e in order if e not in coords] if missing: raise ValueError(f"no coordinates for {missing}") self._cfg = dict(n_times=n_times, F1=F1, F2=F2, kern_length=kern_length, sep_kern=sep_kern, spatial=spatial, readout=readout, residual=residual, learn_adjacency=learn_adjacency, pos_mode=pos_mode, n_freq=n_freq, pos_hidden=pos_hidden, sigma=sigma, threshold=threshold, pool1=pool1, pool2=pool2, dropout=dropout) self.coords, self.order = coords, order self.n_channels = len(order) # Layer 1 -- Temporal conv (IDENTICAL in both branches) self.temporal = nn.Sequential( nn.Conv2d(1, F1, (1, kern_length), padding="same", bias=False), nn.BatchNorm2d(F1), ) # Layer 2 -- the swap point if spatial == "graph": self.spatial = GraphConvLayerPos( F1, F2, coords=coords, order=order, readout=readout, residual=residual, learn_adjacency=learn_adjacency, pos_mode=pos_mode, n_freq=n_freq, pos_hidden=pos_hidden, sigma=sigma, threshold=threshold) elif spatial == "depthwise": self.spatial = DepthwiseSpatial(F1, F2, self.n_channels) else: raise ValueError("spatial must be 'graph' or 'depthwise'") self.pool1 = nn.AvgPool2d((1, pool1)) self.spatial_drop = nn.Dropout(dropout) # Layer 3 -- Separable conv (IDENTICAL) self.separable = nn.Sequential( SeparableConv(F2, F2, sep_kern), nn.BatchNorm2d(F2), nn.ELU(), ) # Layer 4 -- Avg pool + flatten (IDENTICAL) -> flat feature vector self.pool2 = nn.AvgPool2d((1, pool2)) self.sep_drop = nn.Dropout(dropout) self.flatten = nn.Flatten() with torch.no_grad(): was_training = self.training self.eval() self.flat_dim = self.forward( torch.zeros(1, 1, self.n_channels, n_times)).shape[1] self.train(was_training) def forward(self, x): x = self.temporal(x) # (B, F1, N, T) x = self.spatial(x) # (B, F2, 1, T) x = self.spatial_drop(self.pool1(x)) x = self.separable(x) # (B, F2, 1, T/pool1) x = self.sep_drop(self.pool2(x)) return self.flatten(x) # (B, flat_dim) # -- montage transfer --------------------------------------------------- def transfer_to_montage(self, coords, order): """Return a copy of this model wired to a DIFFERENT electrode montage. Every learned parameter carries over unchanged, including when the new montage has a different number of electrodes, because no parameter is indexed by electrode: the readout and FiLM weights are functions of (x, y). Only the A_hat and pos buffers are rebuilt. Raises with readout='lookup' -- an (F_out, N) table has no meaning on a montage it was not trained on. That contrast is the point of the method. """ if self._cfg["spatial"] != "graph": raise RuntimeError("montage transfer needs spatial='graph'") if self._cfg["readout"] != "coord": raise RuntimeError( f"readout='{self._cfg['readout']}' is indexed by electrode position " "in the channel list, so it cannot transfer. Use readout='coord'.") cfg = dict(self._cfg) n_times = cfg.pop("n_times") new = EEGNetGNNPos(n_times=n_times, coords=coords, order=order, **cfg) src = self.state_dict() keep = {k: v for k, v in src.items() if not k.startswith("spatial.A_hat") and not k.startswith("spatial.pos")} missing, unexpected = new.load_state_dict(keep, strict=False) assert not unexpected, f"unexpected keys: {unexpected}" assert all(k.startswith("spatial.A_hat") or k.startswith("spatial.pos") for k in missing), f"failed to transfer: {missing}" return new class EEGNetGNNPosClassifier(nn.Module): """Backbone + linear head, trained END-TO-END. Layer 2 does not classify anything: it outputs (B, F2, 1, T). The left-vs-right decision is a subtraction performed by this Linear over the pooled feature maps. Nothing is frozen -- freezing a randomly-initialised backbone is logistic regression on random projections. """ def __init__(self, backbone, n_classes, dropout_rate=0.5): super().__init__() self.backbone = backbone self.dropout = nn.Dropout(dropout_rate) self.classifier = nn.Linear(backbone.flat_dim, n_classes) def forward(self, x): return self.classifier(self.dropout(self.backbone(x))) @torch.no_grad() def extract_features(self, x): self.backbone.eval() return self.backbone(x)