sulcimap (version 1.0.6)

plot_sulci: Plot sulcal measures on brain

Description

Generates composite brain figures (left/right lateral/medial) by mapping sulcal values.

Usage

plot_sulci(
  sulcus_values,
  palette = "gyr",
  value_range = NULL,
  save_dir = NULL,
  measure = c("all", "opening", "depth", "surface", "length"),
  show_colorbar = TRUE,
  caption = expression(-log[10](p)),
  ...
)

Value

If save_dir = NULL, returns a ggplot (or patchwork) object representing the brain figure, which can be further modified and saved. If save_dir is not NULL, the plot image(s) are automatically saved in that directory and the function (invisibly) returns a character vector with the path(s) to the saved file(s).

Arguments

sulcus_values

data.frame or path/to/csv Either (1) a two-column dataframe with Sulcus and Value, or (2) a path to a CSV file containing those columns. Sulcus must use BrainVISA-style tags (left/right, 4 types) and include all expected names. Missing sulcus should have Value = 0 (see README and data samples).

palette

character Color palette for mapping values and the colorbar. Options include "viridis", "magma", "plasma", "inferno", "cividis", "heat", "gyr".

value_range

numeric length-2 or NULL (default NULL) Controls the color scale.

• NULL: auto-scale from the min/max of the provided values.

• c(min, max): fix the scale across plots/conditions for comparability.

save_dir

character or NULL (default NULL) Directory where the plot image(s) are saved. If it does not exist, it will be created. Set to NULL to skip saving and only return the plot object.

measure

character What to plot:

• "all": generate all four measures in one figure.

• "opening", "depth", "surface", "length": generate a single-measure plot.

show_colorbar

logical Show or hide the color bar on the figure.

caption

character or expression Label displayed with the color bar. For math, use e.g. expression(-log[10](p)).

...

Advanced options: base_dir (path to assets), scale_width (magick scale, default "1000x"), file_prefix (default "sulci"), width_in, height_in (inches; defaults 14, 8), dpi (default 300).

Examples

# Minimal executable example using assets_light
ex <- data.frame(
  Sulcus = c("S.C._left.opening", "S.C._right.opening",
  "S.F.int._left.opening", "S.F.int._right.opening"),
  Value  = c(1, 0.5, 0.8, 0.4)
)
assets_light <- sulcimap::get_assets_light()
p <- plot_sulci(
  sulcus_values = ex,
  measure       = "opening",
  palette       = "gyr",
  show_colorbar = FALSE,
  base_dir      = assets_light,
  save_dir      = NULL
)
# p is a ggplot/patchwork object; printing it will draw the figure.

# \donttest{
# Full example
# df should have columns: Sulcus (BrainVISA-style names with suffixes), Value
# plot_out <- plot_sulci(
#  sulcus_values = df,
#    palette       = "gyr",
#   value_range   = NULL,
#  save_dir      = NULL,
#    measure       = "opening",
#    show_colorbar = TRUE,
#    caption       = expression(-log[10](p))
# )
# }