STFEEG-Tool: A Spatial-Temporal-Frequency EEG Analysis Tool for Motor Imagery Brain-Computer Interfaces

Summary

This study presents a standardized and reproducible protocol for implementing the Spatial-Temporal-Frequency EEG analysis tool (STFEEG) for motor imagery EEG decoding, incorporating configurable spatial-temporal-frequency segmentation, Common Spatial Patterns (CSP)-based feature extraction, multiple classification algorithms, and visualization capabilities.

Abstract

Motor imagery-brain-computer interfaces (MI-BCIs) have demonstrated significant potential for neurorehabilitation and cognitive neuroscience. However, a standardized and reproducible MI-EEG workflow for configurable spatial-temporal-frequency feature analysis remains limited, and many pipelines require complex configuration and parameter tuning with limited interpretability, hindering practical deployment and generalization. To address these challenges, an STFEEG-Tool was developed to provide a user-friendly, standardized, and interpretable workflow for EEG decoding in MI paradigms. STFEEG-Tool enables fine-grained configuration of temporal, frequency-band, and spatial segmentation, allowing the extraction of multiscale MI features. The toolbox integrates multiple feature extraction algorithms, including common spatial patterns (CSP) and divergence-based CSP (div-CSP), along with various classifiers, such as support vector machines (SVMs), Ridge Regression Classifier, and Lasso Classifier. A dynamic time-frequency scalp topographical map is provided to summarize spatial patterns across time-frequency segments and support interpretation of decoding results. Overall, STFEEG-Tool serves as a reproducible and extensible platform for fine-grained MI-EEG analysis, facilitating the translation of fine-grained decoding pipelines into practical, user-oriented applications.

Introduction

Motor imagery brain-computer interfaces (MI-BCIs) enable direct communication between the human brain and external devices without requiring peripheral muscle activity¹. In recent years, MI-BCI technology has been widely applied in neurorehabilitation², assistive control³, and human-computer interaction⁴. These applications highlight the need for accessible and reproducible analysis workflows that can be reliably adopted by researchers and clinicians, including users with limited programming expertise.

Conventional MI-EEG decoding approaches are predominantly based on spatial filtering and linear classification frameworks. Methods such as Common Spatial Pattern⁵ (CSP) and divergence-based CSP⁶ (div-CSP) have been widely used to extract discriminative spatial features from multi-channel EEG signals. To further extract features across distinct frequency components, Filter Bank CSP⁷ (FBCSP) and Sub-band CSP^8,9 (SBCSP) have been extensively explored. In addition, temporal segmentation has been integrated into the feature extraction process by dividing each trial into multiple time intervals, allowing the capture of evolving discriminative patterns and further enhancing decoding performance^10,11,12. To enhance the discriminability of extracted features, various feature selection strategies have been introduced to reduce redundancy and mitigate overfitting^13,14,15. For classification, traditional machine learning models such as support vector machines¹⁶ and regularized regression classifiers^17,18,19 continue to be widely used because of their interpretability and computational efficiency.

Despite their effectiveness, these approaches are typically implemented in customized, dataset-specific codebases, which complicates systematic reuse and independent verification. Several graphical user interface (GUI)-based software platforms have been developed to support EEG analysis and BCI research. For example, EEGLAB²⁰ offers a comprehensive suite of functions for EEG preprocessing, time-frequency analysis, feature extraction, classification, and advanced visualization. Its highly modular and extensible architecture has enabled broad adoption within the EEG research field. BCILAB²¹, in integration with EEGLAB, incorporates over 100 signal processing and machine learning algorithms spanning the entire decoding pipeline, from preprocessing to classification. Similarly, OpenViBE²² offers a visual programming environment for designing real-time BCI workflows, in which users can assemble signal-processing pipelines by graphically linking modular components. The platform is particularly suited for online EEG acquisition and real-time stimulus-response paradigms, and has been widely used in the development and testing of interactive BCI applications. In addition, PyNoetic, a modular Python framework for no-code EEG brain-computer interface development, enables end-to-end BCI workflow construction through an integrated GUI supporting data acquisition, preprocessing, feature extraction, and classification²³. Unlike earlier tools that require substantial manual configuration or scripting, PyNoetic offers a higher level of abstraction for pipeline design, enabling flexible assembly and reconfiguration of processing stages without low-level programming. In many MI-EEG studies, these platforms can already support routine preprocessing, conventional feature extraction, and baseline decoding and evaluation.

