System setup

What each pipeline needs

The cortical mesh-projection pipeline is the lightest — it runs in seconds with no system tools and minimal R dependencies. All heavier packages (freesurfer, Rvcg, terra, etc.) are in Suggests and only loaded when a pipeline actually needs them.

FreeSurfer

FreeSurfer is needed by the subcortical, whole-brain, cerebellar volume, and neuromaps volume pipelines. The cortical annotation pipeline needs the freesurferformats R package (not FreeSurfer itself) to read .annot and .label files, and the tract pipelines need no system tools at all.

On macOS, you also need:

• XQuartz
• Xcode command line tools

Verify your installation:

freesurfer::fs_dir()

Parallel processing

ggseg.extra uses the furrr package for parallel processing. By default, processing runs sequentially.

To enable parallel processing, set up a future plan before running atlas creation functions:

library(future)

plan(multicore, workers = 4)

Prefer multicore where it is available. The pipelines hand each worker a whole volume, which under multicore costs nothing: forked workers share the parent’s memory copy-on-write. A multisession worker is a fresh R process, so the volume is serialised to it over a socket – for a 256^3 aseg that is 67 MB per worker, which is more work than the projection it was sent to compute. Measured on an 8-core machine, the projection step runs about 3.4x faster under plan(multicore, workers = 4) and slightly slower under plan(multisession, workers = 4) than it does sequentially.

multicore is unavailable on Windows, and RStudio disables it by default. There multisession is the only parallel option, and sequential is often the better choice.

plan(multisession, workers = 4)

To return to sequential processing:

plan(sequential)

Progress bars

ggseg.extra uses progressr to report progress during long-running operations. Progress reporting is disabled by default.

To enable progress bars:

library(progressr)

handlers("cli")
handlers(global = TRUE)

This gives you a cli-style progress bar that updates as each region or step completes. It works with both sequential and parallel execution.

Checking your setup

Run the setup report to verify everything is in place:

sitrep()