This repository contains the source of SOFA, a model aimed at improving brain-computer interfaces (BCIs) by automatically selecting parameters best suited to each run.

The objective was to create a model simple to understand, implement and tune, yet efficient enough to improve BCIs over sparse data.

The model records observations, i.e. past choices and their (averaged) associated outcomes. The model can also be provided with priors, if there exist data about a participant and the most likely outcomes -- for example if there exist a correlation between personality traits and difficulty selection.

The more evidence toward a positive outcome, the more likely the action leading to said outcome will be selected. To do so, a softmax function is used to translate knowledge (observations and/or priors) into probabilistic actions.

The model possesses only two parameters. The first parameter is the confidence in the priors, a coefficient applied to them before softmax. The second parameter is the weight of the observations, a coefficient applied to observations that will increase by that much each iteration. The reasoning is that the more observations the model gathers, the more trustful it becomes in them. Increasing the weight is akin to speeding-up the shift from exploration to exploitation.

The model is implemented in python, as a ModelAdaptive class (python/model_adaptive.py). A Model abstraction class (python/model.py) is used to facilitate the comparisons with other models. For repeatability, a numpy RandomState instance can be passed to the models to draw random numbers from.

To run and test the model with default dataset, simply run python/main.py. The required python packages are listed in the python/requirements.txt file.

Tested with python 2.7 (pandas 0.23.4 and numpy 1.14.5) and python 3.12 (pandas 2.3.1 and numpy 2.3.5).

To test the model, simulations are performed on data extracted from Mladenovic et al., Towards Identifying Optimal Biased Feedback for Various User States and Traits in Motor Imagery BCI, IEEE Trans Biomed Eng. 2022 Mar;69(3):1101-1110. doi: 10.1109/TBME.2021.3113854. Epub 2022 Feb 18., and gathered in data/fusion.csv file.

In this experiment a biased feedback was implemented: the task could be made easier or harder. The resulting BCI performance was compared across three groups (either positive, negative or neutral bias). It was shown that some personality traits could predict which bias was best suited to participants.

We simulated how the SOFA model would behave if it was used to select the bias from run to run, attempting to automatically select the bias that would yield the best performance for each participant -- here using an "archetype" of a participant, matching traits over the three groups.

The experiment comprised two sessions. The first session was used to create priors (here links between personality traits and best suited bias), the second was used as the test set

The adaptive model (SOFA) was compared against a random model (random selection of the bias each run) and fixed models (same bias always selected). The behavior of adaptive model was tested depending if priors were given or not, if said priors were purposely misleading or not, and if observations were used or not.

The output of the simulations were recorded in data/models_big.csv.bz2 and R was used to process the data (entry point R/main.R, tested with R 4.3.3 and psych 2.4.1, ggsignif 0.6.4, multcomp 1.4-25, nlme 3.1-164, ez 4.5-0, ggplot2 3.4.4, rmarkdown 2.25).

Copyright (c) 2019-2026 Jérémy Frey & Jelena Mladenović

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.

If you use this software, please cite it as below:

@software{frey_2026_21890344,
  author       = {Frey, J\'{e}r\'{e}my and
                  Mladenovi\'{c}, Jelena},
  title        = {SOFA: Softmax Optimized Feedback Adaptation},
  month        = aug,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {v0.1.0},
  doi          = {10.5281/zenodo.21890344},
  url          = {https://github.com/jfrey-xx/SOFA-source},
}