Pipeline configuration

The atlas creation functions share common parameters that control pipeline behaviour. You can set these explicitly in each function call, globally via R options, or through environment variables.

Parameter hierarchy

Parameters resolve in this order:

1. Explicit argument — value passed directly to the function
2. R option — value from options()
3. Environment variable — value from Sys.getenv()
4. Default — built-in default value

This lets you set project-wide defaults while still overriding them for specific calls.

Available options

Parameter	R Option	Environment Variable	Default
verbose	ggseg.extra.verbose	GGSEG_EXTRA_VERBOSE	TRUE
cleanup	ggseg.extra.cleanup	GGSEG_EXTRA_CLEANUP	TRUE
skip_existing	ggseg.extra.skip_existing	GGSEG_EXTRA_SKIP_EXISTING	TRUE

The tolerance, smoothness and smooth_refinements parameters are deprecated. sf simplification has moved out of atlas creation entirely — call atlas_smooth() on the returned atlas instead.

Setting options in R

Use options() to set defaults for your R session:

options(
  ggseg.extra.cleanup = FALSE
)

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

Verbosity

The verbose parameter controls progress messages during pipeline execution.

options(ggseg.extra.verbose = FALSE)

Sys.setenv(GGSEG_EXTRA_VERBOSE = "false")

Cleanup

The cleanup parameter controls whether intermediate files are removed after pipeline completion. Set it to FALSE to keep them for debugging:

options(ggseg.extra.cleanup = FALSE)

atlas <- create_subcortical_from_volume(
  input_volume = "aseg.mgz",
  output_dir = "my_atlas_files"
)

Skip existing

The skip_existing parameter lets you resume interrupted pipeline runs by reusing existing intermediate files:

options(ggseg.extra.skip_existing = FALSE)

options(ggseg.extra.skip_existing = TRUE)

Geometry parameters

sf geometry simplification is no longer applied during atlas creation. Use atlas_smooth() on the returned atlas to control the trade-off between detail and file size. See vignette("post-processing") for the full workflow.

Environment variables

Environment variables are useful for CI pipelines, Docker containers, or settings that should persist across R sessions.

In .Renviron:

GGSEG_EXTRA_VERBOSE=false
GGSEG_EXTRA_CLEANUP=true
GGSEG_EXTRA_SKIP_EXISTING=true

In a shell:

export GGSEG_EXTRA_VERBOSE=false
R -e "ggseg.extra::create_cortical_from_annotation(...)"

In Docker:

ENV GGSEG_EXTRA_VERBOSE=false
ENV GGSEG_EXTRA_CLEANUP=true

Overriding defaults

Explicit arguments always win:

options(ggseg.extra.cleanup = TRUE)

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

Recipes

Development and debugging

options(
  ggseg.extra.verbose = TRUE,
  ggseg.extra.cleanup = FALSE,
  ggseg.extra.skip_existing = FALSE
)

Production and CI

options(
  ggseg.extra.verbose = FALSE,
  ggseg.extra.cleanup = TRUE,
  ggseg.extra.skip_existing = TRUE
)

Iterating on simplification level

atlas_smooth(keep = ...) is the single tuning knob for sf simplification. Higher keep retains more vertices (more detail, larger file). Try a few values without re-running the slow creation pipeline:

annot_files <- c("lh.myatlas.annot", "rh.myatlas.annot")

atlas_raw <- create_cortical_from_annotation(
  input_annot = annot_files,
  output_dir = "atlas_workdir"
)

# High fidelity
atlas <- atlas_raw |> atlas_smooth(keep = 0.5)

# Compact
atlas <- atlas_raw |> atlas_smooth(keep = 0.05, exclude = "cortex_")