Title: Mapping Brain Folding Patterns
Version: 1.0.4
Maintainer: Mahan Shafie <mahan.shafie@unito.it>
Description: Visualizes sulcal morphometry data derived from 'BrainVisa' https://brainvisa.info/ including width, depth, surface area, and length. The package enables mapping of statistical group results or subject-level values onto cortical surface maps, with options to focus on all sulci or only selected regions of interest. Users can display all four measures simultaneously or restrict plots to chosen measures, creating composite, publication-quality brain visualizations in R to support the analysis and interpretation of sulcal morphology.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 4.0)
Imports: utils, tools, magick, ggplot2, viridisLite, scales, patchwork, cowplot, grid, grDevices
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2025-09-30 10:46:05 UTC; mahan
Author: Mahan Shafie [aut, cre]
Repository: CRAN
Date/Publication: 2025-10-06 08:10:02 UTC

sulcimap: Mapping Brain Folding Patterns

Description

Visualizes sulcal morphometry data derived from 'BrainVisa' https://brainvisa.info/ including width, depth, surface area, and length. The package enables mapping of statistical group results or subject-level values onto cortical surface maps, with options to focus on all sulci or only selected regions of interest. Users can display all four measures simultaneously or restrict plots to chosen measures, creating composite, publication-quality brain visualizations in R to support the analysis and interpretation of sulcal morphology.

Author(s)

Maintainer: Mahan Shafie mahan.shafie@unito.it

Ensure bundled assets are available locally (unzips on first use)

Description

Ensure bundled assets are available locally (unzips on first use)

Usage

.ensure_sulcimap_assets()

Value

Path to the directory containing extracted assets

Clear sulcimap cached assets

Description

Clear sulcimap cached assets

Usage

clear_sulcimap_cache()

Value

Logical TRUE if cache removed or did not exist

Lightweight assets for light example Unzips a tiny assets bundle and returns the directory path.

Description

Lightweight assets for light example Unzips a tiny assets bundle and returns the directory path.

Usage

get_assets_light()

Value

A character scalar: path to the unzipped assets directory.

Path to sulcimap extracted asset directory

Description

This will unzip the bundled assets into a per-user cache the first time it is called then return the cache path on subsequent calls

Usage

get_sulcimap_assets_dir()

Value

Character scalar: full path to the root of extracted assets

Full path to a bundled PNG (after extraction)

Description

Full path to a bundled PNG (after extraction)

Usage

get_sulcus_image(name)

Arguments

name

Relative path inside the assets

Value

Character scalar: full path

List bundled PNGs (after extraction)

Description

List bundled PNGs (after extraction)

Usage

list_sulci_images()

Value

Character vector of relative PNG paths

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)),
  ...
)

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).

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).

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.


# 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))
# )