Several GUI-based platforms support MI-EEG analysis through standardized preprocessing, feature extraction, and baseline decoding (Table 1). However, they lack optimization for fine-grained spatial-frequency-time decomposition, including user-defined spatial partitioning and cross-domain visualization. To address these methodological needs, a fine-grained spatial-temporal-frequency decoding framework for MI-EEG²⁴ was previously proposed, jointly modeling spatial electrode groups, frequency sub-bands, and temporal segments to improve decoding performance and enhance multi-domain interpretability. Building on this framework, the Spatial-Temporal-Frequency EEG analysis tool (STFEEG-Tool) was developed as a graphical user interface (GUI)-based toolbox that standardizes fine-grained MI-EEG decoding within a configurable and reproducible workflow while remaining compatible with existing EEG toolchains.

STFEEG-Tool integrates data preparation, preprocessing, spatial-temporal-frequency segmentation, feature extraction, wrapper-based feature selection, classification, and visualization into a unified pipeline. Rather than replacing established EEG toolboxes, it complements them through transparent parameter specification, consistent pipeline execution, and model-informed visualization to support fine-grained analysis.

The main contributions of this work are threefold. First, STFEEG-Tool provides a user-friendly, end-to-end GUI workflow with standardized parameter configuration for fine-grained MI-EEG decoding. Second, it enables multiscale spatial-temporal-frequency segmentation, including user-defined spatial decomposition, which is not consistently available on general-purpose platforms. Third, it enhances interpretability through time-frequency topographical maps and electrode-group significance maps that summarize discriminative contributions and reveal subject-specific MI-relevant patterns across domains.

The toolbox is open-source and available at: https://github.com/CissyZR/Spatial-Frequency-Temporal_EEG_Analysis_Tool 

Protocol

The data used in this protocol were obtained from publicly available, de-identified datasets. The original data collection procedures were conducted in accordance with the ethical standards of the respective institutions; therefore, no additional institutional approval was required for this secondary analysis.

Figure 1 illustrates the overall workflow of the Spatial-Temporal-Frequency Electroencephalography Analysis Tool. Follow the steps below to configure each module and reproduce the fine-grained spatial-frequency-time decoding protocol. The software used in this study is listed in the Table of Materials.

1. Preparation of the software and STFEEG-Tool package

1. Install a numerical computing environment that supports MAT-file processing and GUI execution (see Table of Materials).
2. Download STFEEG - Tool from the online repository, unzip it to a local folder, and locate the installer file STFEEG-Tool.mlappinstall.
3. Double-click on STFEEG - Tool.mlappinstall, and follow the on-screen instructions to complete the installation.
4. Open the App tab, confirm that STFEEG-Tool appears in the installed apps list (Figure 2), and click on it to launch the GUI (Figure 3).

2. Preparation of the input data MAT-file

1. Create a MAT - file (.mat) containing four variables named TrainData, TrainLabel, TestData, and TestLabel.
   1. Store TrainData and TestData as 3-D arrays of size N_trials × N_channels × N_timepoints.
   2. Store TrainLabel and TestLabel as N_trials × 1 column vectors of integer class labels, using a consistent encoding across training and test sets.
      NOTE: Construct TrainData and TestData from non-overlapping sessions or recording blocks to prevent information leakage.
2. Ensure that TrainData and TestData share the same channel order and sampling frequency (Hz).
3. (Optional) Download the provided example MAT-file (Data.mat) based on BCI Competition IV 2a from the public repository to quickly test the software.

