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 |
palette |
character
Color palette for mapping values and the colorbar. Options include
|
value_range |
numeric length-2 or NULL (default
|
save_dir |
character or NULL (default |
measure |
character What to 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. |
... |
Advanced options:
|
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))
# )