Package 'ggseg.extra'

Description

Converts logical, numeric, or character input to an integer verbosity level: 0L (silent), 1L (standard), or 2L (debug).

Usage

as_verbosity(x)

Arguments

Value

Integer 0L, 1L, or 2L

Examples

as_verbosity(FALSE)
as_verbosity(TRUE)
as_verbosity(2)

Description

Reduce vertex count in the sf geometry of a ggseg_atlas object using Douglas-Peucker simplification. Higher tolerance values produce simpler shapes with fewer vertices. This avoids re-running the full atlas creation pipeline.

Usage

atlas_simplify(atlas, tolerance = 0.5)

Arguments

Value

A modified ggseg_atlas with simplified sf geometry.

Examples

## Not run: 
atlas <- atlas_simplify(my_atlas, tolerance = 1)
plot(atlas)

## End(Not run)

Description

Apply kernel smoothing to the sf geometry of a ggseg_atlas object. Higher smoothness values produce rounder region boundaries. This avoids re-running the full atlas creation pipeline.

Usage

atlas_smooth(atlas, smoothness = 5)

Arguments

Value

A modified ggseg_atlas with smoothed sf geometry.

Examples

## Not run: 
atlas <- atlas_smooth(my_atlas, smoothness = 10)
plot(atlas)

## End(Not run)

Description

Turn FreeSurfer annotation files into a brain atlas you can plot with ggseg and ggseg3d. Reads the annotation, extracts vertex-to-region assignments, and generates 2D polygon geometry by projecting the inflated mesh triangles to 2D via orthographic projection.

Usage

create_cortical_from_annotation(
  input_annot,
  atlas_name = NULL,
  output_dir = NULL,
  hemisphere = c("rh", "lh"),
  views = c("lateral", "medial", "superior", "inferior"),
  tolerance = NULL,
  smooth_refinements = NULL,
  cleanup = NULL,
  verbose = get_verbose(),
  skip_existing = NULL
)

Arguments

Value

A ggseg_atlas object containing region metadata (core), vertex indices for 3D rendering, a colour palette, and sf geometry for 2D plots.

Examples

## Not run: 
atlas <- create_cortical_from_annotation(
  input_annot = c("lh.aparc.DKTatlas.annot", "rh.aparc.DKTatlas.annot")
)
ggseg(atlas = atlas)

## End(Not run)

Description

Build a brain atlas from a CIFTI dense label file (.dlabel.nii). The file must be in fsaverage5 space (10,242 vertices per hemisphere).

Usage

create_cortical_from_cifti(
  cifti_file,
  atlas_name = NULL,
  output_dir = NULL,
  hemisphere = c("rh", "lh"),
  views = c("lateral", "medial", "superior", "inferior"),
  tolerance = NULL,
  smooth_refinements = NULL,
  cleanup = NULL,
  verbose = get_verbose(),
  skip_existing = NULL
)

Arguments

Value

A ggseg_atlas object.

Examples

## Not run: 
atlas <- create_cortical_from_cifti(
  cifti_file = "parcellation.dlabel.nii"
)

## End(Not run)

Description

Build a brain atlas from GIFTI label files (.label.gii). Assumes fsaverage5 surface space (10,242 vertices per hemisphere).

Usage

create_cortical_from_gifti(
  gifti_files,
  atlas_name = NULL,
  output_dir = NULL,
  hemisphere = c("rh", "lh"),
  views = c("lateral", "medial", "superior", "inferior"),
  tolerance = NULL,
  smooth_refinements = NULL,
  cleanup = NULL,
  verbose = get_verbose(),
  skip_existing = NULL
)

Arguments

Value

A ggseg_atlas object.

Examples

## Not run: 
atlas <- create_cortical_from_gifti(
  gifti_files = c("lh.aparc.label.gii", "rh.aparc.label.gii")
)

## End(Not run)

Description

Build an atlas from individual FreeSurfer .label files rather than a complete annotation. Each label file defines a single region by listing which surface vertices belong to it.

The function detects hemisphere from filename prefixes (lh. or rh.) and derives region names from the rest of the filename.

Usage

create_cortical_from_labels(
  label_files,
  atlas_name = NULL,
  input_lut = NULL,
  output_dir = NULL,
  views = c("lateral", "medial"),
  tolerance = NULL,
  smooth_refinements = NULL,
  cleanup = NULL,
  verbose = get_verbose(),
  skip_existing = NULL
)

