Plot vertex-wise coefficient maps on a 3D cortical surface

Locates the vertex-wise coefficient MGH files for a given model term and surface measure, optionally applies cluster-wise significance (CWS) masking, and renders the result on a standard fsaverage surface via plot_vw_surf().

Surface maps are loaded directly in R using load.mgh() without any Python dependency at the file-loading stage. The Python/nilearn rendering backend is invoked only through plot_vw_surf().

Usage

plot_vw_map(
  res_dir,
  term,
  measure = "area",
  hemi = c("both", "lh", "rh"),
  surface = c("pial", "inflated"),
  threshold = "cws",
  ...
)

Arguments

res_dir

Character. Path to the directory containing FreeSurfer-style vertex-wise result files (*.mgh) and stack_names.txt.

term

Character. Name of the model term to visualize (matched against entries in stack_names.txt).

measure

Character. Surface measure to load, e.g. "area", "thickness", "volume". Default "area".

hemi

Character. Which hemisphere(s) to plot: "both" (default), "lh" or "rh".

surface

Character. Surface mesh: "pial" (default) or "inflated".

threshold

Controls vertex-level masking before plotting:

"cws" (default)

Cluster-wise significant. Loads the matching *.cache.*.sig.ocn.mgh file and masks all vertices not belonging to a significant cluster. If no OCN file is found, the unmasked coefficients are plotted with a warning.

"fdr <= 0.05" or "p < 0.01" etc

FDR or P values below a threshold. Loads the matching *.fdr.mgh or *.p.mgh file and masks all vertices not meeting the rule. If no file is found, the unmasked coefficients are plotted with a warning.

Numeric

Absolute-value threshold (vertices with |value| < threshold are hidden).

NULL

No masking; all vertices are rendered.

...

Additional arguments forwarded to plot_vw_surf(), e.g. roi_outline, views, cmap, vmin, vmax, colorbar, colorbar_label, title, to_file, dpi, fs_home, fs_template.

Value

Invisibly: the output of plot_vw_surf() — the temp HTML file path (interactive mode) or to_file path (static PNG mode). Called primarily for its side-effect of opening or saving the figure.

See also

plot_vw_surf(), plot_vw_diff()

Examples

if (FALSE) { # rlang::is_installed("reticulate") && dir.exists("~/results/fs_results")
# Both hemispheres, interctive plot, cluster-wise masking (default)
plot_vw_map(
  res_dir = "~/results/fs_results",
  term    = "age",
  measure = "thickness"
)

# Left hemisphere only, numeric threshold, save to PNG
plot_vw_map(
  res_dir   = "~/results/fs_results",
  term      = "age",
  hemi      = "lh",
  threshold = 0.05,
  to_file   = "figures/age_lh.png",
  dpi       = 300L
)

# No masking, custom colour map and title
plot_vw_map(
  res_dir   = "~/results/fs_results",
  term      = "sex",
  threshold = NULL,
  cmap      = "RdBu_r",
  title     = "Sex difference in cortical area"
)
}