Title:	Spatial Null Models and Transforms for Brain Map Comparison
Version:	0.2.1
Description:	Implements spatial null models and coordinate-space transformations for statistical comparison of brain maps, following the framework described in Markello et al. (2022) <doi:10.1038/s41592-022-01625-w>. Provides variogram-matching surrogates (Burt et al. 2020), Moran spectral randomization (Wagner & Dray 2015), and spin-based permutation tests (Alexander-Bloch et al. 2018). Includes an R interface to the 'neuromaps' annotation registry for browsing, downloading, and comparing brain map annotations from the Open Science Framework ('OSF'). Integrates with 'ciftiTools' for coordinate-space transforms.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
Config/testthat/edition:	3
Config/testthat/parallel:	true
Depends:	R (≥ 4.2.0)
Imports:	cli, dplyr, ggplot2, gifti, httr2, igraph, lifecycle, rlang, stats, tibble, tools, withr
Suggests:	ciftiTools, clue, freesurferformats, jsonlite, knitr, rmarkdown, RNifti, RSpectra, testthat (≥ 3.0.0), vcr (≥ 1.0.0)
VignetteBuilder:	knitr
URL:	https://github.com/lcbc-uio/neuromapr, https://lcbc-uio.github.io/neuromapr/, https://doi.org/10.5281/zenodo.18648937
BugReports:	https://github.com/lcbc-uio/neuromapr/issues
NeedsCompilation:	no
Packaged:	2026-02-22 20:26:24 UTC; athanasm
Author:	Athanasia Mo Mowinckel [aut, cre, cph]
Maintainer:	Athanasia Mo Mowinckel <a.m.mowinckel@psykologi.uio.no>
Repository:	CRAN
Date/Publication:	2026-02-27 16:20:02 UTC

Convert FreeSurfer annotation to GIFTI

Description

Reads a FreeSurfer .annot file and writes a GIFTI label file.

Usage

annot_to_gifti(annot_path, output_path = NULL)

Arguments

Value

The output file path (invisibly).

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

## Not run: 
annot_to_gifti("lh.aparc.annot")
annot_to_gifti("lh.aparc.annot", "lh.aparc.label.gii")

## End(Not run)

Check for Connectome Workbench

Description

Verifies that wb_command is available. If wb_path is NULL, checks ciftiTools default and system PATH.

Usage

check_wb_command(wb_path = NULL)

Arguments

Value

Path to wb_command executable.

Examples

## Not run: 
check_wb_command()

## End(Not run)

Clear cached neuromaps registry data

Description

Removes the session-level cache of the neuromaps annotation registry, forcing a fresh download on the next call to neuromaps_available() or fetch_neuromaps_annotation().

Usage

clear_neuromaps_cache()

Value

NULL, invisibly.

Examples

clear_neuromaps_cache()

Compare brain maps with spatial null model significance testing

Description

Computes the correlation between two brain maps and optionally tests significance using a spatial null model to account for spatial autocorrelation.

Usage

compare_maps(
  x,
  y,
  method = c("pearson", "spearman"),
  null_method = NULL,
  n_perm = 1000L,
  nulls = NULL,
  distmat = NULL,
  coords = NULL,
  seed = NULL,
  na.rm = TRUE,
  verbose = TRUE,
  ...
)

## S3 method for class 'neuromaps_enhanced_comparison'
print(x, ...)

Arguments

Value

A neuromaps_enhanced_comparison object (inherits neuromaps_comparison) with additional fields p_null, null_method, null_r, and n_perm.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

x <- rnorm(50)
y <- x + rnorm(50)
compare_maps(x, y, verbose = FALSE)

Download a neuromaps annotation

Description

Download brain map annotation files from the neuromaps OSF repository. Surface annotations return two files (left and right hemispheres), volume annotations return one.

Usage

