Mini course 2024
This page corresponds the mini-course given at the fNIRS conference in 20224. More information here: https://fnirs2024.fnirs.org/educational-course/minicourses/minicourse-edda-cg16/
- Hardware: a basic recent laptop should be fine.
- An internet connection. A dedicated wifi connection will be available on site for the participants of the workshop.
- Operating system: Linux, windows or Mac OS. Everything should work on all systems though we recommend using Linux since more tests have been done with it.
- Disk space: the full installation with dependencies and sample data should take no more than 4Gb. Some space can be freed by cleaning the CPLEX dependency (saves ~3Gb).
- Matlab: version > R2015b is recommended.
- Before attending the workshop: Please complete the following Setup section.
If Brainstorm is already installed, update to the latest version (Menu bar: Update > Update Brainstorm).
For a new installation, Brainstorm requires a user to be registered in order to download it. This allows their development team to track their usage. Consult Brainstorm tutorial for instruction on how to download Brainstorm
For the first time it runs, brainstorm asks to specify a database folder. This will be the place where all the data imported by brainstorm will go. Create a folder named brainstorm_db in your Documents folder and specify it as your main brainstorm database. Then, the main brainstorm interface will be displayed.
No prior knowledge of brainstorm is mandatory for the current workshop session which should cover the basics. However, if one wishes to get familiar with brainstorm features, we refer to the brainstorm tutorials page.
Important for mac users: If the right-click doesn't work anywhere in the Brainstorm interface and you cannot get to see the popup menus in the database explorer, try to change the configuration of your trackpad in the system preferences and enable left-click. Alternatively, connect a standard external mouse with two buttons. Some Apple pointing devices do not interact very well with Java/Matlab.
CPLEX is a set of tools to perform functional optimization edited by IBM. It is used here to solve the integer programming problem during the optimal montage computation (last tutorial of this workshop).
For license concerns, we cannot bundle the CPLEX library within NIRSTORM. One can purchase a free copy of CPLEX if they are students or academics.
For this tutorial, download CPLEX 12.10.
To download CPLEX :
- Visit http://ibm.biz/CPLEXonAI and create an account using your institutional email
- Once you are connected; go down the page and click on software and then ILOG CPLEX Optimization Studio and click on download. A new page will open
- In the search options, select text, and write: "IBM ILOG CPLEX Optimization Studio V12.10 Multiplatform Multilingual eAssembly"
- Download "IBM ILOG CPLEX Optimization Studio V12.10 for X Multiplatform Multilingual" where X is your operating system (eg. Windows, Linux, MacOs)
- For MacOs, install CPlex.
- For Linux, and Windows, unzip the file in your Documents
Finally, add the path to the CPLEX Matlab bindings to the Matlab path: go to the "Home" tab, click "Set path" (yellow folder icon) then click on "Add with subfolders" and select the folder of the CPLEX Matlab bindings.
In Mac, this file is in your application folder.
If you cannot get a working version of CPLEX, let us know during the workshop and we'll try to help you.
Using Brainstorm plug-in system, download the following plugins :
- NIRS > NIRSTORM
- NIRS > MCXLAB-cl
- SPM12
- Inverse > Brainentropy
The total disk space required after data download and installation is ~1.3Go. The size is quite large because of the optical data that are required for the computation of the forward model. The dataset can be downloaded from: https://osf.io/md54y/?view_only=0d8ad17d1e1449b5ad36864eeb3424ed .
For the optimal montage, download Colin27 template, to do so, execute the following command in Matlab : nst_bst_set_template_anatomy('Colin27_4NIRS_Jan19', 0, 1)
** Licence ** This tutorial dataset (NIRS and MRI data) remains proprietary of the MultiFunkIm Laboratory of Dr Grova, at PERFORM centre, Concordia University, Montreal. Its use and transfer outside the Brainstorm tutorial, e.g. for research purposes, is prohibited without written consent from our group. For questions please contact Christophe Grova: christophe.grova@concordia.ca
Presentation slides linked to this tutorial can be found at: https://docs.google.com/presentation/d/1k3SkdnwnGyne6mI6J76856oKygdkcRrm/edit?usp=sharing&ouid=114007975416410855082&rtpof=true&sd=true
This process is part of the experiment planning, taking place before the acquisition, where the experimenter wants to define where to place the optode on the scalp. Usually, a NIRS montage has limited coverage over the head and hence optodes are placed specifically on top of a predefined target cortical region of interest (ROI). However, due to the non-trivial light propagation across head tissues as well as the complex cortical topology, the optode placement cannot be optimally based solely on a pure geometrical criterion.
Here, the computation of the optimal NIRS montage consists of finding the set of optode coordinates whose sensitivity to a predefined region of interest is maximized (Machado et al., 2014; Pellegrino et al., 2016).
To achieve this, this process requires:
- an anatomical MRI,
- pre-computed fluence data,
- a target ROI, either on the cortex or on the scalp.
For ease of configuration, the current tutorial relies on the Colin27 template adapted to NIRS (included in the workshop sample data). Indeed, fluence maps have already been pre-computed for this anatomy so that one can directly run the optimal montage process without going through the forward model computation. However, the most accurate results are obtained when using the subject-specific MRI. The current procedure can be straightforwardly transposed to any MRI.
Note that fluence data available in the downloaded sample data cover only the region of interest considered here. It amounts to around 1/10th of the head and data takes ~500Mb. In order not to have to download the whole head data (~6 Gb), NIRSTORM provides an on-demand fluence download system (specifically for the Colin27 template).
It will download only the fluence data required to cover the considered region if they are not already available on the local drive (in .brainstorm/defaults/nirstorm/fluence/MRI__Colin27_4NIRS).
- Create a new subject, called "Subject_OM", with the default set-up
- Go to the anatomy view, right-click on Subject_OM and select "Use template > Colin27_4NIRS_Jan19". To download the Colin27 template, to do so, execute the following command in Matlab : nst_bst_set_template_anatomy('Colin27_4NIRS_Jan19', 0, 1)
For ease of reproducibility, the ROI definition is atlas-based. For this tutorial, we will target the frontopolar gyrus. For that, we will target the region labeled "RPF G_and_S_transv_frontopol" from the Destrieux atlas. To visualise the region,
- Open the mid cortical mesh by double-clicking on it in the anatomical view of Subject_OM
- Select the scout panel and use the drop-down menu to show the Destrieux atlas
- Select the scout defining the bottom of the frontopolar gyrus, labeled "RPF G_and_S_transv_frontopol".
The optimal montage works by searching for the best possible layout of optode pairings within a given region on the head mesh (search space). Each vertex in this region is a candidate holder on which an optode (source or detector) can be placed. A montage is best if it maximizes the optical sensitivity over a pre-defined cortical region of interest.
Without any file in the process panel, click run and then NIRS > Source > Compute optimal montage. Select the subject and click on Edit. The following figure should appear :
Here are the process parameters to fill in, along with some explanation about them:
-
Cortical scout (target ROI), select Destrieux atlas and G_and_S_transv_frontopol R.
-
Search space : To avoid the explicit definition of the head region (search space), we will use the option 'use default search space' which constructs the head scout by projecting the target cortical scout onto the head mesh. Use 3 cm for the extent of scalp projection. Alternatively, note that the head scout could be given explicitly by selecting the head scout.
Montage :
-
Number of sources: 4
Maximal number of sources in the optimal montage. The actual number in the resulting montage may be lower. -
Number of detectors: 8
Maximal number of detectors in the optimal montage. The actual number in the resulting montage may be lower. -
Number of adjacent: 2
Minimal number of detectors that must be seen by any given source. -
Range of optodes distance: 20 - 40 mm
Minimal and maximal distance between two optodes (source or detector). This applies to source-source, detector-dectector, and source-detector distances. -
Minimum source detector distance: 20 mm
Minimal distance between a source and a detector.
Fluence information
-
Fluence Data Source (URL or path): enter the path to the fluences. For colin27, specify "http://thomasvincent.xyz/nst_data/fluence/" and the necessary fluences will be automatically downloaded.
-
Wavelength (nm): 685
The wavelength of the fluence to load and which will be used to compute the optical sensitivity to the target cortical ROI. Note that optimal montages vary only very slightly across wavelengths. Hence we don't need to use the two actual wavelengths used during acquisitions. This saves some computation time! -
**Segmentation label **: the label used to describe the tissues in your segmentation file. Here scalp (labeled as 1), skull (labeled as 2), CSF (labeled as 3), grey matter (labeled as 4), and white matter (labeled as 5)
Output:
-
Output condition name: Optimal_Montage_frontal
The name of the condition (output functional folder) which will contain the computed montage. -
** Folder for weight table ** : Folder to save the optical sensitivity to the target cortical ROI.
The optimal montage computations comprise the following steps with their typical execution time in brackets:
-
Mesh and anatomy loading [< 10 sec]
-
Loading of fluence files [< 1 min]
Fluence files will be first searched for in the folder .brainstorm/default/nirstorm/fluence. If not available, they will be requested from the resource specified previously (online here).
-
Computation of the weight table (summed sensitivities) [< 3 min]
For every candidate pair, the sensitivity is computed by summation of the normalized fluence products over the cortical target ROI. This is done only for pairs fulfilling the distance constraints. This step if skipped if the weight table folder is specified and a weight table was already pre-computed.
-
Linear mixed integer optimization using CPLEX [~ 5 min]
This is the main optimization procedure. It explores the search space and iteratively optimizes the combination of optode pairings while guaranteeing model constraints.
-
Output saving [< 5 sec]
Switch to the functional tab of Subject_OM.
Under the newly created folder "Optimal_Montage_frontal", double click on "NIRS-BRS channels (19)". This will display the optimal montage along with some scalp regions. Ignore these regions for now.
In the view control panel, switch the "Surface" tab, click on the "+" icon in the top right and select "cortex". This will show the cortical mesh with the target frontopolar ROI for which the montage was optimized:
In order to use the optode coordinates in a neuronavigation, they can be exported as a CSV file.
Right-click on "NIRS-BRS channels (19)", select "File > Export to File" then for "Files of Type:" select "NIRS: Brainsight (*.txt)". Go to the folder Documents\Nirstorm_workshop_PERFORM_2020 and enter filename "optimal_montage_frontal.txt".
Here is the content of the exported coordinate file, whose format can directly be used with the Brainsight neuronavigation system:
# Version: 5
# Coordinate system: NIftI-Aligned
# Created by: Brainstorm (nirstorm plugin)
# units: millimetres, degrees, milliseconds, and microvolts
# Encoding: UTF-8
# Notes: Each column is delimited by a tab. Each value within a column is delimited by a semicolon.
# Sample Name Index Loc. X Loc. Y Loc. Z Offset
S1 1 61.801026 53.794879 20.827570 0.0
S2 2 58.614179 65.147586 -12.996690 0.0
S3 3 18.340509 84.492701 3.992621 0.0
S4 4 0.721182 85.338992 16.268421 0.0
D1 5 52.653816 67.712105 8.169515 0.0
D2 6 36.819009 72.131463 32.357219 0.0
D3 7 35.263908 77.335821 12.195818 0.0
D4 8 30.828533 79.924480 -26.315089 0.0
D5 9 43.354290 77.996386 -9.680977 0.0
D6 10 8.060217 87.471897 -13.272658 0.0
D7 11 -17.384161 84.440003 4.209488 0.0
D8 12 14.779627 78.451950 37.003541 0.0
Boas D, Culver J, Stott J, Dunn A. Three dimensional Monte Carlo code for photon migration through complex heterogeneous media including the adult human head. Opt Express. 2002 Feb 11;10(3):159-70 pubmed
Boas D.A., Dale A.M., Franceschini M.A. Diffuse optical imaging of brain activation: approaches to optimizing image sensitivity, resolution, and accuracy. NeuroImage. 2004. Academic Press. pp. S275-S288 pubmed
Hansen C. and O’Leary DP., The Use of the L-Curve in the Regularization of Discrete Ill-Posed Problems. SIAM J. Sci. Comput., 14(6), 1487–1503 SIAM
Arridge SR, Methods in diffuse optical imaging. Philos Trans A Math Phys Eng Sci. 2011 Nov 28;369(1955):4558-76 pubmed
Amblard C,, Lapalme E. and Jean-Marc Lina JM, Biomagnetic source detection by maximum entropy and graphical models. IEEE Trans Biomed Eng. 2004 Mar;51(3):427-42 pubmed
Grova, C. and Makni, S. and Flandin, G. and Ciuciu, P. and Gotman, J. and Poline, JB. Anatomically informed interpolation of fMRI data on the cortical surface Neuroimage. 2006 Jul 15;31(4):1475-86. Epub 2006 May 2. pubmed
Chowdhury RA, Lina JM, Kobayashi E, Grova C., MEG source localization of spatially extended generators of epileptic activity: comparing entropic and hierarchical bayesian approaches. PLoS One. 2013;8(2):e55969. doi: 10.1371/journal.pone.0055969. Epub 2013 Feb 13. pubmed
Machado A, Marcotte O, Lina JM, Kobayashi E, Grova C., Optimal optode montage on electroencephalography/functional near-infrared spectroscopy caps dedicated to study epileptic discharges. J Biomed Opt. 2014 Feb;19(2):026010 pubmed
Pellegrino G, Machado A, von Ellenrieder N, Watanabe S, Hall JA, Lina JM, Kobayashi E, Grova C., Hemodynamic Response to Interictal Epileptiform Discharges Addressed by Personalized EEG-fNIRS Recordings Front Neurosci. 2016 Mar 22;10:102. pubmed
Fang Q. and Boas DA., Monte Carlo simulation of photon migration in 3D turbid media accelerated by graphics processing units, Opt. Express 17, 20178-20190 (2009) pubmed