MATLAB code to replicate main results from "Decoding Motor Plans Using a Closed-Loop Ultrasonic Brain-Machine Interface"

==============================

Project Organization

├── README.md           <- The top-level README for developers using this project
├── setup.m             <- Used to setup the repo and data directory hierarchy
├── behavior            <- functions for parsing behavioral files and data
├── data loading        <- functions for loading data
├── decoders            <- functions related to decoding, including different decoder algorithms
│   └── classwise PCA   <- specialized functions for classwise PCA
├── images              <- Referenced by `README.md` to explain dialog boxes and user choices.
├── image alignment     <- functions for aligning different datasets and pretraining models
├── plotting            <- functions for visualization of results and output
├── statistics          <- functions for calculating different types of statistics
├── utilities           <- functions with miscellanous purposes
└── third-party         <- third party repositories, functions, etc.

Associated dataset

Available from CaltechData: Click here to download.

Packaged as .zip file in data hierarchy used by MATLAB functions. Once downloaded, extract contents from the .zip file.

├── project_record.json               Metadata about each experimental session.
├── DescriptionOfFiles.pdf            Information about contents of .mat files
├── aligned_doppler_data              Empty folder where aligned datasets will be saved
├── doppler data
|   └──rt_fUS_data_S{*A}_R{*B}.mat    Doppler data files where {*A} is the session number and {*B} is the run number.
├── output                            Empty folder where figures and output will be saved.
├── simulated                         Empty folder where simulated BMI sessions will be saved.
├── sulcus                            Empty folder where sulcal maps will be saved.

Other information

Tested on MATLAB R2021a on Windows 10, MATLAB 2021b, and MATLAB 2022b on Mac Ventura 13.4.1 Please send feedback and suggestions to: [email protected]

Zenodo archive -

==============================

In publications, please reference:

Griggs, W.S., Norman, S.L., Deffieux, T., Segura, F., Osmanski, B.-F., Chau, G., Christopoulos, V., Liu, C., Tanter, M., Shapiro, M.G., and Andersen, R.A. Decoding Motor Plans Using a Closed-Loop Ultrasonic Brain-Machine Interface. Nature Neuroscience. November 30, 2023. https://www.nature.com/articles/s41593-023-01500-7

Quick Start

Clone this repo to a known location on your computer.
Download paired dataset from CaltechData and unzip in a location that is convenient.
Run setup.m. This will add appropriate folders to MATLAB search path and specify path to the downloaded data directory.
Run code blocks from main_analysis.m.

Demo of `simulate_real_time_fUS_BMI`

Select fUS-BMI run mode. Here, I chose the verbose mode.

Run as fast as possible with minimal user display - Fast mode; Will display occasional updates to the command line and MATLAB figure about performance
Run slower with full display of data streaming and trial performance - Verbose mode; Will display simulated data streaming, task, and trial-by-trial performance of fUS-BMI

Select training mode. Here, I chose the pretrain+retrain option.

pretrain+retrain - Use both a pretrained model and retrain after each trial
pretrain only - Use only a pretrained model and do not retrain model.
retrain only - Use only data from current session and retrain after each trial after sufficient trials for initial training set.
For more description of pretraining vs retraining, see paper.

Select dataset to test (and retrain) fUS-BMI on.

If retrain option was selected in step #2. Then data from this dataset will also be included in training dataset.
Does not matter whether the underlying dataset was collected with pretrain or retrain on. All of the data is compatible with all of the modes.

Select if you want to save the data from this run
If you want to save the data, select where to save.
If you specified to use pretrain option, then select aligned dataset to use

If no aligned datasets exist or you want to create a new one, then select cancel.

Specify whether you want to create an aligned dataset to be used for pretraining or if you just want to quit.
Specify which dataset you want to use for pretraining.

Warning

If you choose the same dataset you chose earlier, this will create a data leak.

Align neurovascular maps using the MATLAB app.

Automated Intensity-Based Image Alignment button - This should get the two neurovascular images mostly aligned.
If the alignment can be improved, use the arrow keys to translate the image and r/t to rotate the image.
Once you are happy with the alignment, click save transform to workspace button.
If you want to reset to initial alignment, click reset to initial alignment button

Pre-alignment

Post-alignment

Select where to save the aligned dataset.
The fUS-BMI will now run.

Demo of `simulate_real_time_fUS_BMI`

Select dataset

1.5. (if sulcus has been previously traced and saved) Can specify if you want to create a new sulcus map

Trace the brain surface and sulci.

Trace the brain surface and sulci by sequentially clicking on the image with the crosshairs.
Once finished, press Enter.
There should be one line between the left and right side of the image and the line should not cross itself.