spectralbrain.io.parcellate#

spectralbrain.io.parcellate(*, subjects_dir=None, subject_id=None, t1_path=None, atlas='schaefer_200', hemi='lh', surface='white', atlas_volume_path=None, gpu=None)[source]#

Parcellate a cortical hemisphere into atlas-defined regions.

This is the high-level entry point that auto-detects the source format and applies the appropriate projection strategy.

Parameters:

  • subjects_dir (PathLike, optional) – Path to the FreeSurfer SUBJECTS_DIR. Falls back to the $SUBJECTS_DIR environment variable.

  • subject_id (str, optional) – FreeSurfer subject ID (e.g. 'sub-01'). Required when using FreeSurfer surfaces.

  • t1_path (PathLike, optional) – Path to a raw T1-weighted NIfTI file. If provided (and no subjects_dir), the preprocessing pipeline is run first: skull-strip → FastSurfer/recon-all → then parcellate.

  • atlas (str) –

    Target atlas short name. See list_atlases() for all supported names. Common choices:

    • 'schaefer_200' — Schaefer 200 parcels, 7 networks

    • 'schaefer_400' — Schaefer 400 parcels, 7 networks

    • 'dkt' — Desikan-Killiany-Tourville (FreeSurfer native)

    • 'destrieux' — Destrieux 2009 (FreeSurfer native)

    • 'glasser' — HCP-MMP 1.0 (360 parcels)

    • 'brainnetome' — Brainnetome 246 regions

    • 'aal3' — AAL3 atlas

    • 'harvard_oxford' — Harvard-Oxford cortical

  • hemi ({'lh', 'rh'}) – Hemisphere.

  • surface (str) – FreeSurfer surface to use: 'white', 'pial', 'inflated', 'sphere', etc.

  • atlas_volume_path (PathLike, optional) – Explicit path to a volumetric atlas NIfTI file (overrides the automatic fetcher for MNI-volume atlases).

  • gpu (bool or None) – GPU toggle for preprocessing steps.

Returns:

ParcellationResult – Dataclass with .vertices, .faces, .labels, .parcels (dict of sub-meshes), and metadata.

Raises:

  • ValueError – If the atlas is not recognised, or if neither subjects_dir nor t1_path is provided.

  • FileNotFoundError – If required files (surfaces, annotations) are missing.

  • EnvironmentError – If FreeSurfer or containers are needed but not available.

Return type:

ParcellationResult

Examples

From FreeSurfer subjects_dir (most common):

>>> result = parcellate(
...     subjects_dir="/data/freesurfer",
...     subject_id="sub-01",
...     atlas="schaefer_200",
...     hemi="lh",
... )
>>> result.n_parcels
100
>>> verts, faces = result.get_parcel(1)

From raw T1w (runs preprocessing first):

>>> result = parcellate(
...     t1_path="/data/sub-01_T1w.nii.gz",
...     atlas="dkt",
...     hemi="lh",
... )

With a custom volumetric atlas:

>>> result = parcellate(
...     subjects_dir="/data/freesurfer",
...     subject_id="sub-01",
...     atlas="brainnetome",
...     atlas_volume_path="/atlases/BN_Atlas_246_2mm.nii.gz",
... )