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.

The shortest path

From a FreeSurfer annotation to something you can plot:

atlas <- create_cortical_from_annotation(
  input_annot = c("lh.aparc.annot", "rh.aparc.annot")
)

# Fewer vertices, and the voxel staircase rounded off
atlas <- atlas_polish(atlas, keep = 0.2)

plot(atlas)

That is the whole cortical pipeline. sitrep() reports whether your machine has what the other pipelines need before you start one.

Picking a creation function

Which pipeline you want depends on the format you have:

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_cerebellar_from_gifti()`	GIFTI labels on the SUIT surface	Cerebellar parcellations
`create_cerebellar_from_annotation()`	FreeSurfer `.annot` on the SUIT surface	Cerebellar parcellations
`create_cerebellar_from_volume()`	Volumetric cerebellar segmentation	Cerebellar parcellations, with 3D meshes
`create_tract_from_tractography()`	Tractography files (`.trk`, `.tck`)	White matter tracts
`create_tract_from_volume()`	Volumetric tract labels	Tracts given as a segmentation rather than streamlines

Each function produces a ggseg_atlas object that works with both ggseg (2D) and ggseg3d (3D). The exception is create_wholebrain_from_volume(), which returns a named list of them: one each for the cortical, subcortical and cerebellar parts of the volume.

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.

How each pipeline works

The cortical pipeline projects inflated mesh triangles straight to 2D polygons, so it takes seconds and needs no FreeSurfer installation. The subcortical and tract pipelines instead build 3D meshes from a volume and get their 2D view by slicing it. Each has its own steps, inputs and system requirements: the atlas workflows article walks through all five with diagrams.

Post-processing

Raw atlases often contain regions you don’t need (white matter, ventricles, unknown labels), views that don’t show your structures well, and outlines that still follow the voxel grid. The atlas_region_* and atlas_view_* verbs curate the first two and atlas_polish() shapes the third, all without rebuilding from scratch. See vignette("post-processing") for the full toolkit and ?atlas-verbs for the vocabulary.

System requirements

Using pre-built atlases requires nothing beyond R. Creating your own atlases may require additional R packages and system tools depending on the pipeline:

Cortical (annotation/label files) — no system tools needed; uses the freesurferformats R package to read files and projects mesh to 2D directly.
Subcortical / whole-brain — FreeSurfer; contours are traced from the projection itself, with no image round-trip.
Cerebellar — no system tools from a surface parcellation (GIFTI or annotation); FreeSurfer from a volume.
Tract — no system tools; reads tractography files with R packages.

All heavier dependencies (freesurfer, Rvcg, terra, etc.) are in Suggests and only loaded when needed.

Run sitrep() to check your setup, or see vignette("system-setup") for details.

Tutorials

Step-by-step tutorials that walk through complete atlas creation pipelines, one per input format, live on the package website under Tutorials. They are not shipped with the installed package because they need FreeSurfer subject data and network access to build.

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