sidchop / reponeurovis

Reproducible and Programmatic Human Neuroimaging Visualisations

A Practical Guide for Generating Reproducible and Programmatic Neuroimaging Visualizations

Paper

Neuroimaging visualizations form the centerpiece of the interpretation and communication of scientific results, and are also a cornerstone for data quality control. Often, these images and figures are produced by manually changing settings on Graphical User Interfaces (GUIs). There now exist many well-documented code-based brain visualization tools that allow users to programmatically generate publication-ready figures directly within R, Python and MATLAB environments. Here, we provide a rationale for the wide-spread adoption of code-generated brain visualizations by highlighting corresponding advantages in replicability, flexibility, and integration over GUI based tools. We then provide a practical guide outlining the steps required to generate these code-based brain visualizations. We also present a comprehensive table of tools currently available for programmatic brain visualizations (https://sidchop.shinyapps.io/braincode_selector/) and provide didactic examples of visualizations and associated code as a point of reference. Finally, we provide a web-app (https://sidchop.shinyapps.io/braincode/) which can generate simple code-templates as starting points for these visualizations.

Full paper: A Practical Guide for Generating Reproducible and Programmatic Neuroimaging Visualizations. Chopra, Sidhant., Labache, L., Dhamala, E., Orchard, E., Holmes. A.

---

Tool finder:

To assists researchers in finding a code-based brain visualization tool, we have provided a interactive table: https://sidchop.shinyapps.io/braincode_selector/. If you think that we have missed a code-based package/library or tool box which can generate brain visualization directly within in R, python or MATLAB environments, please creating an issue on this GitHub page or leave a comment on this google sheet.

---

Template generator (R & Python):

Brain-Code: A web-app for generating code templates for brain visualizations

To assist new users transition into generating code-based brain visualizations we have developed a web-app (https://sidchop.shinyapps.io/braincode/) which allows for interactive generation of code-templates for beginner friendly libraries/packages in R and Python. In the web-app, users can select R or Python as their coding environment, and choose between voxel, ROI, vertex, and edge-level visualizations. They can then manually adjust a limited set of visualization setting, such as color-scales and view, and are provided with a reactive code-template which can be copied and then used within their respective programming environment. The provided code templates require users to customize the code, such as alter file-paths. The available settings have been purposefully limited to allow users to explore and fine-tune additional visualization options within their own programming environment. The code-template also contains links and prompts to more detailed documentation, alternate packages/libraries and tutorials which allow for more complex and publication-ready brain visualizations. If the web-app (https://sidchop.shinyapps.io/braincode/) becomes unavailable, bundled version can be downloaded and executed locally using R or Python using the following links:

• R template generator (Shiny for R app: https://figshare.com/articles/software/braincodeR_tar/23537313)
• Python template generator (Shiny for python app: https://figshare.com/articles/software/braincodePy_tar/23537319)
• Interactive tool selector (Shiny for R app: https://figshare.com/articles/software/braincode_table_selector_tar/23537316)

Note: This web-app is still being refined, so some features are a little slow and we are working on the UI. Please feel free to leave feedback by creating an issue on this GitHub page.

Interface for BrainCode web-app which generates simple code-based templates for brain visualizations. (1) Select your programming environment (R or Python). (2) Select your visualization type (Voxel, Region, Vertex and Edge). (3) Manually adjust limited visualization settings and examine how it reactively changes the visualization (4) and code template (5). (5) Copy the code template into your programming environment, change file-paths to your own data and explore other visualization settings offered by the functions.

Examples of figures made within R and Python:  

Examples of figures made in Python:

Questions

Please contact me (Sidhant Chopra) as [email protected] and/or [email protected]

reponeurovis's Issues

There is no result output after "p.build()" in "Visualise Vertex-level data"

Example code typos in web app

Hi,

Thanks for this tool!

For R code, region-level data, atlas_data = left_join(atlas,data)) has an extra ")". Also, ggplot2 needs to be imported as a library.

Best,
Steven

There is no result output after "p.build()" in "Visualise Vertex-level data"

Thank you for this nice tool! I would like to use it to plot surfaces, but I seem to have a slight problem while repeating the steps of the tutorial in "Visualise Vertex-level data".....

I ran the code on jupyter lab; There no output of figure after "p.build()", and the code is shown below:

from surfplot import Plot
from surfplot.datasets import load_example_data
from neuromaps.datasets import fetch_fslr
from brainspace.mesh.mesh_io import read_surface

surfaces = fetch_fslr()
lh, rh = surfaces['inflated']
effect = load_example_data(dataset = 'default_mode', join=True)

p = Plot(lh, rh, views=['lateral','medial','anterior', 'dorsal'], zoom=1.2)
p.add_layer(effect, cbar=True, cmap='inferno')
p.build()

Looking forward to getting your answer, thank you!

Error in `layer_brain()`: ! Problem while setting up layer. ℹ Error occurred in the 1st layer. Caused by error in `match.arg()`:

Example code for Visualise Region-level data (https://sidchop.shinyapps.io/braincodepy/) missing code

In an attempt to reproduce the below code, I found a line was missing to generate unique values in the first place. I've placed ** around it for you. Cheers

# e.g. pip install numpy brainspace surfplot neuromaps nibabel 

from surfplot import Plot
from brainspace.datasets import load_parcellation
from brainspace.mesh.mesh_io import read_surface
from neuromaps.datasets import fetch_fslr
import numpy as np

# Load the surface we want to use as the background
# Read in your own background surface {'.ply', '.vtp', '.vtk', '.fs', '.asc', '.gii'} 
surfaces = read_surface('./path/to/surface/file.gii.gz') 

# Or use one of the surface files included in the neuromaps package 
# Here we are using the 32k FsLR (a symmetric version 
# fsaverage space template with ~32k verticies in each hemisphere
surfaces = fetch_fslr()
lh, rh = surfaces['inflated']

# Next we want to load the parcellation/atlas we want to plot
# on the background surface. A parcellation is a array or surface file the same 
# length (number of vertices) as the background surface, with the same value  
# assigned to clusters of vertivies, representing discrete brain regions  
# We can either read in a surface file in FsLR space
atlas = read_surface('./path/to/surface/atlas/file.gii.gz') 

# Or use one of the surface files included in the brainspace package
atlas = load_parcellation('schaefer', 100, join = True)

# You can either plot this atlas directly, or assign new values 
# to each parcel to demonstrate an statistical effect. Here we assign a 
# random value between [0,1] to each unique parcel (excluding the medial wall [0])
**unique = np.unique(atlas)**
unique = unique[1:len(atlas)]
for i in range(unique.shape[0]):
	rd = np.random.uniform(low=0.0, high=1.0, size=1).round(3)
	atlas = np.where(atlas==unique[i], rd, atlas)

# Generate plot
p = Plot(lh, rh, views=['lateral','medial'], zoom=1.2)
p.add_layer(atlas, cbar=True, cmap='inferno')
p.build()```