braindecode.models.FNIRSCNN1D#

class braindecode.models.FNIRSCNN1D(n_outputs=None, n_chans=None, chs_info=None, n_times=None, input_window_seconds=None, sfreq=None, *, n_filters_conv1=64, n_filters_conv2=128, kernel_size_conv1=7, kernel_size_conv2=5, pool_size=2, n_norm_groups=8, drop_prob=0.5, activation=<class 'torch.nn.modules.activation.GELU'>)[source]#

FNIRSCNN1D, the 1D-CNN of Trakoolwilaiwan et al. (2018), as in GeoNIRS.

Convolution

Added in version 2.1.

Trakoolwilaiwan et al. [1] proposed convolutional neural networks for fNIRS brain-computer interfaces, to classify rest, right- and left-hand motor execution from HbO/HbR signals. The GeoNIRS benchmark [2] uses a “1D-CNN (Trakoolwilaiwan et al., 2018)” as its first supervised neural baseline (Section 3.1; the “1D-CNN” rows of Tables 1, 14 and 15, and 88.4 K parameters in Table 10). This class ports that baseline: the DirectEventCNN1DClassifier of the GeoNIRS repository (commit 81f8995) as its benchmark builds it, one classifier per event window. The two GroupNorm and GELU stages are the GeoNIRS authors’ (the networks of Trakoolwilaiwan et al. use one or three convolutions of kernel 3 with max pooling and dropout), and the architecture is documented from their code.

The model is small and direct. Two temporal convolutions read the window, the second of them at half the sampling rate; the result is averaged over time and classified. Nothing in it knows about channels, chromophores or optode geometry: the first convolution mixes every row. With \(B\) the batch size, \(C\) = n_chans, \(T\) = n_times and \(F_1\), \(F_2\) the two filter counts, the steps are:

