netneurotools.datasets.fetch_civet_curated

netneurotools.datasets.fetch_civet_curated(version='civet41k', force=False, data_dir=None, verbose=1)

Download files for CIVET template.

This dataset contains surface geometry files (white, midthickness, inflated, veryinflated, sphere), medial wall labels, and surface shape files (sulcal depth and vertex area) in GIFTI format for the CIVET template at multiple densities.

If you used this data, please cite 1, 2, 3, 4.

Parameters:

version ({‘civet41k’, ‘civet164k’}, optional) – Which density of the CIVET-space geometry files to fetch.

Returns:

filenames – Dictionary-like object with keys [‘white’, ‘midthickness’, ‘inflated’, ‘veryinflated’, ‘sphere’, ‘medial’, ‘sulc’, ‘vaavg’], where corresponding values are Surface namedtuples containing filepaths for the left (L) and right (R) hemisphere files in GIFTI format.

Return type:

sklearn.utils.Bunch

Other Parameters:

• force (bool, optional) – If True, will overwrite existing dataset. Default: False

• data_dir (str, optional) – Path to use as data directory. If not specified, will check for environmental variable ‘NNT_DATA’; if that is not set, will use ~/nnt-data instead. Default: None

• verbose (int, optional) – Modifies verbosity of download, where higher numbers mean more updates. Default: 1

Notes

This function fetches curated CIVET surfaces from the neuromaps package (see neuromaps.datasets.fetch_civet). All files are provided in GIFTI format (.gii). The CIVET template is registered to ICBM152 stereotaxic space.

The returned files include:

• white: White matter surface geometry (.surf.gii), representing the boundary between white matter and gray matter.

• midthickness: Midthickness surface geometry (.surf.gii), halfway between white and pial surfaces.

• inflated: Inflated surface geometry (.surf.gii) for improved visualization of sulci and gyri.

• veryinflated: Very inflated surface geometry (.surf.gii) providing additional smoothing for visualization.

• sphere: Spherical surface geometry (.surf.gii) used for surface-based registration and applying parcellations.

• medial: Medial wall mask (.label.gii) indicating vertices to exclude from analyses (vertices with no cortex).

• sulc: Sulcal depth map (.shape.gii) providing sulcal/gyral patterns on the midthickness surface.

• vaavg: Vertex area map (.shape.gii) representing the average vertex area on the midthickness surface.

The vertex density varies by version: civet41k (≈41k vertices) and civet164k (≈164k) per hemisphere.

Example directory tree:

