MATLAB code to replicate main results from "Decoding Motor Plans Using a Closed-Loop Ultrasonic Brain-Machine Interface"
==============================
├── 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.
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.
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]
==============================
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
-
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
.
- 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 performanceRun 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 trialpretrain 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
orretrain
on. All of the data is compatible with all of the modes.
-
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
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.