Create GDS from nested structure of NeuroVol objects

The most flexible import function for creating GDS objects from neuroim2 data. Supports multiple subjects and multiple contrasts, with proper variance/SE handling.

Usage

gds_from_neurovol_nested(
  beta,
  var = NULL,
  se = NULL,
  contrasts = NULL,
  mask = NULL,
  col_data = NULL,
  metadata = list(),
  ...
)

Arguments

beta

A nested list structure for beta/effect estimates. Can be:

• Nested list: list(subject1 = list(con1 = vol, con2 = vol), ...)

• List of 4D NeuroVec: list(subject1 = vec4d, subject2 = vec4d, ...) where each NeuroVec has contrasts along the 4th dimension

var

Optional matching structure for variance estimates.

se

Optional matching structure for standard errors (alternative to var).

contrasts

Character vector of contrast names. Required when using NeuroVec inputs; inferred from inner list names otherwise.

mask

Optional mask. See as_gds.NeuroVol for options.

col_data

Optional data frame of subject-level covariates.

metadata

Optional list of additional metadata to attach.

...

Additional arguments passed to new_gds().

Value

A gds object with dimensions samples x subjects x contrasts.

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp <- neuroim2::NeuroSpace(c(4, 4, 2), spacing = c(2, 2, 2))
  make_vol <- function(x) neuroim2::NeuroVol(array(x, c(4, 4, 2)), sp)
  subj <- c("sub-01", "sub-02")

  # Example 1: Nested list structure (subjects x contrasts)
  beta <- lapply(stats::setNames(subj, subj), function(s)
    list(faces = make_vol(rnorm(32)), places = make_vol(rnorm(32))))
  var <- lapply(stats::setNames(subj, subj), function(s)
    list(faces = make_vol(runif(32, 0.5, 1.5)),
         places = make_vol(runif(32, 0.5, 1.5))))

  gds_obj <- gds_from_neurovol_nested(beta, var = var)
  print(gds_obj)

  # Example 2: List of 4D NeuroVecs (each subject has a multi-contrast 4D image)
  sp4 <- neuroim2::NeuroSpace(c(4, 4, 2, 3), spacing = c(2, 2, 2))
  beta_vecs <- lapply(stats::setNames(subj, subj), function(s)
    neuroim2::NeuroVec(array(rnorm(96), c(4, 4, 2, 3)), sp4))
  # Without variance maps a unit-variance placeholder is used (with a warning)
  gds_obj <- gds_from_neurovol_nested(beta_vecs,
                                      contrasts = c("faces", "places", "objects"))
  print(contrasts(gds_obj))
}
#> GDS
#>   dims: 32 x 2 x 2 [sample x subject x contrast]
#>   space: voxel dim=4x4x2, storage=packed
#>   subjects: 2 (sub-01, sub-02)
#>   contrasts: 2 (faces, places)
#>   assays: beta[location], var[variance]
#> Warning: No variance or SE provided; using unit variance as a synthetic placeholder. This is only valid for unweighted reducers such as method = "ols:voxelwise" (e.g. one_sample()/group_ols()); variance-weighted reducers (fixed/random/meta:*) will refuse it. Supply real SE (e.g. nifti_source(se = ...)) for meta-analysis.
#> [1] "faces"   "places"  "objects"