fetch_neuromaps_annotation(
  source,
  desc,
  space,
  density = NULL,
  resolution = NULL,
  hemisphere = NULL,
  data_dir = neuromaps_cache_dir(),
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Character vector of downloaded file path(s).

Examples

fetch_neuromaps_annotation("abagen", "genepc1", "fsaverage", density = "10k")

Convert FreeSurfer morphometry to GIFTI

Description

Reads a FreeSurfer morphometry file (.curv, .thickness, .sulc) and writes a GIFTI func file.

Usage

fsmorph_to_gifti(morph_path, output_path = NULL)

Arguments

Value

The output file path (invisibly).

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

## Not run: 
fsmorph_to_gifti("lh.thickness")
fsmorph_to_gifti("lh.thickness", "lh.thickness.func.gii")

## End(Not run)

Generate null distributions for brain map data

Description

Dispatches to the appropriate null model method for generating spatially-constrained surrogate brain maps.

Usage

generate_nulls(
  data,
  method = c("burt2020", "moran", "spin_vasa", "spin_hungarian", "alexander_bloch",
    "baum", "cornblath", "burt2018"),
  n_perm = 1000L,
  distmat = NULL,
  coords = NULL,
  parcellation = NULL,
  seed = NULL,
  ...
)

Arguments

Value

A null_distribution object.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

data <- rnorm(100)
distmat <- as.matrix(dist(seq_len(100)))
nd <- generate_nulls(data, method = "moran", distmat = distmat, n_perm = 10L)

Compute parcel centroids

Description

Finds the centroid of each parcel using one of three methods.

Usage

get_parcel_centroids(
  vertices,
  labels,
  method = c("average", "surface", "geodesic"),
  faces = NULL
)

Arguments

Value

Numeric matrix (n_parcels x 3) with rownames set to parcel labels.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

vertices <- matrix(rnorm(30), ncol = 3)
labels <- c(1L, 1L, 1L, 2L, 2L, 2L, 3L, 3L, 3L, 3L)
get_parcel_centroids(vertices, labels, method = "average")

Compute geodesic distances on a surface mesh

Description

Builds a graph from a triangular mesh and computes shortest-path (Dijkstra) distances between vertices.

Usage

get_surface_distance(vertices, faces, source_vertices = NULL)

Arguments

Value

Numeric distance matrix. If source_vertices is provided, returns a ⁠length(source_vertices) x n⁠ matrix; otherwise an ⁠n x n⁠ matrix.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

vertices <- matrix(
  c(0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1),
  nrow = 4, byrow = TRUE
)
faces <- matrix(c(1L, 2L, 3L, 2L, 3L, 4L), nrow = 2, byrow = TRUE)
get_surface_distance(vertices, faces)

Build an igraph from a triangular surface mesh

Description

Extracts unique edges from triangular faces, computes Euclidean edge weights, and returns an igraph graph object suitable for geodesic distance computation.

Usage

make_surf_graph(vertices, faces)

Arguments

Value

An igraph graph object with weighted edges.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

vertices <- matrix(
  c(0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1),
  nrow = 4, byrow = TRUE
)
faces <- matrix(c(1L, 2L, 3L, 2L, 3L, 4L), nrow = 2, byrow = TRUE)
g <- make_surf_graph(vertices, faces)

List available neuromaps annotations

Description

Query the neuromaps registry to see which brain map annotations are available for download. Data is fetched from the neuromaps project's GitHub repository and cached for the session.

Usage

neuromaps_available(
  source = NULL,
  desc = NULL,
  space = NULL,
  density = NULL,
  resolution = NULL,
  hemisphere = NULL,
  tags = NULL,
  format = NULL,
  refresh = FALSE,
  fixed = FALSE
)

Arguments

Details

All string filter parameters (source, desc, space, density, resolution, hemisphere, format) are treated as R regular expressions and matched with grepl(). For example, source = "^beliveau$" matches exactly, while source = "bel" matches any source containing "bel". Set fixed = TRUE for literal string matching. The tags parameter always uses exact matching (AND logic).

When used in fetch_neuromaps_annotation(), source, desc, and space are exact matches.

Value

A tibble of available annotations with columns: source, desc, space, den, res, hemi, format, fname, full_desc, tags, N, age.

Examples

neuromaps_available()
neuromaps_available(source = "beliveau")
neuromaps_available(tags = "pet")

Alexander-Bloch spin test null model

Description

Original vertex-level spin test: rotates coordinates and assigns each rotated vertex the value of its nearest original vertex (no optimal matching).

Usage

null_alexander_bloch(
  data,
  coords,
  n_perm = 1000L,
  seed = NULL,
  rotation = c("euler", "rodrigues")
)

Arguments

Value

A null_distribution object.

References

Alexander-Bloch AF et al. (2018) NeuroImage 175:111-120. doi:10.1016/j.neuroimage.2018.04.023

Examples

coords <- list(lh = matrix(rnorm(30), 10, 3), rh = matrix(rnorm(30), 10, 3))
data <- rnorm(20)
nd <- null_alexander_bloch(data, coords, n_perm = 10L, seed = 1L)

Baum spin test null model

Description

Spin-based null model with maximum-overlap parcel reassignment. After rotating vertex coordinates, each original parcel is assigned the value of the rotated parcel with the most vertex overlap.

Usage

null_baum(
  data,
  coords,
  parcellation,
  n_perm = 1000L,
  seed = NULL,
  rotation = c("euler", "rodrigues")
)

Arguments

Value

A null_distribution object.

References

Baum GL et al. (2020) PNAS 117:21854-21861. doi:10.1073/pnas.2005518117

Examples

coords <- list(lh = matrix(rnorm(30), 10, 3), rh = matrix(rnorm(30), 10, 3))
parcellation <- c(rep(1L, 5), rep(2L, 5), rep(3L, 5), rep(4L, 5))
data <- c(1.0, 2.0, 3.0, 4.0)
nd <- null_baum(data, coords, parcellation, n_perm = 10L, seed = 1L)

Burt 2018 spatial autoregressive null model

Description

Generates surrogate brain maps using a spatial autoregressive (SAR) model. Estimates spatial autocorrelation and distance decay parameters, then generates surrogates by solving the SAR equation and rank-matching to the original data.

Usage

null_burt2018(data, distmat, n_perm = 1000L, seed = NULL)

Arguments

Value

A null_distribution object.

References

Burt JB et al. (2018) Nature Neuroscience 21:1251-1259. doi:10.1038/s41593-018-0195-0

Examples

data <- rnorm(50)
distmat <- as.matrix(dist(matrix(rnorm(100), 50, 2)))
nd <- null_burt2018(data, distmat, n_perm = 10L, seed = 1L)

Variogram-matching null model

Description

Generates spatially-constrained surrogate brain maps by matching the empirical variogram of the original data through smoothed random permutations.

Usage

null_burt2020(
  data,
  distmat,
  n_perm = 1000L,
  seed = NULL,
  ns = 500L,
  nh = 25L,
  pv = 25,
  knn = 1000L,
  deltas = seq(0.1, 0.9, by = 0.1),
  kernel = c("exponential", "gaussian", "uniform"),
  resample = FALSE
)

Arguments

Value

A null_distribution object.

References

Burt JB et al. (2020) NeuroImage 220:117038. doi:10.1016/j.neuroimage.2020.117038

Examples

data <- rnorm(50)
distmat <- as.matrix(dist(matrix(rnorm(100), 50, 2)))
nd <- null_burt2020(data, distmat, n_perm = 10L, seed = 1L)

Cornblath spin test null model

Description

Spin-based null model where each rotated vertex receives the label of its nearest non-medial-wall original vertex, then parcels are reassigned by majority vote among the resulting vertex labels.

Usage

null_cornblath(
  data,
  coords,
  parcellation,
  n_perm = 1000L,
  seed = NULL,
  rotation = c("euler", "rodrigues")
)

Arguments

Value

A null_distribution object.

References

Cornblath EJ et al. (2020) Communications Biology 3:590. doi:10.1038/s42003-020-01296-5

Examples

coords <- list(lh = matrix(rnorm(30), 10, 3), rh = matrix(rnorm(30), 10, 3))
parcellation <- c(rep(1L, 5), rep(2L, 5), rep(3L, 5), rep(4L, 5))
data <- c(1.0, 2.0, 3.0, 4.0)
nd <- null_cornblath(data, coords, parcellation, n_perm = 10L, seed = 1L)

Create a null distribution object

Description

Create a null distribution object

Usage

new_null_distribution(nulls, method, observed, params = list())

## S3 method for class 'null_distribution'
print(x, ...)

## S3 method for class 'null_distribution'
summary(object, ...)

## S3 method for class 'null_distribution'
as.matrix(x, ...)

## S3 method for class 'null_distribution'
plot(x, parcel = 1L, ...)

Arguments

Value

A null_distribution object.

Examples

nulls <- matrix(rnorm(30), nrow = 3, ncol = 10)
nd <- new_null_distribution(nulls, "test", observed = c(1, 2, 3))
print(nd)
summary(nd)

Moran spectral randomization null model

Description

Generates spatially-constrained surrogate brain maps using Moran's eigenvector maps (MEMs) for spectral randomization.

Usage

null_moran(
  data,
  distmat,
  n_perm = 1000L,
  seed = NULL,
  procedure = c("pair", "singleton"),
  kernel = c("inverse_distance", "exponential", "gaussian", "bisquare"),
  tol = 1e-06
)

Arguments

Value

A null_distribution object.

References

Wagner HH, Dray S (2015) Methods in Ecology and Evolution 6:1169-1178. doi:10.1111/2041-210X.12407

Examples

data <- rnorm(50)
distmat <- as.matrix(dist(matrix(rnorm(100), 50, 2)))
nd <- null_moran(data, distmat, n_perm = 10L, seed = 1L)

Spin-test null models for brain maps

Description

Generate spatially-constrained null distributions using spin-based permutation of spherical coordinates.

Usage

null_spin_vasa(
  data,
  coords,
  n_perm = 1000L,
  seed = NULL,
  rotation = c("euler", "rodrigues")
)

null_spin_hungarian(
  data,
  coords,
  n_perm = 1000L,
  seed = NULL,
  rotation = c("euler", "rodrigues")
)

Arguments

Value

A null_distribution object.

References

Alexander-Bloch AF et al. (2018) NeuroImage 175:111-120. doi:10.1016/j.neuroimage.2018.04.023

Vasa F et al. (2018) Cerebral Cortex 28:3293-3303. doi:10.1093/cercor/bhx195

Markello RD, Misic B (2021) NeuroImage 236:118052. doi:10.1016/j.neuroimage.2021.118052

Examples

coords <- list(lh = matrix(rnorm(30), 10, 3), rh = matrix(rnorm(30), 10, 3))
data <- rnorm(20)
nd <- null_spin_vasa(data, coords, n_perm = 10L, seed = 1L)

Parcellate brain map data

Description

High-level wrapper that reads data and parcellation from file paths or vectors, then aggregates vertices into parcels.

Usage

parcellate(data, parcellation, summary_func = mean)

Arguments

Value

Named numeric vector of parcel-level values.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

data <- c(1.0, 2.0, 3.0, 4.0)
labels <- c(1L, 1L, 2L, 2L)
parcellate(data, labels)

Map parcel data back to vertices

Description

Expands parcel-level values to a vertex-level vector using parcellation labels.

Usage

parcels_to_vertices(parcel_data, labels, fill = NA_real_)

Arguments

Value

Numeric vector of length(labels).

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

parcel_data <- c("1" = 10, "2" = 20)
labels <- c(1L, 1L, 2L, 2L, 0L)
parcels_to_vertices(parcel_data, labels)

Permutation test for any metric between brain maps

Description

Computes a user-specified metric between two vectors and tests significance using either spatially-constrained null surrogates or simple random permutation.

Usage

permtest_metric(
  x,
  y,
  metric_func = stats::cor,
  n_perm = 1000L,
  seed = NULL,
  null_method = NULL,
  distmat = NULL,
  coords = NULL,
  parcellation = NULL,
  ...
)

Arguments

Value

List with ⁠$observed⁠, ⁠$null_values⁠, ⁠$p_value⁠, and ⁠$n_perm⁠.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

x <- rnorm(100)
y <- x + rnorm(100)
result <- permtest_metric(x, y, n_perm = 99L, seed = 1L)
result$observed
result$p_value

Read vertex/voxel values from a brain map file

Description

Reads GIFTI (.func.gii) or NIfTI (.nii.gz) files and returns the values as a numeric vector. Used internally by compare_maps() when file paths are passed instead of numeric vectors.

Usage

read_brain_map_values(path)

Arguments

Value

A numeric vector of map values.

Examples

## Not run: 
read_brain_map_values("cortical_thickness.func.gii")
read_brain_map_values("brain_volume.nii.gz")

## End(Not run)

Resample brain maps for comparison

Description

Aligns two brain maps into the same coordinate space and density before comparison. Supports multiple strategies for choosing the target space.

Usage

resample_images(
  src,
  trg,
  src_space = c("fsaverage", "fsLR"),
  trg_space = c("fsaverage", "fsLR"),
  strategy = c("downsample_only", "transform_to_src", "transform_to_trg",
    "transform_to_alt"),
  alt_space = NULL,
  alt_density = NULL,
  hemisphere = c("left", "right"),
  area_surf_current = NULL,
  area_surf_new = NULL,
  wb_path = NULL,
  verbose = TRUE
)

Arguments

Value

List with ⁠$src⁠ and ⁠$trg⁠ file paths in the aligned space.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

## Not run: 
resample_images("src.func.gii", "trg.func.gii",
  src_space = "fsaverage", trg_space = "fsaverage"
)

## End(Not run)

Transform brain maps between coordinate spaces

Description

Resamples GIFTI surface files between fsaverage and fsLR coordinate spaces using Connectome Workbench via ciftiTools.

Usage

transform_to_space(
  paths,
  target_space = c("fsLR", "fsaverage"),
  target_density = "32k",
  hemisphere = c("left", "right"),
  method = c("adaptive", "barycentric"),
  area_surf_current = NULL,
  area_surf_new = NULL,
  wb_path = NULL,
  verbose = TRUE
)

Arguments

Value

Character vector of transformed file paths.

References

Robinson EC et al. (2014) NeuroImage 100:414-426. doi:10.1016/j.neuroimage.2014.07.033

Robinson EC et al. (2018) NeuroImage 167:150-165. doi:10.1016/j.neuroimage.2017.10.037

Examples

## Not run: 
transform_to_space("map.func.gii", target_space = "fsLR")

## End(Not run)

Unparcellate brain map data

Description

Inverse of parcellate(): maps parcel-level values back to vertices.

Usage

unparcellate(parcel_data, parcellation, fill = NA_real_)

Arguments

Value

Numeric vector of vertex-level values.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

parcel_data <- c("1" = 10, "2" = 20)
labels <- c(1L, 1L, 2L, 2L, 0L)
unparcellate(parcel_data, labels)

Compute per-vertex surface areas

Description

Each triangle distributes one-third of its area to each of its three vertices. Triangle area is computed via the cross-product formula.

Usage

vertex_areas(vertices, faces)

Arguments

Value

Numeric vector of length nrow(vertices).

Examples

vertices <- matrix(c(0, 1, 0, 0, 0, 1, 0, 0, 0), nrow = 3, byrow = TRUE)
faces <- matrix(c(1L, 2L, 3L), nrow = 1)
vertex_areas(vertices, faces)

Aggregate vertex data into parcels

Description

Summarises vertex-level data by parcellation labels.

Usage

vertices_to_parcels(data, labels, summary_func = mean)

Arguments

Value

Named numeric vector of parcel-level values.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

data <- c(1.0, 2.0, 3.0, 4.0)
labels <- c(1L, 1L, 2L, 2L)
vertices_to_parcels(data, labels)