Build Cluster Explorer Data

Compute sign-aware volumetric connected components from a statistic map, annotate them with atlas parcels, and extract cluster-level 4D signal summaries aligned to sample rows.

Usage

build_cluster_explorer_data(
  data_source,
  atlas,
  stat_map,
  sample_table = NULL,
  threshold = 3,
  min_cluster_size = 20,
  connectivity = c("26-connect", "18-connect", "6-connect"),
  tail = c("two_sided", "positive", "negative"),
  signal_fun = mean,
  signal_fun_args = list(na.rm = TRUE),
  series_fun = NULL,
  prefetch = TRUE,
  prefetch_max_clusters = Inf,
  prefetch_max_voxels = Inf,
  series_cache_env = NULL
)

Arguments

data_source

A sample-wise data source supporting neuroim2::series(data_source, i) where i is voxel coordinates (n x 3 matrix) or indices. Rows of the returned matrix correspond to samples/design rows.

atlas

A volumetric atlas object used for parcel annotation. When atlas and stat_map dimensions differ, the atlas is automatically resampled to stat_map space (nearest-neighbor labels) before cluster annotation.

stat_map

A NeuroVol statistic image used for thresholding and clustering.

sample_table

Optional data frame with one row per sample. If NULL, a default table with .sample_index is created.

threshold

Numeric threshold used for cluster formation.

min_cluster_size

Minimum number of voxels required to keep a cluster.

connectivity

Connectivity passed to neuroim2::conn_comp().

tail

Clustering mode: "positive", "negative", or "two_sided".

signal_fun

Function used to summarize cluster signal per sample.

signal_fun_args

Named list of additional arguments passed to signal_fun.

series_fun

Optional function override for extracting voxel-wise sample series. Must accept (data_source, i) and return a matrix-like object with one row per sample.

prefetch

Logical; if TRUE, precompute signal summaries for all clusters on recompute.

prefetch_max_clusters

Maximum clusters allowed for eager prefetch. Prefetch is skipped when exceeded.

prefetch_max_voxels

Maximum total cluster voxels allowed for eager prefetch. Prefetch is skipped when exceeded.

series_cache_env

Optional environment used to memoize voxel-coordinates-to-series extraction across cluster computations.

Value

A list with:

cluster_table

Cluster summary tibble.

cluster_parcels

Cluster-parcel overlap tibble.

cluster_ts

Sample-level cluster signal tibble.

cluster_voxels

Named list of voxel coordinate matrices by cluster ID.

cluster_index

A NeuroVol of global cluster IDs.

sample_table

Normalized sample table with .sample_index.

prefetch_info

List describing whether eager signal prefetch was requested/applied and the effective guard thresholds.

Examples

grid <- neuroim2::NeuroSpace(c(2, 1, 1))
volume <- neuroim2::NeuroVol(array(c(1, 2), c(2, 1, 1)), grid)
atlas <- structure(
  list(
    atlas = volume, ids = 1:2,
    labels = c("A", "B"), orig_labels = c("A", "B"),
    hemi = c("left", "right"), name = "toy",
    cmap = rbind(c(1, 0, 0), c(0, 0, 1)),
    atlas_ref = new_atlas_ref("toy", "two-regions",
      template_space = "MNI152NLin6Asym", coord_space = "MNI152"
    )
  ),
  class = "atlas"
)
samples <- array(rep(c(0.2, 0.7), 3), c(2, 1, 1, 3))
data_source <- neuroim2::NeuroVec(
  samples, neuroim2::NeuroSpace(dim(samples))
)
stat_map <- neuroim2::NeuroVol(array(c(4, 5), c(2, 1, 1)), grid)
clusters <- build_cluster_explorer_data(data_source, atlas, stat_map,
  threshold = 3, min_cluster_size = 1, tail = "positive"
)
#> Warning: clustered volume only contains 1 partition
clusters$cluster_table
#> # A tibble: 1 × 12
#>   cluster_id sign     component_id n_voxels peak_x peak_y peak_z max_stat
#>   <chr>      <chr>           <int>    <int>  <int>  <int>  <int>    <dbl>
#> 1 P1         positive            1        2      2      1      1        5
#> # ℹ 4 more variables: peak_coord <chr>, atlas_label_primary <chr>,
#> #   n_parcels <int>, parcel_overlap <dbl>