netneurotools.datasets.fetch_fsaverage
- netneurotools.datasets.fetch_fsaverage(version='fsaverage', use_local=False, force=False, data_dir=None, verbose=1)[source]
Download files for fsaverage FreeSurfer template.
This dataset contains surface files for the fsaverage template including original, white matter, pial, inflated, and spherical surfaces for both left and right hemispheres.
If you used this data, please cite 1, 2, 3.
- Parameters:
version (str, optional) – One of {‘fsaverage’, ‘fsaverage3’, ‘fsaverage4’, ‘fsaverage5’, ‘fsaverage6’}. Default: ‘fsaverage’
use_local (bool, optional) – If True, will attempt to use local FreeSurfer data. Default: False
- Returns:
filenames – Dictionary-like object with keys [‘orig’, ‘white’, ‘smoothwm’, ‘pial’, ‘inflated’, ‘sphere’], where corresponding values are Surface namedtuples containing filepaths for the left (L) and right (R) hemisphere surface files.
- Return type:
- 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
The returned surfaces represent different stages of cortical surface reconstruction and transformations:
orig: Original surface extracted from the brain volume, representing the initial estimate of the cortical boundary before topology correction.
white: White matter surface, representing the boundary between white matter and gray matter (inner cortical surface).
smoothwm: Smoothed white matter surface, created by applying smoothing to the white surface for improved visualization and analysis.
pial: Pial surface, representing the outer boundary of the cortex (gray matter/CSF interface). This is commonly used for cortical thickness calculations and surface-based registration.
inflated: Inflated surface, where sulci and gyri are smoothed to make visualization of the entire cortical surface easier while preserving topology. Useful for visualizing data across the cortex without occlusion by folding patterns.
sphere: Spherical surface, where the cortical surface is mapped to a sphere. This is essential for surface-based registration, inter-subject alignment, and applying parcellations.
Each surface can be loaded with neuroimaging tools like nibabel and used for surface-based analyses, visualization, or spatial transformations.
In a typical FreeSurfer installation, these template surfaces can be found in the subjects directory under
$FREESURFER_HOME/subjects/(e.g.,$FREESURFER_HOME/subjects/fsaverage/surf/). Whenuse_local=True, this function will attempt to locate and use these local files instead of downloading them.Example directory tree:
~/nnt-data/tpl-fsaverage ├── fsaverage │ ├── LICENSE │ └── surf │ ├── lh.curv │ ├── lh.inflated │ ├── lh.inflated_avg │ ├── lh.orig │ ├── lh.orig_avg │ ├── lh.pial │ ├── lh.pial_avg │ ├── lh.smoothwm │ ├── lh.sphere │ ├── lh.sphere.reg.avg │ ├── lh.white │ ├── lh.white_avg │ ├── rh.curv │ ├── rh.inflated │ ├── rh.inflated_avg │ ├── rh.orig │ ├── rh.orig_avg │ ├── rh.pial │ ├── rh.pial_avg │ ├── rh.smoothwm │ ├── rh.sphere │ ├── rh.sphere.reg.avg │ ├── rh.white │ └── rh.white_avg ├── fsaverage3 │ ├── LICENSE │ └── surf │ ├── lh.curv │ ├── lh.inflated │ ├── lh.inflated_avg │ ├── lh.orig │ ├── lh.orig_avg │ ├── lh.pial │ ├── lh.pial_avg │ ├── lh.smoothwm │ ├── lh.sphere │ ├── lh.sphere.reg.avg │ ├── lh.white │ ├── lh.white_avg │ ├── rh.curv │ ├── rh.inflated │ ├── rh.inflated_avg │ ├── rh.orig │ ├── rh.orig_avg │ ├── rh.pial │ ├── rh.pial_avg │ ├── rh.smoothwm │ ├── rh.sphere │ ├── rh.sphere.reg.avg │ ├── rh.white │ └── rh.white_avg ├── fsaverage4 │ ├── LICENSE │ └── surf │ ├── lh.curv │ ├── lh.inflated │ ├── lh.inflated_avg │ ├── lh.orig │ ├── lh.orig_avg │ ├── lh.pial │ ├── lh.pial_avg │ ├── lh.smoothwm │ ├── lh.sphere │ ├── lh.sphere.reg.avg │ ├── lh.white │ ├── lh.white_avg │ ├── rh.curv │ ├── rh.inflated │ ├── rh.inflated_avg │ ├── rh.orig │ ├── rh.orig_avg │ ├── rh.pial │ ├── rh.pial_avg │ ├── rh.smoothwm │ ├── rh.sphere │ ├── rh.sphere.reg.avg │ ├── rh.white │ └── rh.white_avg ├── fsaverage5 │ ├── LICENSE │ └── surf │ ├── lh.curv │ ├── lh.inflated │ ├── lh.inflated_avg │ ├── lh.orig │ ├── lh.orig_avg │ ├── lh.pial │ ├── lh.pial_avg │ ├── lh.smoothwm │ ├── lh.sphere │ ├── lh.sphere.reg.avg │ ├── lh.white │ ├── lh.white_avg │ ├── rh.curv │ ├── rh.inflated │ ├── rh.inflated_avg │ ├── rh.orig │ ├── rh.orig_avg │ ├── rh.pial │ ├── rh.pial_avg │ ├── rh.smoothwm │ ├── rh.sphere │ ├── rh.sphere.reg.avg │ ├── rh.white │ └── rh.white_avg └── fsaverage6 ├── LICENSE └── surf ├── lh.curv ├── lh.inflated ├── lh.inflated_avg ├── lh.orig ├── lh.orig_avg ├── lh.pial ├── lh.pial_avg ├── lh.smoothwm ├── lh.sphere ├── lh.sphere.reg.avg ├── lh.white ├── lh.white_avg ├── rh.curv ├── rh.inflated ├── rh.inflated_avg ├── rh.orig ├── rh.orig_avg ├── rh.pial ├── rh.pial_avg ├── rh.smoothwm ├── rh.sphere ├── rh.sphere.reg.avg ├── rh.white └── rh.white_avg 10 directories, 125 filesExamples
Load the fsaverage template surfaces:
>>> surfaces = fetch_fsaverage(version='fsaverage') >>> surfaces.keys() dict_keys(['orig', 'white', 'smoothwm', 'pial', 'inflated', 'sphere'])
Access the pial surface paths for left and right hemispheres:
>>> surfaces.pial Surface(L=PosixPath('~/nnt-data/tpl-fsaverage/fsaverage/surf/lh.pial'), R=PosixPath('~/nnt-data/tpl-fsaverage/fsaverage/surf/rh.pial'))
Load the left pial surface with nibabel to examine its structure:
>>> import nibabel as nib >>> pial_left = nib.freesurfer.read_geometry(surfaces.pial.L) >>> vertices, faces = pial_left >>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}") Vertices: (163842, 3), Faces: (327680, 3)
References