3. Launching the GUI and set paths

1. Launch the STFEEG - Tool GUI to open the MI-EEG Analysis window (Figure 3).
2. In the Data Loading panel, click on Browser next to Data Path and select the folder that contains the prepared MAT-file.
3. Confirm that the sampling frequency Fs displayed in the GUI matches the dataset sampling frequency (Hz).
4. Click on Browser next to Save Path and select an output folder to store results (e.g., configuration files, model files, and predicted labels).
5. (Optional) Specify Model Path based on the intended use.
   1. To save a model during training, click on Browser next to Model Path and select a destination folder; if Model Path is left empty, the software automatically saves the model in Save Path.
   2. To load a pretrained model for testing, click on Browser next to Model Path and select the folder that contains the saved model files.
6. Click on Load in the Data Loading panel to import the MAT-file. The software automatically checks the required variables and selected paths, and loads the dataset if no errors are reported.

4. Configuring the preprocessing (band-pass filtering)

1. Use the default band-pass filter settings shown in the GUI (Order = 5, Fc1 = 5 Hz, Fc2 = 35 Hz, filter type = IIR) unless a different preprocessing configuration is required.
2. (Optional) Enter the filter Order to override the default value.
3. (Optional) Enter the lower and upper cutoff frequencies (Fc1 and Fc2) in Hz to override the default values.
4. (Optional) Select the filter type from the drop-down menu to override the default option.
5. Click on OK to confirm the preprocessing configuration. If no changes are made, the software applies the default settings shown in the panel.

5. Configuring the fine-grained segmentation strategy

1. In the Segmentation Strategy panel of the main GUI, click on Edit to open the Segmentation configuration window.
2. Configure temporal windows.
   1. Select the Temporal Windows tab.
   2. Review the existing window list shown in the table (Figure 4).
   3. (Optional) To add windows, enter the Start, End, and Interval values, and click on Add to append the generated windows to the list.
   4. (Optional) To delete an existing window, right-click on the corresponding row in the table and select Delete.
3. Configure filter-bank frequency bands.
   1. Select the Frequency Bands tab (Figure 5).
   2. Review the existing frequency-band list shown in the table.
   3. (Optional) To add bands, enter the Start (Hz), End (Hz), and Interval values, and click on Add to append the generated bands to the list.
   4. (Optional) To delete an existing band, right-click on the corresponding row in the table and select Delete.
4. Configure spatial segmentation by channel groups (Figure 6).
   1. Select the Spatial Segmentation tab.
   2. Review the channel-group assignments in the Groups of Channel Number list.
   3. (Optional) To replace the current channel-group configuration, click on Browser next to Channel Groups to select a channel-group definition MAT-file.
   4. (Optional) To enable scalp visualizations, click on Browser next to Channel Location to select the channel-location file for the dataset channels.
      NOTE: The public repository provides savedChCell.mat (channel-group definitions) and channel_locations_22ch.txt (22-channel scalp coordinates for BCI Competition IV 2a), which can be used directly with the included example data.
   5. (Optional) Click on Replace to load the selected channel-group file and update the Groups of Channel Number list. If a channel-location file has been selected in Channel Location, the tool also loads it for subsequent scalp visualizations (Figure 7).
5. Apply and verify the segmentation settings.
   1. After completing the settings in all tabs, click on OK at the bottom of the Segmentation window to apply the updated temporal windows, frequency bands, and spatial segmentation.
   2. Return to the main GUI and confirm that the updated time bands, frequency bands, and channel groups are reflected in the Segmentation Strategy panel.

6. Configuring the feature extraction, classifiers, and cross-validation

1. In the Classification Configuration panel, select the Feature Extraction method from the drop-down menu.
   NOTE: Detailed descriptions of CSP and div-CSP are provided in Supplementary File 1.
