Plugins
Authors: Francois Tadel, Raymundo Cassani
Brainstorm connects with features from many third-party libraries of methods. In Brainstorm jargon, a plugin is an external software that is can be downloaded or updated automatically by Brainstorm when needed. This tutorial presents the API to register and manage plugins.
Contents
Interactive management
The Brainstorm interface offers menus to Install/Update/Uninstall plugins.
Install: Downloads and unzips the package and all its dependencies in the Brainstorm user folder:
$HOME/.brainstorm/plugins/
Update: Some plugins are designed to update themselves automatically whenever a new version is available online, or requested by Brainstorm. Others plugins must be updated manually. Updating is equivalent to uninstalling without removing the dependencies, and then installing again.
Uninstall: Deletes the plugin folder, all its subfolders, and all the other plugins that depend on it.
Manual install: If you already have a given plugin installed on your computer (eg. FieldTrip, SPM12) and don't want Brainstorm to manage the download/update or the Matlab path for you, reference it with the menu: Custom install > Set installation folder.
Load: Adds all the subfolders needed by the plugin to the Matlab path, plus other optional tasks. Loading a plugin causes the recursive load of all the other plugins required by this plugin.
Unload: Removes all the plugin folders from the Matlab path, and all the plugins that depend on it.
Website: Opens the website documenting the plugin.
Usage statistics: Display the number of downloads of the plugin, month by month.
List: You can list all the installed plugins with the menu List:
Brainstorm plugins by category
By default Brainstorms offers a curated set of plugins organized in following categories:
Generic toolboxes:
FieldTrip: http://www.fieldtriptoolbox.org
Anatomy processing:
Brain2Mesh: http://mcx.space/brain2mesh/
- Warning: Requires the Imaging Processing Toolbox
CAT12: https://neuroimage.usc.edu/brainstorm/Tutorials/SegCAT12
CT2MRI: https://github.com/ajoshiusc/USCCleveland/tree/master/ct2mrireg
Warning: Requires the Imaging Processing Toolbox and BrainSuite
Iso2Mesh: http://iso2mesh.sourceforge.net
Zeffiro: https://github.com/sampsapursiainen/zeffiro_interface
Forward modeling:
OpenMEEG: https://neuroimage.usc.edu/brainstorm/Tutorials/TutBem
DUNEuro: https://neuroimage.usc.edu/brainstorm/Tutorials/Duneuro
Inverse modeling:
BrainEntropy: https://neuroimage.usc.edu/brainstorm/Tutorials/TutBEst
I/O Libraries for specific file formats:
AD Instruments SDK: https://github.com/JimHokanson/adinstruments_sdk_matlab
Axion BioSystems (.raw): https://www.axionbiosystems.com/products/software/neural-module
BCI2000 (.dat): https://www.bci2000.org/mediawiki/index.php/Technical_Reference:BCI2000_File_Format
Blackrock NeuroPort (.nev, .nsx): https://github.com/BlackrockMicrosystems/NPMK
EasyH5 Toolbox (.h5): https://github.com/NeuroJSON/easyh5
JSNIRF Toolbox (.snirf, .jsnirf, .bnirs): https://github.com/NeuroJSON/jsnirfy
Philips-EGI EEG (.mff): https://github.com/arnodelorme/mffmatlabio
Neuroelectrics EEGLAB plugin (.easy, .nedf): https://www.neuroelectrics.com
NumPy-Matlab (.npy): https://github.com/kwikteam/npy-matlab
Neurodata Without Borders (.nwb): https://github.com/NeurodataWithoutBorders/matnwb
Plexon (.plx, .pl2): https://plexon.com/software-downloads/#software-downloads-SDKs
Plotly export: https://plotly.com/matlab/
Tucker-Davis Technologies SDK: https://www.tdt.com/support/matlab-sdk/
Simulation:
Statistics:
mTRF-Toolbox: https://github.com/mickcrosse/mTRF-Toolbox
Picard ICA: https://github.com/pierreablin/picard
e-phys:
DeriveLFP: https://journals.physiology.org/doi/full/10.1152/jn.00642.2010
KiloSort: https://papers.nips.cc/paper/2016/hash/1145a30ff80745b56fb0cecf65305017-Abstract.html
KiloSortWrapper: https://zenodo.org/records/3604165
UltraMegaSort2000: https://github.com/danamics/UMS2K/blob/master/UltraMegaSort2000%20Manual.pdf
Wave_clus: https://journals.physiology.org/doi/full/10.1152/jn.00339.2018
fNIRS:
NIRSTORM: https://github.com/Nirstorm/nirstorm
MCXlab-cuda: http://mcx.space/wiki/
MCXlab-cl: http://mcx.space/wiki/
sEEG:
If there is a third-party software that you consider useful to the Brainstorm community, please make a post about it in the Brainstorm Forum to start the discussion.
Meanwhile, if you want to add a third-party software that is not available as a plugin, you can register such software as an user-defined plugin, see this section below: User-defined plugins.
Example: FieldTrip
We have the possibility to call some of the FieldTrip toolbox functions from the Brainstorm environment. If you are running the compiled version of Brainstorm these functions are already packaged with Brainstorm, otherwise you need to install FieldTrip on your computer, either manually or as a Brainstorm plugin.
Already in path: If you already have a recent version of FieldTrip set up on your computer and available in your Matlab path, the fieldtrip plugin entry should show a green dot, and everything should work without doing anything special.
Custom install: If FieldTrip is somewhere on your computer, but not currently in your Matlab path, you can simply tell Brainstorm where it is with the menu: Plugins > fieldtrip > Custom install > Set installation folder.
Plugin install: Otherwise, the easiest solution is to click on Plugins > fieldtrip > Install, and let Brainstorm manage everything automatically: downloading the latest version, setting the path, managing incompatibilities with other toolboxes (e.g. SPM or ROAST).
Plugin definition
The plugins registered in Brainstorm are listed in bst_plugin.m / GetSupported. Each one is an entry in the PlugDesc array, following the structure defined in db_template('plugdesc'). The fields allowed are described below.
Mandatory fields:
Name: String: Plugin name = subfolder in the Brainstorm user folder
Version: String: Version of the plugin (eg. '1.2', '21a', 'github-master', 'github-main', 'latest')
URLzip: String: Download URL, zip or tgz file accessible over HTTP/HTTPS/FTP
URLinfo: String: Information URL = Software website
Optional fields:
AutoUpdate: Boolean: If true, the plugin is updated automatically when there is a new version available (default: true).
AutoLoad: Boolean: If true, the plugin is loaded automatically at Brainstorm startup
Category: String: Sub-menu in which the plugin is listed
ExtraMenus: Cell matrix {Nx2} or {Nx3}: List of entries to add to the plugins menu
ExtraMenus{i,1}: String: Label of the menu
ExtraMenus{i,2}: String: Matlab code to eval when the menu is clicked
ExtraMenus{i,3}: String, optional: Context in which the menu is enabled {'installed', 'loaded', 'always'}. By default, the menu is always enabled.
TestFile: String: Name of a file that should be located in one of the loaded folders of the plugin (eg. 'spm.m' for SPM12). This is used to test whether the plugin was correctly installed, or whether it is available somewhere else in the Matlab path.
ReadmeFile: String: Name of the text file to display after installing the plugin (must be in the plugin folder). If empty, it tries using brainstorm3/doc/plugin/plugname_readme.txt
LogoFile: String: Name of the image file to display during the plugin download, installation, and associated computations (must be in the plugin folder). Supported extensions: gif, png. If empty, try using brainstorm3/doc/plugin/<Name>_logo.[gif|png]
MinMatlabVer: Integer: Minimum Matlab version required for using this plugin, as returned by bst_get('MatlabVersion')
CompiledStatus: Integer: Behavior of this plugin in the compiled version of Brainstorm:
- 0: Plugin is not available in the compiled distribution of Brainstorm
- 1: Plugin is available for download (only for plugins based on native compiled code)
- 2: Plugin is included in the compiled distribution of Brainstorm
RequiredPlugs: Cell-array: Additional plugins required by this plugin, that must be installed/loaded beforehand.
{Nx2} => {'plugname','version'; ...} or
{Nx1} => {'plugname'; ...}
UnloadPlugs: Cell-array of names of incompatible plugin, to unload before loading this one
LoadFolders: Cell-array of subfolders to add to the Matlab path when setting up the plugin. Use {'*'} to add all the plugin subfolders.
GetVersionFcn: String to eval or function handle to call to get the version after installation
DownloadedFcn: String to eval or function handle to call after downloading the plugin
InstalledFcn: String to eval or function handle to call after installing the plugin
UninstalledFcn: String to eval or function handle to call after uninstalling the plugin
LoadedFcn: String to eval or function handle to call after loading the plugin
UnloadedFcn: String to eval or function handle to call after unloading the plugin
DeleteFiles: Cell-array of files to delete after unzipping the plugin package (path relative to the plugin folder)
DeleteFilesBin: Cell-array of files to delete before compiling Brainstorm, to avoid including them in the binary distribution (path relative to the plugin folder)
Fields set when installing the plugin:
InstallDate: Installation date: 'dd-mmm-yyyy HH:MM:SS'
Processes: List of process functions to be added to the pipeline manager
Fields set when loading the plugin:
Path: Installation path (eg. /home/username/.brainstorm/plugins/fieldtrip)
SubFolder: If all the code is in a single subfolder (eg. /plugins/fieldtrip/fieldtrip-20210304), this is detected and the full path to the TestFile would be typically fullfile(Path, SubFolder).
isLoaded: 0=Not loaded, 1=Loaded
isManaged: 0=Installed manually by the user, 1=Installed automatically by Brainstorm
User-defined plugins
It is possible for users to register their own plugins. Once the user-defined plugin is registered, the new plugin will appear under the category User defined, and it can be installed. When a plugin is registered by the user, there will be a JSON file with the plugin definition in the Brainstorm plugin folder: $HOME/.brainstorm/plugins/
Registration of user-defined plugins can be done in three different ways:
Manually: Provide the mandatory fields of the plugin definition. All other fields will be set to their default values.
From file: Provide the path to a JSON file with the plugin definition.
From URL: Provide the URL to a JSON file with the plugin definition.
Providing the JSON file (by file path or URL) allows more flexibility in the plugin definition.
User-defined plugins can be removed with the Remove plugin option.
Example of JSON file
This is an example of a JSON file to add the processes of the bst-users repository as an user-defined plugin.
Command-line management
The calls to install or manage plugins are all documented in the header of bst_plugin.m: