Saving Feature in Bessy

An expansion of the spike on Session Saves by Brian

Problem

The current version of BCI Essentials (Bessy) has no features for saving data from a BCI session. We are interested in saving the trained classifier object within the Python (BessyPy) backend and being able to restore a trained classifier object from the Unity (BessyU) frontend.

Definitions

• BCI User: The person who is wearing the BCI equipment that reads their neural signals.
• BCI Operator: The person who is operating the computer hardware and software, such as Bessy, that analyzes the neural signals from the BCI User.
• Session: A BCI User donning BCI equipment, performing calibration that provides training data, and interacting with the Unity software. A classifier is trained from the training data and used in the remainder of the session for the brain-computer interaction.
• classifier: The Python object that contains within it the model that performs inference to convert a BCI User’s neural signals to selections in the Unity software via BessyU. This model is trained by BessyPy using data from the calibration phase of a session. The object also contains within it the training data used to train the classifier.

Current related solutions and their limitations

• Lab Recorder can be used to save the data streams passed through LSL. This is done outside of Bessy. However, we don’t want to rely on this as not all BCI Operators use Lab Recorder to save data locally.
• A classifier could be retrained from the saved data stream. However, there can still be slight differences in the classifier when retrained on the same data, depending on the type of inference model used. Importantly, there is no method within Bessy to load a trained classifier into Bessy for use in “online” mode.

Proposed solution

Add 4 new methods to Bessy to enable saving and loading of the classifier objected being used in online mode:

1. BessyPy.save_classifier: A method to save the classifier located within the EEG_data and ERP_data object in both online and offline mode. This would use Python pickle to write the classifier object from the Python interpreter’s memory to local storage.
2. BessyPy.load_classifier: A method to load a saved classifier into the EEG_data or ERP_data object in online mode. This would use Python pickle to load a classifier object from local storage into the Python interpreter’s memory
3. BessyU: A method to activate BessyPy.save_classifier so that this function can be mapped to a button or UI object.
4. BessyU: A method to activate BessyPy.load_classifier so that this function can be mapped to a button or UI object.

Use cases

Being able to save and restore the trained classifier will be helpful in at least two use cases, with Case A being a higher priority:

Case A: Computer failure. A computer failure, whether at the hardware or software level, will result in total loss of data within Bessy. As a result, a session will have to be restarted from scratch including the time-consuming calibration phase. Being able to restore a session by loading the already-trained classifier would be immensely helpful for both BCI Operators and BCI Users.

Case B: User Profiles. BCI Operators may want to save a BCI Users trained classifier, as this would allow an Operator to restore from a specific previously trained classifier, compare classifiers between sessions, or use a BCI User’s previously trained classifiers for Transfer Learning.

Feature roadmap

Version 1: Manual saving of trained classifier

• This version implements the 4 methods in the proposed solution, and begins to address case A (computer failure) and case B (user profiles).
• This version enables an Operator to save a trained classifier to an Operator-specified location and filename and to load an Operator-selected classifier into BessyPy.
• Options should be given to the Operator within the Unity interface, via BessyU, to save the classifier upon training (or after each calibration round), and to bypass training by loading a trained classifier from a file. These buttons would call BessyPy.save_classifier and BessyPy.load_classifier, respectively.

Version 2: Automatic saving of trained classifier

• This version addresses use case A (Computer failure).
• The classifier is automatically saved after each calibration round. In BessyPy the main function of EEG_data and ERP_data will need additional control logic so that BessyPy.save_classifier is called whenever the classifier is updated. This “autosaved” classifier is saved to local storage.
• The classifier can be restored when a session is restarted. This would require that BessyU is aware of the existence of an autosaved classifier and a menu option within the Unity interface that an Operator selects to load the automatically saved classifier rather than redo the training.
• Only 1 autosaved classifier will be kept in storage prevent excessive disk usage. As this feature is to address the case when the computer fails and the classifier that was actively used needs to be restored, this should be sufficient.
• The autosaved file is a “temporary” file because it will be continually overwritten as the classifier gets updated within a session, or a new session is started.
• The optimal location to save the temporary file is to be determined. It could be in some temporary storage or cache, or could be located within the folder from which BessyPy is executed. In any case, it should be somewhere that the BessyU can refer to by default for an autosaved classifier to load into BessyPy. 

Additions by Brian on April 28, 2025:

• I think that we should save the epochs rather than the classifier. Saving epochs X and labels y we can retrain the classifier or add some more data and retrain the classifier.
• This is easier now that we have the data_tank.
• Every time we add epochs to the data tank we can have the data tank save the epochs and labels as a .npz file, replacing any prior .npz. Files will be saved in bci-essentials-python/session_saves. We will have to add session_saves/*.npz to the .gitignore.
• On data_tank initialization it can look for .npz file in session_saves. And load it if it was created recently (ie. within say 15 minutes).

Version 3: User profiles that manages history of stored classifiers

• This version addresses case B (User profiles).
• BCI Operators can create BCI User profiles from which to select and load classifiers. This history of trained classifiers can provide information on the date, Operator, paradigm, purpose, accuracy, etc. This will be particularly useful for Transfer learning that may enable previously trained classifiers to initialize a new classifier.
• The user profiles could also be used to store BCI settings that are normally passed into BessyPy.