Convert GDS assay to list of NeuroVol objects

Extract a single assay from a GDS object and return it as a list of neuroim2::NeuroVol objects, one per subject/contrast combination.

Usage

as_neurovol_list(
  x,
  assay = "beta",
  by = c("subject", "contrast"),
  drop_dim = TRUE
)

Arguments

x

A GDS object with a voxel space.

assay

Name of the assay to extract (default: "beta").

by

How to organize the output list. One of:

• "subject": list indexed by subject, each element is a NeuroVol (only works when there's a single contrast)

• "contrast": list indexed by contrast, each element is a NeuroVol (only works when there's a single subject)

drop_dim

If TRUE (default), drop singleton dimensions when extracting. If FALSE, always return a nested list structure.

Value

A named list of neuroim2::NeuroVol objects. The structure depends on the by parameter and the dimensions of the data:

• Single contrast, by = "subject": list of NeuroVol named by subject

• Single subject, by = "contrast": list of NeuroVol named by contrast

• Multiple of both: nested list [[subject]][[contrast]]

Examples

if (requireNamespace("neuroim2", quietly = TRUE)) {
  sp4 <- neuroim2::NeuroSpace(c(4, 4, 2, 4), spacing = c(2, 2, 2))
  vec4d <- neuroim2::NeuroVec(array(rnorm(128), c(4, 4, 2, 4)), sp4)
  gds <- as_gds(vec4d, along = "subject", subjects = paste0("sub0", 1:4))

  # Extract beta maps as list of NeuroVols (one per subject)
  vols <- as_neurovol_list(gds, assay = "beta")
  print(names(vols))
  print(vols$sub01)  # NeuroVol for subject "sub01"

  # Extract by contrast (here: one subject with three contrasts)
  sp3 <- neuroim2::NeuroSpace(c(4, 4, 2, 3), spacing = c(2, 2, 2))
  vec_con <- neuroim2::NeuroVec(array(rnorm(96), c(4, 4, 2, 3)), sp3)
  gds_con <- as_gds(vec_con, along = "contrast",
                    contrasts = c("faces", "places", "objects"))
  vols_by_con <- as_neurovol_list(gds_con, assay = "beta", by = "contrast")
  print(names(vols_by_con))
}
#> [1] "sub01" "sub02" "sub03" "sub04"
#> <DenseNeuroVol> [7 Kb] 
#> ── Spatial ───────────────────────────────────────────────────────────────────── 
#>   Dimensions    : 4 x 4 x 2
#>   Spacing       : 2 x 2 x 2 mm
#>   Origin        : 0, 0, 0
#>   Orientation   : RAS
#> ── Data ──────────────────────────────────────────────────────────────────────── 
#>   Range         : [-1.713, 1.827]
#> [1] "faces"   "places"  "objects"