Note
Go to the end to download the full example code
Accessing brain reference templates
Other than a reference space, which is only a semantic entity, a reference template is a spatial object representing the brain volume in the form of a 3D image or 3D surface mesh. Since each reference template is uniquely linked to one particular brain reference space, we access templates by the get_template() method of Space objects.
In siibra, reference templates are Volume objects. Volumes allow fetching volumetric data from different types of “volume providers” through their fetch() method.
It is important to note that the same volume (such as the BigBrain 3D model) can be provided through different resources and formats, which represent it as an image or surface mesh, each possibly through multiple formats. Therefore, a Volume object can have multiple volume providers, which are selected depending on the parameters passed to fetch(). This example will show some typical settings.
import siibra
from nilearn import plotting
We choose the ICBM 2009c on linear asymmetric space, and then request the template siibra linked to it. As expected, the template is an object of type Volume.
icbm_tpl = siibra.spaces.get('icbm 2009c nonl asym').get_template()
icbm_tpl
<Volume(space_spec={'@id': 'minds/core/referencespace/v1.0.0/dafcffc5-4826-4bf1-8ff6-46b8a31ff8e2'}, name='MNI 152 ICBM 2009c Nonlinear Asymmetric', providers={'neuroglancer/precomputed': <siibra.volumes.providers.neuroglancer.NeuroglancerProvider object at 0x7f72b2b65f10>, 'neuroglancer/precompmesh/surface': <siibra.volumes.providers.neuroglancer.NeuroglancerSurfaceMesh object at 0x7f72b2b65df0>, 'zip/nii': <siibra.volumes.providers.nifti.ZipContainedNiftiProvider object at 0x7f72b2ae3340>})>
We can now fetch data from the template. By default (and if available), this gives us a 3D image in the form of a Nifti1Image object as defined and supported by the commonly used nibabel library.
<class 'nibabel.nifti1.Nifti1Image'>
We can display this template with common neuroimaging visualization tools. Here we use the plotting tools provided by nilearn
plotting.view_img(icbm_img, bg_img=None, cmap='gray', colorbar=False)
/opt/hostedtoolcache/Python/3.8.18/x64/lib/python3.8/site-packages/nilearn/plotting/html_stat_map.py:112: UserWarning: Threshold given was 1e-06, but the data has no values below -0.0126495361328125.
warnings.warn(
As described above however, the template has multiple volume providers, representing different resources and formats. The Volume object has a list of accepted format specifiers:
icbm_tpl.formats
{'zip/nii', 'neuroglancer/precomputed', 'neuroglancer/precompmesh/surface'}
Although the particular source format is usually not of interest to us, we want to distinguish image and mesh representations of course. We can use the format parameter of fetch() to specify “mesh” or “image”, or to fetch from a concrete resource format. Meshes are provided as a dictionary with an Nx3 array of N vertices, and an Mx3 array of M triangles defined from the vertices. we can pre-check wether a volume provides image or mesh data explicitly using provides_mesh and provides_image
<class 'dict'>
We can likewise visualize the mesh using plotting functions of nilearn