vertex-wise plotting from 3D volumes¶

in this tutorial, you will see how to use yabplot to project a continuous 3D volume onto a cortical surface and visualize it vertex-wise.

why project to the surface? lets say you have statistical maps from voxel-wise analysis that are in 3D volumes (nifti files), but you want to visualize them on the folded cortex.

inputs and outputs¶

we start with:

1. data volume (.nii.gz): the 3D NIfTI file where each voxel contains continuous scalar data (e.g., an fMRI task activation map, t-statistics, or p-values).
2. (optional) standard brain mesh (.surf.gii): the background brain meshes to project the data onto. it is optional as we can simply fetch for instance the 'midthickness' brain mesh, but you can also supply your own custom mesh (e.g., fsaverage).

we need to generate:

1. vertex arrays (numpy.ndarray): 1D arrays of data sampled exactly at the surface vertices (using project_vol2surf).
2. pyvista meshes (pv.PolyData): custom 3D mesh objects that bind the geometry and the data together (using load_vertexwise_mesh), ready to be passed to plot_vertexwise which results in a nice vertex-wise plot.

In [ ]:

import pooch
from yabplot.data import get_surface_paths
from yabplot.utils import project_vol2surf, load_vertexwise_mesh
from yabplot.plotting import plot_vertexwise

# fetch an example 3D volume data from neurovault
nv_url = "http://neurovault.org/media/images/4874/MNI152_EB_01.nii.gz"
nii_path = pooch.retrieve(url=nv_url, known_hash=None, path=pooch.os_cache("yabplot"), 
                          fname="sample_task_map.nii.gz")

# load the standard brain mesh paths
b_lh_path, b_rh_path = get_surface_paths('midthickness', 'bmesh')

# project 3d volume to 1d surface arrays
lh_data, rh_data = project_vol2surf(nii_path, bmesh_type='midthickness')

# make vertex-wise brain meshes with the injected data
lh_mesh, rh_mesh = load_vertexwise_mesh(b_lh_path, b_rh_path, lh_data, rh_data)

# plot
plot_vertexwise(lh_mesh, rh_mesh, cmap='coolwarm')

import pooch from yabplot.data import get_surface_paths from yabplot.utils import project_vol2surf, load_vertexwise_mesh from yabplot.plotting import plot_vertexwise # fetch an example 3D volume data from neurovault nv_url = "http://neurovault.org/media/images/4874/MNI152_EB_01.nii.gz" nii_path = pooch.retrieve(url=nv_url, known_hash=None, path=pooch.os_cache("yabplot"), fname="sample_task_map.nii.gz") # load the standard brain mesh paths b_lh_path, b_rh_path = get_surface_paths('midthickness', 'bmesh') # project 3d volume to 1d surface arrays lh_data, rh_data = project_vol2surf(nii_path, bmesh_type='midthickness') # make vertex-wise brain meshes with the injected data lh_mesh, rh_mesh = load_vertexwise_mesh(b_lh_path, b_rh_path, lh_data, rh_data) # plot plot_vertexwise(lh_mesh, rh_mesh, cmap='coolwarm')

In [13]:

# plotting parameters are largely the same as in plot_cortical
plot_vertexwise(lh_mesh, rh_mesh, cmap='Reds', vminmax=[0, 10])

# plotting parameters are largely the same as in plot_cortical plot_vertexwise(lh_mesh, rh_mesh, cmap='Reds', vminmax=[0, 10])