Arguments

Value

A ggseg_atlas object.

Examples

## Not run: 
labels <- c("lh.region1.label", "lh.region2.label", "rh.region1.label")
atlas <- create_cortical_from_labels(labels)

## End(Not run)

Description

Build a brain atlas directly from a neuromaps annotation. The annotation is downloaded via neuromapr::fetch_neuromaps_annotation().

Supports both surface (.func.gii) and volume (.nii/.nii.gz) annotations. Volume annotations in MNI152 space are automatically projected to fsaverage5 via FreeSurfer's mri_vol2surf.

Usage

create_cortical_from_neuromaps(
  source,
  desc,
  space = "fsaverage",
  density = "10k",
  label_table = NULL,
  n_bins = NULL,
  atlas_name = NULL,
  output_dir = NULL,
  hemisphere = c("rh", "lh"),
  views = c("lateral", "medial", "superior", "inferior"),
  tolerance = NULL,
  smooth_refinements = NULL,
  cleanup = NULL,
  verbose = get_verbose(),
  skip_existing = NULL
)

Arguments

Value

A ggseg_atlas object.

Examples

## Not run: 
atlas <- create_cortical_from_neuromaps(
  source = "abagen",
  desc = "genepc1",
  n_bins = 7
)

## End(Not run)

Description

Turn a subcortical segmentation volume (like aseg.mgz) into a brain atlas with 3D meshes for each structure. The function extracts each labelled region from the volume, creates a surface mesh, and smooths it.

For 2D plotting, the function can also generate slice views by taking snapshots at specified coordinates and extracting contours.

Requires FreeSurfer for mesh generation.

Usage

create_subcortical_from_volume(
  input_volume,
  input_lut = NULL,
  atlas_name = NULL,
  views = NULL,
  output_dir = NULL,
  vertex_size_limits = NULL,
  dilate = NULL,
  tolerance = NULL,
  smoothness = NULL,
  verbose = get_verbose(),
  cleanup = NULL,
  skip_existing = NULL,
  decimate = 0.5,
  steps = NULL
)

Arguments

Value

A ggseg_atlas object with region metadata (core), 3D meshes, a colour palette, and optionally sf geometry for 2D slice plots.

Examples

## Not run: 
# Create 3D-only subcortical atlas from aseg
atlas <- create_subcortical_from_volume(
  input_volume = "path/to/aseg.mgz",
  input_lut = "path/to/FreeSurferColorLUT.txt",
  steps = 1:3
)

# View with ggseg3d
ggseg3d(atlas = atlas, hemisphere = "subcort")

# Full atlas with 2D slices
atlas <- create_subcortical_from_volume(
  input_volume = "path/to/aseg.mgz",
  input_lut = "path/to/ASegStatsLUT.txt"
)

# Post-process to remove/modify regions (functions from ggseg.formats)
atlas <- atlas |>
  atlas_region_remove("White-Matter") |>
  atlas_region_contextual("Cortex")

## End(Not run)

Description

Turn tractography streamlines into a brain atlas where each tract is rendered as a 3D tube. The function computes a centerline from the streamlines and generates a tube mesh around it.

You can provide tract data in several formats: TRK files from TrackVis, TCK files from MRtrix, or coordinate matrices directly in R. The function reads the streamlines, extracts a representative centerline (by averaging or selecting the medoid), and builds a tube mesh for 3D rendering.

For tracts with many streamlines, set tube_radius = "density" to make the tube thicker where more streamlines pass through.

Usage

create_tract_from_tractography(
  input_tracts,
  input_aseg = NULL,
  atlas_name = NULL,
  input_lut = NULL,
  tube_radius = 5,
  tube_segments = 8,
  n_points = 50,
  centerline_method = c("mean", "medoid"),
  views = NULL,
  output_dir = NULL,
  verbose = get_verbose(),
  tolerance = NULL,
  smoothness = NULL,
  cleanup = NULL,
  skip_existing = NULL,
  dilate = NULL,
  vertex_size_limits = NULL,
  steps = NULL
)

Arguments

Value

A ggseg_atlas object with type "tract", containing region metadata, tube meshes for 3D rendering, colours, and optionally sf geometry for 2D projection plots.

Examples

## Not run: 
# From TRK files (names derived from filenames)
atlas <- create_tract_from_tractography(
  input_tracts = c("cst_left.trk", "cst_right.trk")
)

