netneurotools.datasets.fetch_fsaverage_curated

netneurotools.datasets.fetch_fsaverage_curated(version='fsaverage', force=False, data_dir=None, verbose=1)

Download files for fsaverage FreeSurfer template.

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

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

Parameters:

version (str, optional) – One of {‘fsaverage’, ‘fsaverage4’, ‘fsaverage5’, ‘fsaverage6’}. Default: ‘fsaverage’

Returns:

filenames – Dictionary-like object with keys [‘white’, ‘pial’, ‘inflated’, ‘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 fsaverage surfaces from the neuromaps package (see neuromaps.datasets.fetch_fsaverage). All files are provided in GIFTI format (.gii) rather than FreeSurfer’s native format.

The returned files include:

• white: White matter surface geometry (.surf.gii), representing the

  boundary between white matter and gray matter. Corresponds to FreeSurfer surfaces ‘lh.white’ and ‘rh.white’.

• pial: Pial surface geometry (.surf.gii), representing the outer

  cortical boundary. Corresponds to FreeSurfer surfaces ‘lh.pial’ and ‘rh.pial’.

• inflated: Inflated surface geometry (.surf.gii) for improved

  visualization of sulci and gyri. Corresponds to FreeSurfer surfaces ‘lh.inflated’ and ‘rh.inflated’.

• sphere: Spherical surface geometry (.surf.gii) used for surface-based

  registration and applying parcellations. Corresponds to FreeSurfer surfaces ‘lh.sphere’ and ‘rh.sphere’.

• medial: Medial wall mask (.label.gii) indicating vertices to exclude

  from analyses (vertices with no cortex). Not a standard FreeSurfer output; derived by neuromaps to mark the no-medial-wall vertices.

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

  on the midthickness surface. Corresponds to FreeSurfer ‘lh.sulc’ and ‘rh.sulc’ values resampled to the midthickness surface.

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

  area on the midthickness surface. Not a standard FreeSurfer output; computed from mesh triangle areas and averaged per vertex.

The vertex density varies by version: fsaverage (164k vertices), fsaverage6 (41k), fsaverage5 (10k), and fsaverage4 (3k).

Example directory tree:

~/nnt-data/tpl-fsaverage_curated
├── fsaverage
│   ├── tpl-fsaverage_den-164k_hemi-L_desc-nomedialwall_dparc.label.gii
│   ├── tpl-fsaverage_den-164k_hemi-L_desc-sulc_midthickness.shape.gii
│   ├── tpl-fsaverage_den-164k_hemi-L_desc-vaavg_midthickness.shape.gii
│   ├── tpl-fsaverage_den-164k_hemi-L_inflated.surf.gii
│   ├── tpl-fsaverage_den-164k_hemi-L_pial.surf.gii
│   ├── tpl-fsaverage_den-164k_hemi-L_sphere.surf.gii
│   ├── tpl-fsaverage_den-164k_hemi-L_white.surf.gii
│   ├── tpl-fsaverage_den-164k_hemi-R_desc-nomedialwall_dparc.label.gii
│   ├── tpl-fsaverage_den-164k_hemi-R_desc-sulc_midthickness.shape.gii
│   ├── tpl-fsaverage_den-164k_hemi-R_desc-vaavg_midthickness.shape.gii
│   ├── tpl-fsaverage_den-164k_hemi-R_inflated.surf.gii
│   ├── tpl-fsaverage_den-164k_hemi-R_pial.surf.gii
│   ├── tpl-fsaverage_den-164k_hemi-R_sphere.surf.gii
│   └── tpl-fsaverage_den-164k_hemi-R_white.surf.gii
├── fsaverage4
│   ├── tpl-fsaverage_den-3k_hemi-L_desc-nomedialwall_dparc.label.gii
│   ├── tpl-fsaverage_den-3k_hemi-L_desc-sulc_midthickness.shape.gii
│   ├── tpl-fsaverage_den-3k_hemi-L_desc-vaavg_midthickness.shape.gii
│   ├── tpl-fsaverage_den-3k_hemi-L_inflated.surf.gii
│   ├── tpl-fsaverage_den-3k_hemi-L_pial.surf.gii
│   ├── tpl-fsaverage_den-3k_hemi-L_sphere.surf.gii
│   ├── tpl-fsaverage_den-3k_hemi-L_white.surf.gii
│   ├── tpl-fsaverage_den-3k_hemi-R_desc-nomedialwall_dparc.label.gii
│   ├── tpl-fsaverage_den-3k_hemi-R_desc-sulc_midthickness.shape.gii
│   ├── tpl-fsaverage_den-3k_hemi-R_desc-vaavg_midthickness.shape.gii
│   ├── tpl-fsaverage_den-3k_hemi-R_inflated.surf.gii
│   ├── tpl-fsaverage_den-3k_hemi-R_pial.surf.gii
│   ├── tpl-fsaverage_den-3k_hemi-R_sphere.surf.gii
│   └── tpl-fsaverage_den-3k_hemi-R_white.surf.gii
├── fsaverage5
│   ├── tpl-fsaverage_den-10k_hemi-L_desc-nomedialwall_dparc.label.gii
│   ├── tpl-fsaverage_den-10k_hemi-L_desc-sulc_midthickness.shape.gii
│   ├── tpl-fsaverage_den-10k_hemi-L_desc-vaavg_midthickness.shape.gii
│   ├── tpl-fsaverage_den-10k_hemi-L_inflated.surf.gii
│   ├── tpl-fsaverage_den-10k_hemi-L_pial.surf.gii
│   ├── tpl-fsaverage_den-10k_hemi-L_sphere.surf.gii
│   ├── tpl-fsaverage_den-10k_hemi-L_white.surf.gii
│   ├── tpl-fsaverage_den-10k_hemi-R_desc-nomedialwall_dparc.label.gii
│   ├── tpl-fsaverage_den-10k_hemi-R_desc-sulc_midthickness.shape.gii
│   ├── tpl-fsaverage_den-10k_hemi-R_desc-vaavg_midthickness.shape.gii
│   ├── tpl-fsaverage_den-10k_hemi-R_inflated.surf.gii
│   ├── tpl-fsaverage_den-10k_hemi-R_pial.surf.gii
│   ├── tpl-fsaverage_den-10k_hemi-R_sphere.surf.gii
│   └── tpl-fsaverage_den-10k_hemi-R_white.surf.gii
└── fsaverage6
    ├── tpl-fsaverage_den-41k_hemi-L_desc-nomedialwall_dparc.label.gii
    ├── tpl-fsaverage_den-41k_hemi-L_desc-sulc_midthickness.shape.gii
    ├── tpl-fsaverage_den-41k_hemi-L_desc-vaavg_midthickness.shape.gii
    ├── tpl-fsaverage_den-41k_hemi-L_inflated.surf.gii
    ├── tpl-fsaverage_den-41k_hemi-L_pial.surf.gii
    ├── tpl-fsaverage_den-41k_hemi-L_sphere.surf.gii
    ├── tpl-fsaverage_den-41k_hemi-L_white.surf.gii
    ├── tpl-fsaverage_den-41k_hemi-R_desc-nomedialwall_dparc.label.gii
    ├── tpl-fsaverage_den-41k_hemi-R_desc-sulc_midthickness.shape.gii
    ├── tpl-fsaverage_den-41k_hemi-R_desc-vaavg_midthickness.shape.gii
    ├── tpl-fsaverage_den-41k_hemi-R_inflated.surf.gii
    ├── tpl-fsaverage_den-41k_hemi-R_pial.surf.gii
    ├── tpl-fsaverage_den-41k_hemi-R_sphere.surf.gii
    └── tpl-fsaverage_den-41k_hemi-R_white.surf.gii

4 directories, 56 files

Examples

Load the fsaverage curated template surfaces:

>>> surfaces = fetch_fsaverage_curated(version='fsaverage')
>>> surfaces.keys()
dict_keys(['white', 'pial', 'inflated', 'sphere', 'medial', 'sulc', 'vaavg'])

Access the pial surface GIFTI files:

>>> surfaces.pial
Surface(L=PosixPath('~/nnt-data/tpl-fsaverage_curated/fsaverage/tpl-fsaverage_den-164k_hemi-L_pial.surf.gii'),
        R=PosixPath('~/nnt-data/tpl-fsaverage_curated/fsaverage/tpl-fsaverage_den-164k_hemi-R_pial.surf.gii'))

Load the left pial surface with nibabel:

>>> import nibabel as nib
>>> pial_left = nib.load(surfaces.pial.L)
>>> vertices = pial_left.agg_data('pointset')
>>> faces = pial_left.agg_data('triangle')
>>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}")
Vertices: (163842, 3), Faces: (327680, 3)

Load and examine the sulcal depth data:

>>> sulc_left = nib.load(surfaces.sulc.L)
>>> sulc_data = sulc_left.agg_data()
>>> sulc_min, sulc_max = sulc_data.min(), sulc_data.max()
>>> print(f"Sulcal depth range: {sulc_min:.2f} to {sulc_max:.2f}")
Sulcal depth range: -1.78 to 1.88

References

[1]

Anders M Dale, Bruce Fischl, and Martin I Sereno. Cortical surface-based analysis: i. segmentation and surface reconstruction. Neuroimage, 9(2):179–194, 1999.

[2]

Bruce Fischl, Martin I Sereno, and Anders M Dale. Cortical surface-based analysis: ii: inflation, flattening, and a surface-based coordinate system. Neuroimage, 9(2):195–207, 1999.

[3]

Bruce Fischl, Martin I Sereno, Roger BH Tootell, and Anders M Dale. High-resolution intersubject averaging and a coordinate system for the cortical surface. Human brain mapping, 8(4):272–284, 1999.

[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.