BST_2_ZI
The goal of these introductions is to guide you through most of the features of the Zeffiro Interface (ZI) accessed through Brainstorm in the form of a Plugin. The results of one section are most of the time used in the following section, therefore read the content of this page in the correct order. Throughout this tutorial, we might refer to ZI with different names such as “ZI,” “zeffiro,” or “zef” instead, and Brainstorm as “BST.” Some sections of the pages may contain too many details for your level of interest or competence. Therefore, this walkthrough has been divided on the level of difficulty as [Simple] and [Advanced]. Please follow these tutorials, and, if required, with the data we provide. This way you will be able to prioritize the essential functions of ZI. After going through these instructions, you should be comfortable enough to test this plugin with your own recordings. You may observe minor differences between the screen captures presented in these pages and what you obtain on your computer: different colormaps, different values, etc. The software is constantly being improved, and some results have changed since we produced the illustrations. When the changes are minor and the interpretation of the figures remains the same, we don't necessarily update the images in the tutorial.
To ensure that the tutorial will be successful, we encourage users to go through BST’s Tutorial 1: Create a new protocol to understand how different directories work.
As always, be sure to cite and give the corresponding credit to the respective developer team whenever ZI is used in your projects.
Installation of Zeffiro Interface (ZI) in BST is accomplished by selecting Plugins -> Anatomy -> zeffiro -> Install (github-main_development_branch) [Fig. 1]. The plugin manager will ask if you wish to install the latest version of zeffiro. Select Yes if you do not have ZI installed. The installation will be done automatically, and the corresponding files can be found within the Brainstorm plugin folder. If you already have ZI installed, cancel the task instead and indicate where your ZI working folder is. Select Custom install -> Select installation folder and navigate through your file explorer to select the working folder featuring your current ZI tools (typically, zeffiro_interface-main_development_branch).
Once the installation is complete, you will notice that BST now recognizes ZI, and the options for loading and unloading have been toggled [Fig. 2]. You can also see that the plugin status is now set as ready [green].
 |
 |
|---|---|
| Figure 1: Plugins tab, then Anatomy, and then the zeffiro section. | Figure 2: Successful ZI installation. |
You will now build a simple FEM mesh structure to ensure that ZI can be called from BST.
The ZI’s mesh generation routine can be run either by calling it directly from BST (Simple) with minimal variables, or by calling the ZI’s profile manager (Advanced) where customized zef. profiles (a collection of variables and handles) are provided. After creating a new subject (such as ICBM152 2023b), select the compartment(s) of interest (Shift + left click) on the subject’s dropdown menu. Right-click on any of the selected compartments and select the Generate FEM mesh option [Fig. 3]. A pop-up window will emerge requesting which method you would like to use. Select the Zeffiro option, and then decide whether you wish to use the ZI’s advanced settings.
N.B.! The order in which the compartments are selected matters, as ZI considers prioritization for its labeling routines.
BST will inquire about the mesh resolution (edge length) in [mm]. Write a simple size such as [3.0] mm and then select [OK]. Finally, you will be prompted whether to use GPU, instead of CPU, for mesh computations [Fig. 4]. If you are unsure of your hardware, select [No]. You can verify in MATLAB’s Command Window.
 |
 |
|---|---|
| Figure 3: (right click) Generate FEM mesh | Figure 4: non-advanced Zeffiro FEM mesh |
The ZI’s plugin—ZEFFIRO-Brainstorm plugin [Fig. 5]—serves as a mediator between BST and ZI. It takes control of any incoming statements until the plugin is terminated, either by closing it or after running a script. By default, the plugin sets up the Setting file zef_bst_default (.m) file with its respective toolbox path (the working directory where Zeffiro Interface is), and its Run script zef_bst_default_fem_mesh_create (.m) file. These two files are the essentials you wish to further customize.
 |
|---|
| Figure 5: Advanced Zeffiro FEM mesh |
The table below lists the UIControl objects.
| # | Name | Style Property | Description |
|---|---|---|---|
| A | ‘Use input file’ | ‘popupmenu’ | - ‘Use input file’ - ‘Ignore input file’ |
| - | |||
| - | |||
| B | ‘Settings file’ | ‘pushbutton’ | Opens file explorer |
| C | ‘Settings file’ | ‘text’ | Title of the selected file |
| D | ‘Toolbox path’ | ‘text’ | Working directory of ZI |
| E | ‘Run script’ | ‘popupmenu’ | Initial function or set of functions |
| - | |||
| F | ‘Edit project’ | ‘pushbutton’ | Launch ZI and load the Settings file |
| G | ‘Run type’ | ‘popupmenu’ | Lists the available functions at the run script bank1. - ‘Fresh start’ - ‘Import compartments’ - ‘Use project’ |
| - | |||
| H | ‘Edit settings’ | ‘pushbutton’ | Opens the Settings file in MATLAB’s Editor |
| I | ‘Create project’ | ‘pushbutton’ | Create an unsaved initial project file |
| J | ‘Run’ | ‘pushbutton’ | Execute the Run script |
When the plugin is called, it creates a preliminary structure array (zef_bst) containing the necessary variables for ZI in its own function workspace. The data in this array is updated by the contents of the Settings file to adjust the pipeline of ZI’s FEM mesh generation.
Detailed modifications can include the size of the mesh resolution (edge length), toggling (surface and volumetric) refinement, adjusting the priority of surfaces in labeling, changes in the settings, etc. Once this step is done (syntax-wise), ZI’s plugin will generate the corresponding volumetric conductivity model by executing the Run script.
Typically, the default run script file (zef_bst_default_fem_mesh_create) already provides the necessary code to create the FEM mesh and return the required output arguments to BST. Therefore, you do not need to modify this file for now.