# With custom names and colours via LUT
atlas <- create_tract_from_tractography(
  input_tracts = c("cst_left.trk", "cst_right.trk"),
  input_lut = "tract_colors.txt"
)

# View with ggseg3d
ggseg3d(atlas = atlas)

## End(Not run)

Description

Build a brain atlas from a single volumetric parcellation (NIfTI/MGZ) that contains both cortical and subcortical regions. Cortical regions are projected onto the fsaverage5 surface via FreeSurfer's mri_vol2surf and rendered as surface views, while subcortical regions go through the mesh-based subcortical pipeline.

Requires FreeSurfer.

Usage

create_wholebrain_from_volume(
  input_volume,
  input_lut = NULL,
  atlas_name = NULL,
  output_dir = NULL,
  projfrac = 0.5,
  projfrac_range = c(0, 1, 0.1),
  subject = "fsaverage5",
  regheader = TRUE,
  min_vertices = 50L,
  cortical_labels = NULL,
  subcortical_labels = NULL,
  cortical_views = c("lateral", "medial", "superior", "inferior"),
  subcortical_views = NULL,
  decimate = 0.5,
  tolerance = NULL,
  smoothness = NULL,
  cleanup = NULL,
  verbose = get_verbose(),
  skip_existing = NULL,
  steps = NULL
)

Arguments

Value

A named list with elements cortical and subcortical, each a ggseg_atlas object (or NULL if no regions of that type exist).

Label classification

The pipeline must know which labels are cortical (rendered on the surface) and which are subcortical (rendered as 3D meshes / 2D slices). Three mechanisms are available, applied in priority order:

1. Function arguments (highest priority): cortical_labels and subcortical_labels override everything for the specified labels.

2. LUT type column: If the colour lookup table has a type column with values "cortical" or "subcortical", that classification is used for any labels not covered by the function arguments. This is the recommended approach for reproducible atlas creation.

3. Vertex-count heuristic (fallback): Labels with at least min_vertices vertices on the surface projection are classified as cortical; the rest as subcortical.

Volume pre-processing

Before surface projection, the volume is filtered so that only voxel IDs listed in the LUT are kept; all other non-zero voxels are zeroed out. This prevents unlisted structures (e.g. white matter, ventricle masks) from bleeding onto the cortical surface during label dilation.

Cortical voxels are also used to generate the brain-outline reference geometry for the subcortical pipeline. The volume's orientation matrix (xform) is used to split cortical voxels by hemisphere: left-hemisphere voxels map to FreeSurfer label 3 (left cortex) and right-hemisphere to label 42 (right cortex).

Human oversight

This is the most complex pipeline in ggsegExtra and the one most likely to need manual correction. Recommended workflow:

1. Run steps = 1:2 first to project the volume and classify labels.

2. Inspect result$cortical_labels and result$subcortical_labels. If the automatic split is wrong, either add a type column to the LUT or use cortical_labels / subcortical_labels to override.

3. Run the full pipeline once you are satisfied with the split.

4. Visually inspect the resulting atlas with ggseg() / ggseg3d().

The cortical surface projection uses FreeSurfer's cortex label (⁠{hemi}.cortex.label⁠) to prevent label dilation into the medial wall. This file ships with fsaverage5 and is always required.

Examples

## Not run: 
# --- Recommended: LUT with type column ---
lut <- data.frame(
  idx   = c(10, 11, 49, 50, 101:148),
  label = c("Left-Thalamus", "Left-Caudate",
            "Right-Thalamus", "Right-Caudate",
            paste0("cortical_region_", 1:48)),
  type  = c(rep("subcortical", 4), rep("cortical", 48)),
  R = sample(50:220, 52, TRUE),
  G = sample(50:220, 52, TRUE),
  B = sample(50:220, 52, TRUE),
  A = 255L
)

result <- create_wholebrain_from_volume(
  input_volume = "my_atlas.nii.gz",
  input_lut = lut,
  atlas_name = "my_atlas"
)
result$cortical   # surface-based cortical atlas
result$subcortical # mesh-based subcortical atlas

# --- Without type column: automatic classification ---
result <- create_wholebrain_from_volume(
  input_volume = "atlas.nii.gz",
  input_lut = "atlas_LUT.txt",
  atlas_name = "auto_atlas"
)

# --- Inspect classification before full run ---
result <- create_wholebrain_from_volume(
  input_volume = "atlas.nii.gz",
  input_lut = "atlas_LUT.txt",
  steps = 1:2
)
result$cortical_labels
result$subcortical_labels

## End(Not run)

Description

Reads a FreeSurfer color lookup table and adds hex colour codes for use in plotting.

Usage

get_ctab(color_lut)

Arguments

Value

A data.frame with the original columns plus roi (zero-padded index) and color (hex colour code).

See Also

read_ctab(), is_ctab()

Examples

ct <- data.frame(
  idx = 0:1, label = c("Unknown", "Region1"),
  R = c(0L, 205L), G = c(0L, 130L), B = c(0L, 176L), A = c(0L, 0L)
)
get_ctab(ct)

Description

Returns the verbosity level from option, environment variable, or default. Checks in order: ggseg.extra.verbose option, GGSEG_EXTRA_VERBOSE env var, then defaults to 1L.

Usage

get_verbose()

Details

Verbosity levels:

• 0 — Silent: no console output

• 1 — Standard (default): pipeline progress and step summaries

• 2 — Debug: includes FreeSurfer command output

Logical values are accepted for backward compatibility (FALSE = 0, TRUE = 1).

Value

Integer 0L, 1L, or 2L

Examples

get_verbose()
options(ggseg.extra.verbose = 0)
get_verbose()
options(ggseg.extra.verbose = NULL)

Description

Check if object is a color table

Usage

is_ctab(x)

Arguments

Value

TRUE if x is a data.frame with the required color table columns.

Examples

ct <- data.frame(
  idx = 0L, label = "Unknown",
  R = 0L, G = 0L, B = 0L, A = 0L
)
is_ctab(ct)
is_ctab(data.frame(x = 1))

Description

Get verbosity level

Usage

is_verbose(verbose = NULL)

Arguments

Value

Integer 0L, 1L, or 2L

Examples

is_verbose()
is_verbose(FALSE)
is_verbose(2)

Description

Annotation files are subject specific. Most are registered for fsaverage, but we recommend using fsaverage5 for the mesh plots in ggseg3d, as these contain a decent balance in number of vertices for detailed rendering and speed.

Usage

mri_surf2surf_rereg(
  subject,
  annot,
  hemi = c("lh", "rh"),
  target_subject = "fsaverage5",
  output_dir = file.path(freesurfer::fs_subj_dir(), subject, "label"),
  verbose = get_verbose()
)

Arguments

Value

nothing

Examples

## Not run: 
# For help see:
freesurfer::fs_help("mri_surf2surf")

mri_surf2surf_rereg(
  subject = "bert",
  annot = "aparc.DKTatlas",
  target_subject = "fsaverage5"
)

## End(Not run)

Description

Reads FreeSurfer annotation files and extracts region information including vertices, colours, and labels for both hemispheres.

Usage

read_annotation_data(annot_files)

Arguments

Value

A tibble with columns: hemi, region, label, colour, vertices

Examples

## Not run: 
atlas_data <- read_annotation_data(c(
  "path/to/lh.aparc.annot",
  "path/to/rh.aparc.annot"
))

## End(Not run)

Description

Reads a CIFTI dense label file (.dlabel.nii) and extracts region information for both hemispheres. Returns data in the same format as read_annotation_data() for use with the cortical atlas pipeline.

Usage

read_cifti_annotation(cifti_file)

Arguments

Details

The CIFTI file must be in fsaverage5 space (10,242 vertices per hemisphere). If your file uses a different resolution, resample it first with Connectome Workbench:

wb_command -cifti-resample input.dlabel.nii ...

Value

A tibble with columns: hemi, region, label, colour, vertices

Examples

## Not run: 
atlas_data <- read_cifti_annotation("parcellation.dlabel.nii")

## End(Not run)

Description

Read a FreeSurfer color lookup table file (e.g., FreeSurferColorLUT.txt or ASegStatsLUT.txt). These files map label indices to region names and RGBA colours.

Usage

read_ctab(path)

Arguments

Value

A data.frame with columns: idx, label, R, G, B, A.

See Also

get_ctab() to read and add hex colours, write_ctab() to write

Examples

ctab_file <- tempfile()
writeLines(c(
  "  0  Unknown                         0   0   0   0",
  "  1  Left-Cerebral-Cortex          205 130 176   0"
), ctab_file)
read_ctab(ctab_file)

Description

Reads GIFTI annotation (.label.gii) files and extracts region information including vertices, colours, and labels. Returns data in the same format as read_annotation_data() for use with the cortical atlas pipeline.

Usage

read_gifti_annotation(gifti_files)

Arguments

Details

Hemisphere is detected from filename patterns: lh., rh., .L., .R.

Value

A tibble with columns: hemi, region, label, colour, vertices

Examples

## Not run: 
atlas_data <- read_gifti_annotation(c(
  "lh.aparc.label.gii",
  "rh.aparc.label.gii"
))

## End(Not run)

Description

Reads neuromaps GIFTI metric files (.func.gii) and converts them to the standard annotation format used by the cortical atlas pipeline.

Usage

read_neuromaps_annotation(gifti_files, label_table = NULL, n_bins = NULL)

Arguments

Details

Automatically detects whether data contains integer parcel IDs (parcellation) or continuous values (brain map). For parcellations, vertex value 0 is treated as medial wall. For continuous data, NaN vertices are medial wall and values are discretized into quantile bins via n_bins.

Files must be in fsaverage5 space (10,242 vertices per hemisphere). Use space = "fsaverage" with density = "10k" when fetching from neuromaps.

Value

A tibble with columns: hemi, region, label, colour, vertices

Examples

## Not run: 
files <- neuromapr::fetch_neuromaps_annotation(
  "abagen", "genepc1", "fsaverage", density = "10k"
)
atlas_data <- read_neuromaps_annotation(files, n_bins = 7)

## End(Not run)

Description

Projects an MNI152-space NIfTI volume onto the fsaverage5 surface via FreeSurfer's mri_vol2surf, then discretizes the projected per-vertex values using the same binning logic as read_neuromaps_annotation().

Usage

read_neuromaps_volume(nifti_file, n_bins = NULL, output_dir = tempdir())

Arguments

Value

A tibble with columns: hemi, region, label, colour, vertices

Examples

## Not run: 
atlas_data <- read_neuromaps_volume("map.nii.gz", n_bins = 7)

## End(Not run)

Description

Load streamlines from a tractography file. Supports TrackVis (.trk) and MRtrix (.tck) formats. The file format is detected from the extension.

Usage

read_tractography(file)

Arguments

Value

A list of matrices, one per streamline. Each matrix has N rows (points along the streamline) and 3 columns (x, y, z coordinates).

See Also

read_trk(), read_tck() for format-specific readers

Examples

## Not run: 
streamlines <- read_tractography("bundle.trk")

## End(Not run)

Description

Scaffold an R package for distributing a brain atlas. The generated package follows ggseg conventions and includes everything you need: template scripts for atlas creation, documentation stubs, a test suite, and GitHub Actions for automated checking.

Usage

setup_atlas_repo(
  path,
  atlas_name = NULL,
  open = rlang::is_interactive(),
  rstudio = TRUE
)

Arguments

Details

The package will be named ⁠ggseg{AtlasName}⁠ (e.g., ggsegSchaefer for a Schaefer parcellation). After creation, edit the files in ⁠data-raw/⁠ to build your atlas, then run devtools::document() and devtools::check().

Value

Invisibly returns the path to the created package.

Examples

## Not run: 
# Create atlas package in a new directory
setup_atlas_repo("ggsegDkt", "dkt")

# Create in current directory, derive name from path
setup_atlas_repo("ggsegMyatlas")

# Specify full path
setup_atlas_repo("~/projects/ggsegSchaefer", "schaefer")

# Without opening in RStudio
setup_atlas_repo("ggsegHarvard", "harvard", open = FALSE)

## End(Not run)

Description

Performs diagnostic checks to verify that system dependencies and environment variables required by ggseg.extra are properly configured.

Usage

setup_sitrep(detail = c("simple", "full"))

Arguments

Value

Invisibly returns a list with check results.

Examples

setup_sitrep()
setup_sitrep("full")

Description

Write a color table to file in FreeSurfer format.

Usage

write_ctab(x, path)

Arguments

Value

Invisibly returns the lines written.

See Also

read_ctab(), is_ctab()

Examples

ct <- data.frame(
  idx = 0:1, label = c("Unknown", "Region1"),
  R = c(0L, 205L), G = c(0L, 130L), B = c(0L, 176L), A = c(0L, 0L)
)
out <- tempfile()
write_ctab(ct, out)