Getting started with ggseg.extra • ggseg.extra

ggseg.extra provides pipelines for creating brain atlas data sets compatible with the ggseg and ggseg3d plotting packages. It supports multiple neuroimaging input formats:

Function	Input	Use case
`create_cortical_from_annotation()`	FreeSurfer `.annot` files	Cortical parcellations (DK, DKT, Yeo networks)
`create_cortical_from_labels()`	Individual `.label` files	Custom region combinations
`create_cortical_from_gifti()`	GIFTI `.label.gii` files	Cortical parcellations in GIFTI format
`create_cortical_from_cifti()`	CIFTI `.dlabel.nii` files	HCP-style cortical parcellations
`create_cortical_from_neuromaps()`	Neuromaps `.func.gii` or `.nii` files	Brain maps and parcellations from neuromaps
`create_subcortical_from_volume()`	Volumetric segmentation	Subcortical structures (thalamus, amygdala)
`create_wholebrain_from_volume()`	Volumetric parcellation with colour table	Combined cortical + subcortical atlases
`create_tract_from_tractography()`	Tractography files (`.trk`, `.tck`)	White matter tracts

All functions produce a ggseg_atlas object that works with both ggseg (2D) and ggseg3d (3D).

What’s inside a ggseg_atlas

Every atlas contains:

Core metadata — region names, hemisphere labels, and the mapping between region names and annotation labels.
Colour palette — extracted from your input files or auto-generated.
3D data — vertex indices for cortical atlases, or meshes for subcortical and tract atlases.
2D geometry (optional) — sf polygon outlines for flat brain plots.

Fast iteration vs. full pipeline

Each creation function uses a steps parameter to control how much of the pipeline runs. For cortical atlases, steps = 1 reads the annotation and returns 3D vertex data in seconds. The full pipeline (steps = 1:8) adds 2D polygon extraction, which requires FreeSurfer and Chrome and takes longer.

annot_files <- file.path(
  freesurfer::fs_dir(),
  "subjects",
  "fsaverage5",
  "label",
  c("lh.aparc.annot", "rh.aparc.annot")
)

atlas_3d_only <- create_cortical_from_annotation(
  input_annot = annot_files,
  steps = 1
)

atlas_full <- create_cortical_from_annotation(
  input_annot = annot_files,
  output_dir = "my_atlas",
  steps = 1:8
)

Start with 3D-only to verify your inputs look right, then run the full pipeline when you’re ready for 2D geometry.

Post-processing

Raw atlases often contain regions you don’t need (white matter, ventricles, unknown labels) and views that don’t show your structures well. The atlas_region_* and atlas_view_* helpers from ggseg.formats handle cleanup without rebuilding from scratch. See vignette("post-processing") for the full toolkit.

System requirements

Creating atlases (as opposed to using pre-built ones) requires:

FreeSurfer for reading neuroimaging formats
ImageMagick for 2D geometry extraction
Chrome or Chromium for 3D screenshots

Run setup_sitrep() to check your setup, or see vignette("system-setup") for installation details and parallel processing setup.

Tutorials

The package includes step-by-step tutorials that walk through complete atlas creation pipelines:

Cortical atlas — from FreeSurfer annotation files
Label-based atlas — from individual label files
Neuromaps atlas — from neuromaps surface or volume data
Subcortical atlas — from volumetric segmentation
Tract atlas — from tractography data

See also vignette("pipeline-configuration") for controlling verbosity, parallelism, and output directories.