= Plugins = ''Authors: Francois Tadel'' Brainstorm connects with features from many third-party libraries of methods. The external software can be downloaded or updated automatically by Brainstorm when needed. This tutorial presents the API to register and manage plugins. <> == Interactive management == The Brainstorm interface offers menus to Install/Update/Uninstall plugins. {{attachment:example1.gif}} '''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: {{attachment:list.gif||width="544",height="156"}} == Brainstorm plugins by category == Generic toolboxes: * '''SPM12''': https://www.fil.ion.ucl.ac.uk/spm/ * '''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 * '''Iso2Mesh''': http://iso2mesh.sourceforge.net * '''ROAST''': https://www.parralab.org/roast/ 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 * '''Blackrock NeuroPort''' (.nev, .nsx): https://github.com/BlackrockMicrosystems/NPMK * '''Philips-EGI EEG''' (.mff): https://github.com/arnodelorme/mffmatlabio * '''Plexon''' (.plx, .pl2): https://plexon.com/software-downloads/#software-downloads-SDKs * '''Neuroelectrics EEGLAB plugin''' (.easy, .nedf): https://www.neuroelectrics.com * '''Neurodata Without Borders''' (.nwb): https://github.com/NeurodataWithoutBorders/matnwb * '''Plotly export''': https://plotly.com/matlab/ * '''Tucker-Davis Technologies SDK''': https://www.tdt.com/support/matlab-sdk/ Simulation: * '''SimMEEG''': https://neuroimage.usc.edu/brainstorm/Tutorials/Simulations#SimMEEG Statistics: * '''LibSVM''': https://www.csie.ntu.edu.tw/~cjlin/libsvm/ e-phys: * '''DeriveLFP''': https://journals.physiology.org/doi/full/10.1152/jn.00642.2010 fNIRS: * '''NIRSTORM''': https://github.com/Nirstorm/nirstorm * '''MCXlab-cuda''': http://mcx.space/wiki/ * '''MCXlab-cl''': http://mcx.space/wiki/ sEEG: * '''MIA''': http://www.neurotrack.fr/mia/ == 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 [[http://www.fieldtriptoolbox.org/faq/should_i_add_fieldtrip_with_all_subdirectories_to_my_matlab_path|available in your Matlab path]], the fieldtrip plugin entry should show a green dot, and everything should work without doing anything special. <
><
> {{attachment:ft_path.gif}} * '''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.<
><
> {{attachment:ft_custom.gif}} * '''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). <
><
> {{attachment:ft_install.gif}} == 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', '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}: 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 * '''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/_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 loaing 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) 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 == Command-line management == The calls to install or manage plugins are all documented in the header of '''bst_plugin.m''': <)>><><)>>