~/nnt-data/tpl-civet_curated
└── v2
    ├── civet164k
    │   ├── tpl-civet_den-164k_hemi-L_desc-nomedialwall_dparc.label.gii
    │   ├── tpl-civet_den-164k_hemi-L_desc-sulc_midthickness.shape.gii
    │   ├── tpl-civet_den-164k_hemi-L_desc-vaavg_midthickness.shape.gii
    │   ├── tpl-civet_den-164k_hemi-L_inflated.surf.gii
    │   ├── tpl-civet_den-164k_hemi-L_midthickness.surf.gii
    │   ├── tpl-civet_den-164k_hemi-L_sphere.surf.gii
    │   ├── tpl-civet_den-164k_hemi-L_veryinflated.surf.gii
    │   ├── tpl-civet_den-164k_hemi-L_white.surf.gii
    │   ├── tpl-civet_den-164k_hemi-R_desc-nomedialwall_dparc.label.gii
    │   ├── tpl-civet_den-164k_hemi-R_desc-sulc_midthickness.shape.gii
    │   ├── tpl-civet_den-164k_hemi-R_desc-vaavg_midthickness.shape.gii
    │   ├── tpl-civet_den-164k_hemi-R_inflated.surf.gii
    │   ├── tpl-civet_den-164k_hemi-R_midthickness.surf.gii
    │   ├── tpl-civet_den-164k_hemi-R_sphere.surf.gii
    │   ├── tpl-civet_den-164k_hemi-R_veryinflated.surf.gii
    │   ├── tpl-civet_den-164k_hemi-R_white.surf.gii
    │   ├── tpl-civet_space-fsaverage_den-164k_hemi-L_sphere.surf.gii
    │   ├── tpl-civet_space-fsaverage_den-164k_hemi-R_sphere.surf.gii
    │   ├── tpl-civet_space-fsLR_den-164k_hemi-L_sphere.surf.gii
    │   └── tpl-civet_space-fsLR_den-164k_hemi-R_sphere.surf.gii
    └── civet41k
        ├── README.md
        ├── tpl-civet_den-41k_hemi-L_desc-nomedialwall_dparc.label.gii
        ├── tpl-civet_den-41k_hemi-L_desc-sulc_midthickness.shape.gii
        ├── tpl-civet_den-41k_hemi-L_desc-vaavg_midthickness.shape.gii
        ├── tpl-civet_den-41k_hemi-L_inflated.surf.gii
        ├── tpl-civet_den-41k_hemi-L_midthickness.surf.gii
        ├── tpl-civet_den-41k_hemi-L_sphere.surf.gii
        ├── tpl-civet_den-41k_hemi-L_veryinflated.surf.gii
        ├── tpl-civet_den-41k_hemi-L_white.surf.gii
        ├── tpl-civet_den-41k_hemi-R_desc-nomedialwall_dparc.label.gii
        ├── tpl-civet_den-41k_hemi-R_desc-sulc_midthickness.shape.gii
        ├── tpl-civet_den-41k_hemi-R_desc-vaavg_midthickness.shape.gii
        ├── tpl-civet_den-41k_hemi-R_inflated.surf.gii
        ├── tpl-civet_den-41k_hemi-R_midthickness.surf.gii
        ├── tpl-civet_den-41k_hemi-R_sphere.surf.gii
        ├── tpl-civet_den-41k_hemi-R_veryinflated.surf.gii
        ├── tpl-civet_den-41k_hemi-R_white.surf.gii
        ├── tpl-civet_space-fsaverage_den-41k_hemi-L_sphere.surf.gii
        ├── tpl-civet_space-fsaverage_den-41k_hemi-R_sphere.surf.gii
        ├── tpl-civet_space-fsLR_den-41k_hemi-L_sphere.surf.gii
        └── tpl-civet_space-fsLR_den-41k_hemi-R_sphere.surf.gii

3 directories, 41 files

License: https://github.com/aces/CIVET_Full_Project/blob/master/LICENSE

Examples

Load the CIVET curated template surfaces:

>>> surfaces = fetch_civet_curated(version='civet41k')
>>> surfaces.keys()
dict_keys([
    'white', 'midthickness', 'inflated', 'veryinflated',
    'sphere', 'medial', 'sulc', 'vaavg'
])

Access the midthickness surface GIFTI files:

>>> surfaces.midthickness
Surface(L=PosixPath('~/nnt-data/tpl-civet_curated/v2/civet41k/tpl-civet_den-41k_hemi-L_midthickness.surf.gii'),
        R=PosixPath('~/nnt-data/tpl-civet_curated/v2/civet41k/tpl-civet_den-41k_hemi-R_midthickness.surf.gii'))

Load the left midthickness surface with nibabel:

>>> import nibabel as nib
>>> gii = nib.load(surfaces.midthickness.L)
>>> vertices = gii.agg_data('pointset')
>>> faces = gii.agg_data('triangle')
>>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}")
Vertices: (40962, 3), Faces: (81920, 3)

Load and examine the sulcal depth data:

>>> sulc_left = nib.load(surfaces.sulc.L)
>>> sulc_data = sulc_left.agg_data()
>>> float(sulc_data.min()), float(sulc_data.max())
(-27.601072311401367, 20.54990005493164)

References

[1]

Oliver Lyttelton, Maxime Boucher, Steven Robbins, and Alan Evans. An unbiased iterative group registration template for cortical surface analysis. Neuroimage, 34(4):1535–1544, 2007.

[2]

Vladimir S Fonov, Alan C Evans, Robert C McKinstry, C Robert Almli, and DL Collins. Unbiased nonlinear average age-appropriate brain templates from birth to adulthood. NeuroImage, 47:S102, 2009.

[3]

Y Ad-Dab’bagh, O Lyttelton, J Muehlboeck, C Lepage, D Einarson, K Mok, O Ivanov, R Vincent, J Lerch, and E Fombonne. The civet image-processing environment: a fully automated comprehensive pipeline for anatomical neuroimaging research. proceedings of the 12th annual meeting of the organization for human brain mapping. Florence, Italy, pages 2266, 2006.

[4]

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, and others. Neuromaps: structural and functional interpretation of brain maps. Nature Methods, 19(11):1472–1479, 2022.