Home
Automated atlas-based morphometry extraction for FreeSurfer-processed brain MRI
Why fsatlas?¶
FreeSurfer's recon-all pipeline produces cortical and subcortical statistics for its built-in atlases (Desikan-Killiany, Destrieux, DKT). But modern neuroimaging studies increasingly require other parcellations — higher-resolution cortical atlases like Schaefer 2018 or HCP-MMP, or multi-scale subcortical atlases like Tian 2020.
Extracting these requires manually chaining several FreeSurfer commands:
fsatlas wraps this entire pipeline into a single command.
Features¶
31 Built-in Atlases
Ships with Schaefer 2018 (100–1000 parcels), Tian 2020 subcortical (Scales I–IV), HCP-MMP1, Brainnetome, Gordon333, AICHA384, AAL116, 4S-156, and all FreeSurfer built-ins. Auto-downloaded on first use.
Custom Atlas Support
Point at any .annot, .nii.gz, .dlabel.gii, or .gca file. fsatlas auto-detects the format and handles the rest.
Surface Pipeline
Transfers .annot / .dlabel.gii from fsaverage → subject via mri_surf2surf, then extracts 9 cortical measures via mris_anatomical_stats.
Volumetric Pipeline
Registers MNI-space NIfTI → subject native space via mri_vol2vol + talairach.xfm, or applies a GCA via mri_ca_label. Extracts 7 measures via mri_segstats.
Wide-Format TSV Output
One row per region per subject — measures as columns, driven by the atlas LUT. Compatible with pandas, R tidyverse, and any statistical analysis tool.
Failure Resilience
Pipeline continues across subjects on errors. All failures are logged to a separate TSV for review.
Thirty-Second Demo¶
# Install
pip install fsatlas
# See what atlases are available
fsatlas list-atlases
# Extract Schaefer 100-parcel cortical morphometry for all subjects
fsatlas extract --atlas schaefer100-7 --output-dir ./results
# Results:
# ./results/schaefer100-7.tsv
# ./results/schaefer100-7_failures.tsv
Output at a Glance¶
subject_id index label hemisphere thickness_mean_mm surface_area_mm2 ... tiv_mm3
---------- ----- ------------------- ---------- ----------------- ---------------- --- --------
sub-01 1 7Networks_LH_Vis_1 lh 2.341 843.0 ... 1458203.0
sub-01 2 7Networks_LH_Vis_2 lh 2.289 700.5 ... 1458203.0
sub-02 1 7Networks_LH_Vis_1 lh 2.501 857.2 ... 1501044.0
Wide-format data — one row per region per subject, every measure as a column. Easy to filter, pivot, or merge in any analysis environment.
Next Steps¶
Install fsatlas from PyPI or from source. Set up FreeSurfer environment variables.
Walk through common extraction workflows with real command examples.
Browse all 31 built-in atlases with descriptions, citations, and parcel counts.
Full reference for all CLI commands and options.