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
DirectEventCNN1DClassifierof the GeoNIRS repository (commit81f8995) 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_timesand \(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_conv1First temporal convolutionConv1d(64 filters, kernel 7,padding="same"),GroupNorm(8 groups), GELU andMaxPool1d(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_conv2Second temporal convolutionConv1d(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_layerClassification headThe feature maps are averaged over time (
AdaptiveAvgPool1d), thenDropout(0.5) and oneLinear. 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_infois 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 withhbo,hbrand 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.
mappingrenames theirencoder.andlinear.keys, so their state dict loads withstrict=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
activationare arguments, fixed in the reference.ch_maskis 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.chs_info (
list[dict] |None) – Information about each individual EEG channel. This should be filled withinfo["chs"]. Refer tomne.Infofor 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_dimin the reference).n_filters_conv2 (
int) – Filters of the second temporal convolution, and the feature size (embedding_dimin 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 bothGroupNormlayers. It must divide both filter counts.drop_prob (
float) – Dropout probability beforefinal_layer(dropoutin the reference).activation (
type[Module]) – Activation after eachGroupNorm.
- 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_hubpackage 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 offinal_layerinstead 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}withreturn_features=True.- Return type:
- 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 ann_outputsthat differs from the saved config. Override in subclasses that need a model-specific head structure. Implementations keep changed constructor arguments in sync withself._update_init_kwargs, so that a saved model can be loaded back. Implementations requiring positive outputs can also useself._set_n_outputsto validate and record the new value.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.