x (B, C, T): HbO rows then HbR rows; NaN or inf = missing sample
1. temporal_conv1: Conv1d, GroupNorm, GELU, MaxPool1d  -> (B, F_1, T // 2)
2. temporal_conv2: Conv1d, GroupNorm, GELU             -> (B, F_2, T // 2)
3. time_pool, flatten_layer, head_dropout              -> (B, F_2)
4. final_layer                                         -> (B, n_outputs)

Macro Components

  • FNIRSCNN1D.temporal_conv1 First temporal convolution

    Conv1d (64 filters, kernel 7, padding="same"), GroupNorm (8 groups), GELU and MaxPool1d (kernel 2), which halves the time axis. The kernel spans 7 samples, 1.4 s at the 5 Hz of the GeoNIRS inputs.

  • FNIRSCNN1D.temporal_conv2 Second temporal convolution

    Conv1d (128 filters, kernel 5, padding="same"), GroupNorm (8 groups) and GELU, at half rate, so its 5 samples span 2 s of the input.

  • FNIRSCNN1D.final_layer Classification head

    The feature maps are averaged over time (AdaptiveAvgPool1d), then Dropout (0.5) and one Linear. The average is what lets the model take a window of any length.

Temporal, Spatial, and Chromophore Encoding

  • Temporal. Two short kernels and one halving of the rate. The final average throws the position of a response away, so the model reads the window as a bag of short patterns.

  • Spatial. None. The first convolution mixes every row, and no optode position is read.

  • Chromophores. HbO and HbR are ordinary rows. Their order must be the one used in training: the GeoNIRS benchmark stacks the HbO rows before the HbR rows, HbO_1, ..., HbO_C, HbR_1, ..., HbR_C. chs_info is not read.

Pretrained Weights

None. The baseline is trained from scratch on each task.

Differences from the Reference Implementation

  • Input. One tensor (batch, n_chans, n_times). The reference takes a batch dictionary with hbo, hbr and a validity mask, replaces the invalid samples by zero and stacks the HbO rows before the HbR rows. Here a non-finite value (NaN or inf) marks a missing sample and is read as zero. The reference’s mask covers both chromophores of a pair, so a sample missing in one of them should be NaN in both.

  • Parity. With the same seed, this class and the authors’ module draw the same weights and give the same logits (max-abs 0.0), in eval mode and in train mode. mapping renames their encoder. and linear. keys, so their state dict loads with strict=True.

  • Event pairs. The reference can also aggregate the events of a pair before its head (event_pair_mode). The benchmark builds it with that mode off, and this class has only that mode.

  • Additions. The kernel lengths, the pooling length, the number of normalization groups and activation are arguments, fixed in the reference. ch_mask is refused, because the first convolution spans every row.

Parameters:
  • n_outputs (int | None) – Number of outputs of the model. This is the number of classes in the case of classification.

  • n_chans (int | None) – Number of EEG channels.

  • chs_info (list[dict] | None) – Information about each individual EEG channel. This should be filled with info["chs"]. Refer to mne.Info for more details.

  • n_times (int | None) – Number of time samples of the input window.

  • input_window_seconds (float | None) – Length of the input window in seconds.

  • sfreq (float | None) – Sampling frequency of the EEG recordings.

  • n_filters_conv1 (int) – Filters of the first temporal convolution (conv_dim in the reference).

  • n_filters_conv2 (int) – Filters of the second temporal convolution, and the feature size (embedding_dim in the reference).

  • kernel_size_conv1 (int) – Kernel length of the first temporal convolution, in samples; an odd length keeps the reference’s symmetric padding.

  • kernel_size_conv2 (int) – Kernel length of the second temporal convolution, in samples; an odd length keeps the reference’s symmetric padding.

  • pool_size (int) – Length and stride of the max pooling after the first convolution.

  • n_norm_groups (int) – Groups of both GroupNorm layers. It must divide both filter counts.

  • drop_prob (float) – Dropout probability before final_layer (dropout in the reference).

  • activation (type[Module]) – Activation after each GroupNorm.

Raises:

ValueError – If some input signal-related parameters are not specified: and can not be inferred.

Notes

In the GeoNIRS benchmark (Section 3.1 and Appendices B.1 and B.5-B.6 of [2]), “baseline models receive the same frozen downstream inputs as GeoNIRS” and “follow the unified protocol in Table 8”: HbO and HbR in µmol/L resampled to 5 Hz and z-scored per recording; eight held-out binary tasks with subject-level five-fold cross-validation and the seeds 810 and 811; 30 epochs, batch 16, AdamW (weight decay 0.05; learning rate 1e-4, from the repository’s downstream.yaml), class-weighted cross-entropy, and model selection by validation balanced accuracy.

Replication through the authors’ training loop with this class in place of theirs (mean over the five test folds and the two seeds; the authors’ module gives the same value in each of the 20 cells, max-abs 0.0; half the range across the two seeds is at most 0.29 points):

Task

Metric

GeoNIRS paper (%)

This class (%)

DS42 (action mode)

macro-F1

55.53

55.85

DS42 (action mode)

AUROC

59.67

59.32

DS19 (pain intensity)

macro-F1

50.05

50.22

DS19 (pain intensity)

AUROC

50.76

49.73

References

Hugging Face Hub integration

When the optional huggingface_hub package is installed, all models automatically gain the ability to be pushed to and loaded from the Hugging Face Hub. Install with:

pip install braindecode[hub]

Pushing a model to the Hub:

from braindecode.models import FNIRSCNN1D

# Train your model
model = FNIRSCNN1D(n_chans=22, n_outputs=4, n_times=1000)
# ... training code ...

# Push to the Hub; ``datasets`` and ``base_model`` go to the card
model.push_to_hub(
    repo_id="username/my-fnirscnn1d-model",
    commit_message="Initial model upload",
    model_card_kwargs={"datasets": ["BNCI2014_001"]},
)

Loading a model from the Hub:

from braindecode.models import FNIRSCNN1D

# Load pretrained model
model = FNIRSCNN1D.from_pretrained("username/my-fnirscnn1d-model")
# Data the weights were trained on, from the Hub model card
print(model.card_data.datasets if model.card_data else None)

# Load with a different number of outputs (head is rebuilt automatically)
model = FNIRSCNN1D.from_pretrained("username/my-fnirscnn1d-model", n_outputs=4)

Extracting features and replacing the head:

import torch

x = torch.randn(1, model.n_chans, model.n_times)
# Extract encoder features (consistent dict across all models)
out = model(x, return_features=True)
features = out["features"]

# Replace the classification head
model.reset_head(n_outputs=10)

Saving and restoring full configuration:

import json

config = model.get_config()            # all __init__ params
with open("config.json", "w") as f:
    json.dump(config, f)

model2 = FNIRSCNN1D.from_config(config)    # reconstruct (no weights)

All model parameters (both EEG-specific and model-specific such as dropout rates, activation functions, number of filters) are automatically saved to the Hub and restored when loading.

See Loading and Adapting Pretrained Foundation Models for a complete tutorial.

Methods

forward(x, return_features=False, ch_mask=None)[source]#

Forward pass of the FNIRSCNN1D model.

Parameters:
  • x (Tensor) – Input tensor with shape (batch_size, n_chans, n_times). A non-finite value (NaN or inf) marks a missing sample and is read as zero.

  • return_features (bool) – If True, return the input of final_layer instead of the logits.

  • ch_mask (Tensor | None) – Not supported, because the first convolution spans every row.

Returns:

Output tensor with shape (batch_size, n_outputs), or {"features": (batch_size, n_filters_conv2), "cls_token": None} with return_features=True.

Return type:

Tensor | dict[str, Tensor | None]

reset_head(n_outputs)[source]#

Replace the classification head for a new number of outputs.

This is called automatically by from_pretrained() when the user passes an n_outputs that differs from the saved config. Override in subclasses that need a model-specific head structure. Implementations keep changed constructor arguments in sync with self._update_init_kwargs, so that a saved model can be loaded back. Implementations requiring positive outputs can also use self._set_n_outputs to validate and record the new value.

Parameters:

n_outputs (int) – New number of output classes.

Return type:

None

Examples

>>> from braindecode.models import BENDR
>>> model = BENDR(n_chans=22, n_times=1000, n_outputs=4)
>>> model.reset_head(10)
>>> model.n_outputs
10

Added in version 1.4.