Neuromaps plugin
Authors: Le Thuy Duong Nguyen, Raymundo Cassani, Jason da Silva Castanheira
Please note that this tutorial page is currently under construction.
The neuromaps plugin for Brainstorm (bst-neuromaps) integrates curated brain annotations (also referred to as brain maps) and tools to further expand the accessibility and inclusivity of brain-mapping tools, as part of an Open Science initiative. We extend these pioneering tools to the Brainstorm environment for users without any prior computer programming experience, providing an intuitive graphic user interface. This approach eliminates barriers of entry for researchers, fostering a more inclusive research community.
The present tutorial will demonstrate the plugin’s functionality within the Brainstorm interface; for a detailed breakdown of the algorithm, please refer to the neuromaps plugin GitHub.
Contents
Introduction
neuromaps is a Python toolbox designed for assessing, transforming, and analyzing structural and functional brain annotations (Markello, Hansen et al., 2022). It marks a significant stride towards integrative analytics in multimodal, multiscale neuroscience by bridging the gap between various neuroimaging modalities and proposing analytical tools to establish connections among different brain features. The toolbox comprises a curated repository of brain annotations in their native space, methods for generating transformations across multiple coordinate systems, and offers a systematic workflow for comprehensive structural and functional annotation enrichment analysis of the human brain.
With the bst-neuromaps plugin we aim to bring annotations from the neuromaps toolbox in to Brainstorm, and provide additional methods for their analysis. The plugin takes advantage of the Brainstorm GUI to enhance accessibility, especially for researchers who may not be familiar with command-line interfaces or programming languages such as Python.
For the first iteration of the implementation of the bst-neuromaps plugin, we focused on the neurotransmitter receptors and transporters. Twenty-six different annotations from the neuromaps toolbox were selected, covering nine different neurotransmitter systems: acetylcholine, cannabinoid, dopamine, GABA, glutamate, histamine, norepinephrine, opioid, and serotonin. These brain annotations are sourced from open-access repositories, addressing the need for a comprehensive tool that integrates standardized analytic workflows for neuroimaging data.
Key features
Flexible framework designed to accommodate future expansions and updates.
Repository of precomputed annotations sourced from the published literature, ensuring accessibility and ease of use.
All the information for these maps, including the appropriate citations to use can be found in this spreadsheet.
In neuromaps Python, the surface annotations are obtained by transforming the the original (volume) annotations offered in MNI152 space to the FsAverage cortical surface using the registration fusion framework proposed in neuromaps (Buckner et al., 2011; Wu et al., 2018).
Correlation processes featuring spatially informed null models that account for spatial autocorrelation.
Install
Being a Brainstorm plugin, the bst-neuromaps plugin can be installed, updated and removed directly from the Brainstorm GUI. For further information, see the plugins tutorial.
From the main window go to Plugins > Anatomy > neuromaps > Install.
A message will appear saying, "Plugin neuromaps is not installed on your computer. Download the latest version of Neuromaps now?" click 'Yes'.
- The plugin will be downloaded and installed automatically. Once installed, you will see a confirmation message.
The README file will appear; after thoroughly reviewing it, click on the "I agree" button to confirm your acceptance of the plugin's terms and conditions.
By following these steps, you will successfully install the bst-neuromaps plugin.
Importing brain annotations
Click on the [Run] button at the bottom-left corner of the Process1 tab.
When the Pipeline editor window appears, click on the first button in the toolbar under 'Process selection'
. It will show you a list of processes. Go to Sources > Fetch brain annotations from neuromaps.
The brain annotations will be listed right under, in the name format
[neurotransmitter]:[subtype]_[tracer]_[source]_[size]_[age]
for example:
Dopamine: D1_sch23390_kaller2017_N13_Age33'Select all the maps you want to import and click Run.
In the bst-neuromaps plugin, the surface annotations are projected from the FsAverage cortex to the MNI ICBM152 cortex with 15,002 vertices, which is the recommended default anatomy in Brainstorm.
Visualizing brain annotations
Once you have fetched the brain annotations, a new subject neuromaps which uses the default Brainstorm anatomy MNI ICBM152 anatomy will appear in the Brainstorm database. Note that the surface annotations are distributed for the cortical surface with 15,002 vertices.
All the imported brain annotations will be visible in the Functional data in the neuromaps subject. Brain annotation are grouped in folders according to the neurotransmitter.
To visualize the surface annotations, you can either double-click on the file or right-click > Cortical activations > Display on cortex.
- You can double-click the color bar at the bottom right of the resulting window to better visualize the annotations (this resets the values to default).
Visualization capabilities
Implementing neuromaps directly into Brainstorm further enhances the overall user experience by providing greater flexibility and control over the visualization and analysis of brain annotations. Brainstorm's advanced functionalities allow users to effortlessly rotate the brain annotations, zoom in and out, reposition them, obtain the coordinates for any point, take snapshots, adjust the transparency, and more.
The ‘Surface’ tab of the Brainstorm window contains buttons and sliders to control the display of these surfaces. Additional relevant functionalities, as outlined in Tutorial 3: Display the Anatomy, include:
Smooth: Inflates the surface to make all the parts of the cortex envelope visible.This is just a display option, it does not actually modify the surface.
Resect: The sliders and the buttons Left/Right/Struct at the bottom of the panel allow you to cut the surface or reorganize the anatomical structures in various ways.
Edge: Display the faces of the surface tesselation.
Colormap
The default colormap upon opening the brain annotation is royal_gramma, but you have the option to set it to other sequential, diverging, or rainbow colormaps. Simply right-click on the brain annotation window, navigate to Colormap: Sources > Colormap.
If you modify a colormap, the changes will be applied to all the figures, saved in your user preferences and available the next time you start Brainstorm. If you wish to undo the changes and reset the colormap to its default values, click on Restore defaults or double-click on the color bar.
You also have the opportunity to customize the brightness, contrast, and decide the color mapping, among other settings. For a comprehensive list of available options with detailed instructions, please refer to Tutorial 18: Colormaps.
Creating weighted-averaged brain annotations
Neurotransmitter annotations that have the same tracer (e.g., Serotonin: 5-HT1b_p943_gallezot2010_N23_Age29 and Serotonin: 5-HT1b_p943_savli2012_N23_Age29 have the same p943 tracer) can be combined to obtain a larger sample size for your analysis. To accomplish this, you can perform a weighted average. In the same way you selected the fetching process:
- Drag-and-drop all the relevant brain annotation files into the processing pipeline (Process1). In this example, we will select the two 5-HT1b files mentioned.
Click on the [Run] button at the bottom-left corner of the Process1 tab.
Once the Pipeline editor window appears, click on the first button in the toolbar under 'Process selection'
. Select the process Average > Average files.
Under 'Group files,' select Everything and for 'Function,' Arithmetic average: mean(x).
- Check the 'Weighted average' box, as shown below.
Click Run. A new file WAvg: 2 files will be added under the same neurotransmitter folder.
To visualize this new weighted-averaged annotation, follow the same steps as with any brain annotation. Either double-click on the file or right-click > Cortical activations > Display on cortex.
By default, the new weighted-averaged file is named WAvg: followed by the number of files averaged. If you wish to rename this or any other file to provide more informative labels for your analysis, follow these steps:
- Click once on the file to select it.
- With a right-click (or pressing F2), you will enter renaming mode and the file name will become editable.
- Type in the new desired name for the file.
- Press the "Enter" key on your keyboard or click outside the file name to save the new name.
Alternatively, you can right-click > File > Rename.
Parcellations
Parcellations are know as Scouts in the Brainstorm jargon. Please refer to Tutorial 23: Scouts for a more in-depth guide in creating, manipulating, and analyzing scouts for effective exploration and comparison of brain activity across different experimental conditions and regions of interest. The figure below shows the left and top views of the brain annotation Dopamine: D1_sch23390_kaller2017_N13_Age33 without and with different cortical parcellations. Only the borders of the Scouts are shown to avoid distorting the underlying color.
So far our annotations have a value for each vertex on the cortical surface. However, it is common to summarize the these values using Scouts. To do so it is possible to use the Extract > Scout time series as
The result is a matrix file (
) with one value for Scout.
Spatial correlation
One of the main advantages of having these brain annotations in a common coordinate system is that we can statistically compare (with spatial correlation) their spatial topographies. However, most statistical analyses (e.g., Pearson correlation) assume that the values of observations in each sample are independent of one another. Spatial autocorrelation violates this assumption because samples taken from nearby areas are related to each other and are not independent. Spatially-naive null models, both parametric and non-parametric, yield inflated p-values and are inappropriate for significance testing of neuroimaging brain maps. When applied to spatially-autocorrelated brain maps typical of most neuroimaging data, these models approach a false positive rate higher than 75% and their usage in the field is discouraged (Markello, R. D., & Misic, B., 2021). We therefore use spatially informed null models to benchmark the statistical unexpectedness of specific features of interest.
Spin test
Building on previous studies that assess the accuracy and computational efficiency of these models, we have selected the non-parametric method as the default for surface data and implemented the most widely adopted of these approaches, which involves randomizing the anatomical alignment between two cortical surface maps through spherical rotation by a random angle. This method is also know as spin-test, where each "spin" is a randomized rotation between the cortical maps (Alexander-Bloch et al., 2018).
According to the literature, null models converge quickly, reaching stable statistical estimates after approximately 100–500 nulls (Markello, R. D., & Misic, B. 2021). Researchers can use this information to balance accuracy and computational feasibility when determining the number of nulls for their analysis. Our recommendation is to generate 1000 nulls to establish a reliable null distribution of correlation coefficients and to estimate the two-tailed p-value for the original correlation between the pair of maps.
A spatial null model is enabled by default to encourage their broader adoption but users can easily revert to an uncorrected correlation by setting the number of spins (nulls) to zero.
Time-defined spatial correlation
Spatial correlation is performed between two brain maps, A and B, which can be time-defined, i.e., comprise more than one time sample. In the case of brain annotations, they consist of only-one time sample. However, this is necessarily the case of the brain activity maps (source maps). Thus, when performing spatial correlations, depending on the number of time samples in maps A and B there are three possible scenarios:
Map A: 1 time sample × Map B: 1 time sample (e.g., brain annotation)
This gives as result one value that is the correlation between the maps
Map A: N time samples × Map B: 1 time sample (e.g., brain annotation)
- This gives as result N correlation values, one for each correlation between the N time samples in map A and the 1 time sample in map B.
Map A: N time samples × Map B: N time samples
This gives as result N correlation values, one for each correlation between the i time sample in map A and the i time sample in map B. Thus, it is possible to visualize the evolution of the similarities between source maps.
💡 For the scenarios with more than one time sample, while spatial autocorrelation is handled with the spin test for each time point, temporal autocorrelation is not corrected.
Examples
The examples provided in this section to demonstrate the use of the bst-neuromaps plugins are based on the based on the sources estimations obtained with the introduction dataset, and can be followed by completing all steps of the Brainstorm Get-started tutorials up to and including tutorial 22: Source estimation.
Spatial correlation between brain annotations
This examples show how to perform the spatial correlation between annotation maps, using the spin test to estimate the p-value of the correlation. Here we use only 50 for sake of computation time, as each spin can take few seconds.
Once brain annotations have been fetches into Brainstorm as mentioned in the importing brain annotations section above.
Drag-and-drop one brain annotation in the Process1 tab, e.g.:
Acetylcholine: VaCht_feobv_aghourian2017_N18_Age67
Select process: Sources > Spatial correlation:
Brain annotations from neuromaps: Select another annotation, e.g.:
Acetylcholine: VaCht_feobv_bedard2019_N5_Age68
Comparison metric: Pearson corr
Type of correlation to be computedIgnore zeros when computing correlation: Check
Vertices with value 0 will not be considered in the correlation.Number of spins for spin test: Set to 0
- Click on Run
The process will return one statistic matrix file () named Brain map corr, it contains the correlation value between the maps Acetylcholine: VaCht_feobv_aghourian2017_N18_Age67 and Acetylcholine: VaCht_feobv_bedard2019_N5_Age68.
* Right-click on the result file, and select File > View file contents. The window that is opened shows correlation value (field tmap) and its associated p-value (field pmap).
Spatial correlation with brain annotations
Now, let's compute the spatial correlation between an time average source map and all the available brain annotations. For sake of time, the spin-test is not performed.
Drag-and-drop the cortical sources estimation for the average deviant trials in Run01 in the Process1 tab and click the [Process sources] button.
Select the process: Average > Average time:
Use absolute values: Uncheck
Time window: Check "All file"
Function: Arithmetic average
Overwrite input files: Uncheck
Select process: Sources > Spatial correlation:
Brain annotations from neuromaps: Select all (Ctr+A)
List of brain annotations that will be correlated with the source file.Comparison metric: Pearson corr
Type of correlation to be computedIgnore zeros when computing correlation: Check
Vertices with value 0 will not be considered in the correlation. [TODO] Why?Number of spins for spin test: Set to 0
- Click on Run
If the requested brain annotations were not fetched yet. This process first fetches the brain annotations, and then performs the requested spatial correlation. The process will return one statistic matrix file () named Brain map corr for each of the source files to process. Right-click on the outcome file and select Display as table to see the correlation values between the source file and each of the brain annotations. Since there was no spin test, the correlation values are uncorrected.
Spatial correlation between source maps
Click on the Process 2 tab
Drag-and-drop the cortical sources estimation for the average deviant trials in Run01 in FilesA side
Drag-and-drop the cortical sources estimation for the average standard trials in Run01 in FilesB side and click the [Process sources] button.
Select process: Sources > Spatial correlation AxB:
Comparison metric: Pearson corr
Type of correlation to be computedIgnore zeros when computing correlation: Check
Vertices with value 0 will not be considered in the correlation. [TODO] Why?Number of spins for spin test: Set to 0
- Click on Run
The process will return one statistic matrix file () named Brain map corr_02, it contains the AxB correlation value for each time sample in files. Double-click the resulting file to open it as a time series. Both source files are the average of different auditory stimuli, however, we can notice that the larger correlation value is obtained around 100 ms which corresponds to the bilateral auditory response in both conditions.
On the hard drive
The resulting file is an matrix statistic file (), as such follows the same organization as described in here.
Right click on the stat matrix file that results from running spatial correlations > File > View file contents.
Description of the fields
pmap: [Nsignals x Ntime]: p-values for all the time points. If a spin test was performed these are the spin-test corrected p-values.
tmap: [Nsignals x Ntime]: values for correlation.
Correction: Correction for multiple comparison already applied ('no', 'cluster', 'fdr', ...)
Type: Type of the data ('matrix').
Comment: String displayed in the database explorer to represent the file.
Time: Time vector associated with the results.
Description: Each of the Comments for the files what where correlated.
History: Indicates the process and input file that gave origin to this stat matrix file.
Options: Specific fields for spatial correlation:
Maps: File names for the brain annotations
nSpins: Number of spins for the spin test. If 0 there was not spin test.
rSpinTest: [Nmaps x Ntime x Nspin] Correlation values for each of the spins for the spin test.
pNoSpinTest: [Nmaps x Ntime] p-values for no spin test.
Useful functions
process_np_fetch_maps*: Imports brain annotations into a "Neuromaps" Subject
process_np_source_corr1*: Spatial correlation between surface source maps and brain annotations
process_np_source_corr2*: Computes the spatial correlation between two sets of surface source maps
process_extract_pthresh: Mask the correlation values according to a significance level. It also applies correction for multiple comparisons.
* These processes are part of the bst-neuromaps plugin.
Applications for integrative research
The bst-neuromaps plugin opens up new and exciting avenues for research and can help address questions that depend crucially on anatomical localization. Below, we explore some potential uses of the plugin in advancing integrative research, supported by examples from the literature.
Annotating structural connectomes
Hansen, J. Y., Shafiei, G., Voigt, K., Liang, E. X., Cox, S. M., Leyton, M., ... & Misic, B. (2023). Integrating multimodal and multiscale connectivity blueprints of the human cerebral cortex in health and disease. Plos Biology, 21(9), e3002314.
- With the advancements in neuroimaging techniques, which enables the simultaneous exploration of diverse interregional relationships across spatial and temporal scales, neuromaps emerge as an invaluable tool for advancing integrative research in connectomics. The researchers noted a consistent primacy of molecular connectivity modes, demonstrating the mapping of correlated receptor similarity onto multiple phenomena. The use of neuromaps revealed both the similar and complementary ways in which connectivity modes reflect cortical geometry, structure, and disease and assisted in constructing a multimodal wiring map.
Identification of specific neurochemical targets for potential future clinical treatments
da Silva Castanheira, J., Wiesman, A. I., Hansen, J. Y., Misic, B., Baillet, S., Network Quebec Parkinson, & PREVENT-AD Research Group. (2023). Neurophysiological brain-fingerprints of motor and cognitive decline in Parkinson’s disease. eBioMedicine, Volume 105, 105201.
- Subject-level data can be contextualized against the brain annotations contained in the plugin to produce a subject-specific ‘fingerprint’ of how individuals express different structural and functional brain phenotypes. The authors were able to show the topographical alignment between spectral brain-fingerprints, the functional hierarchy of cortex, and neurotransmitter systems.
Wiesman, A. I., da Silva Castanheira, J., Degroot, C., Fon, E. A., Baillet, S., Network, Q. P., & Prevent-Ad Research Group. (2023). Adverse and compensatory neurophysiological slowing in Parkinson’s disease. Progress in Neurobiology, 231, 102538.
- Neuromaps has the potential to enhance the integration of neurophysiological and neurochemical data for a more comprehensive understanding of brain function, and assist in the identification of specific neurochemical targets for potential future clinical treatments. The authors demonstrated, for instance, that the clinical relationships of neurophysiological slowing in patients with Parkinson's disease are aligned topographically with the densities of selective neurotransmitter systems and the organization of sensory-association areas—namely, dopamine, serotonin, GABA, and norepinephrine systems.
Acknowledgements
The conception of the original neuromaps algorithm is due to Ross D. Markello, Justine Y. Hansen, Zhen-Qi Liu, Vincent Bazinet, Golia Shafiei, Laura E. Suárez, Nadia Blostein, Jakob Seidlitz, Sylvain Baillet, Theodore D. Satterthwaite, M. Mallar Chakravarty, Armin Raznahan & Bratislav Misic. The appropriate citation for neuromaps is as follows:
Markello, R.D., Hansen, J.Y., Liu, ZQ. et al. neuromaps: structural and functional interpretation of brain maps. Nat Methods 19, 1472–1479 (2022).
If you used any of the included maps, please also cite the original papers that publish the data. References for each map can be found in this spreadsheet.
- If you used the surface maps which were transformed using the registration fusion framework, please also cite:
Wu, J. et al. Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate systems. Hum. Brain Mapp. 39, 3793–3808 (2018).
Contributing
We welcome contributions from the community to help improve and expand the functionality of the Neuromaps plugin. Feel free to submit pull requests on the GitHub repository, report issues, or provide suggestions below! Your feedback is invaluable in ensuring a user-friendly experience for researchers worldwide. We believe that open science is most impactful when the countless everyone is provided with equal access to the newest and greatest resources in the field.