2. Set nCSP to select CSP features from both ends of the feature vector. The tool retains the first nCSP and the last nCSP components (2 × nCSP features in total).
3. Select the classifier(s) by checking the corresponding boxes (SVM, Ridge-Optimal, Lasso-Optimal).
   NOTE: Descriptions of the three classifiers are provided in Supplementary File 2.
4. Set Selection Bands Number to specify how many fine-grained segments/features are retained in wrapper-based selection.
5. Set Cross-Validation to specify the number of folds for k-fold cross-validation on TrainData/TrainLabel.
6. (Optional) Enable Parallel to accelerate computation when multiple segments and classifiers are evaluated, if sufficient computational resources are available.
7. Click on Cross - Validation to perform k-fold cross-validation on TrainData/TrainLabel and train the final model, then test the final model on TestData/TestLabel.
   NOTE: If multiple classifiers are selected, the tool automatically selects and saves the model with the highest cross-validation accuracy, then uses it for test-set evaluation.

7. Viewing the results and visualizations

1. After clicking on Cross - Validation in Step 6, review the performance summary displayed in the Results panel, including Validation Accuracy/Kappa, Test Accuracy/Kappa, and the Per-fold Training Time and Per-fold Testing Time. Record these values for reporting.
   NOTE: Validation Accuracy/Kappa is reported as the mean k-fold cross-validation accuracy/kappa²⁵ computed on TrainData/TrainLabel. Test Accuracy/Kappa is reported as the mean test-set accuracy/kappa²⁵ obtained by evaluating the best model from each fold on TestData/TestLabel and averaging the test results across folds.
2. Inspect the visualization outputs displayed in the Results panel.
   1. Review the time-frequency topographical map to identify discriminative patterns across time, frequency, and scalp regions.
   2. Review the Electrode Group Significance Map to identify channel groups that contribute most to decoding.
      NOTE: Detailed definitions, construction procedures, and interpretation guidelines for both maps are provided in Supplementary File 3.
3. (Optional) Run test-only evaluation using a previously trained model.
   1. Click on Test Load Model to load a pretrained model from Model Path and evaluate it on the current input TestData/TestLabel.
   2. Select the Model Path folder saved during training (Step 3.5) and keep its directory structure unchanged. Ensure that model.mat is in the selected folder and param.mat is in the parent folder, as both are required to load the model and reproduce the visualizations.
   3. Confirm that, in this mode, the GUI reports Test Accuracy and Per-fold Testing Time for the loaded model, and the visualization panels update accordingly.
   4. (Optional) Locate the exported results in the save directory, which include predicted and true labels for further statistical testing.

Results

The STFEEG-Tool was validated on both the BCI Competition IV 2a²⁶ and the BCI Competition III 3a²⁷, and the system successfully executed the complete decoding pipeline in both cases. The fixed cross-session protocol of BCI Competition IV 2a was followed: training on Session 1 and evaluation on the held-out Session 2, recorded on two separate days. Under the same configuration used in the previously reported fine-grained spatial-temporal-frequency framework^...

Discussion

STFEEG-Tool is designed as an MI-EEG-specific toolbox that complements established EEG ecosystems such as EEGLAB²⁰, BCILAB²¹, OpenViBE²², PyNoetic²³. While these platforms provide flexible components for MI decoding, fine-grained spatial-temporal-frequency configuration and model-informed interpretation may involve additional integration across processing steps. This is particularly relevant when explicit electrode-group decom...

Materials

List of materials used in this article

Name	Company	Catalog Number	Comments
MATLAB	MathWorks	Version R2024a	Software environment for numerical computing, signal processing, and GUI development.
Signal Processing Toolbox	MathWorks	https://ww2.mathworks.cn/en/products/signal.html	Toolbox for digital filtering and time-frequency analysis
Statistics and Machine Learning Toolbox	MathWorks	https://ww2.mathworks.cn/en/products/statistics.html	Toolbox for model training and statistical analysis