Return per-file NeuroVecs for preproc scans

Author: bbuchsbaum

NEWS.md

@@ -1,5 +1,16 @@
 # bidser 0.4.0
 
+* Change `read_preproc_scans()` to return a file-ordered list of `NeuroVec`
+  objects, one per matched preprocessed scan, instead of collapsing multiple
+  files into a single container.
+* Fix derivative discovery and legacy fMRIPrep helpers for datasets that place
+  derivative subject folders directly under `derivatives/` with
+  `prep_dir = "derivatives"`.
+* Make `read_confounds()` raise informative, selection-aware errors when no
+  matching participants, confound files, or usable requested confounds are
+  found.
+* Fix `create_preproc_mask()` to ignore matching JSON sidecars and only read
+  actual NIfTI mask images.
 * Add `query_files()` as the recommended explicit query API for new workflows,
   with `match_mode`, `require_entity`, and raw/derivatives `scope` controls.
 * Add `get_metadata()` for inheritance-aware BIDS metadata resolution with

R/bidsio.R

@@ -55,7 +55,8 @@ read_func_scans.bids_project <- function(x, mask, mode = c("normal", "bigvec"),
 #'
 #' This function reads preprocessed functional MRI scans from a BIDS project's fMRIPrep
 #' derivatives directory. It uses the \code{preproc_scans} function to locate the files
-#' and then reads them into a \code{NeuroVec} object using the neuroim2 package. If a
+#' and then reads each one into its own \code{NeuroVec} object using the
+#' neuroim2 package. If a
 #' mask is not provided, one will be automatically created from available brainmask files.
 #'
 #' @param x A \code{bids_project} object with fMRIPrep derivatives
@@ -67,7 +68,8 @@ read_func_scans.bids_project <- function(x, mask, mode = c("normal", "bigvec"),
 #' @param modality Image modality to match (default: "bold" for functional MRI)
 #' @param ... Extra arguments passed to \code{neuroim2::read_vec}
 #' 
-#' @return An instance of type \code{NeuroVec} containing the preprocessed functional data.
+#' @return A named list of \code{NeuroVec} objects, one per matched preprocessed
+#'   scan, in file order.
 #' 
 #' @details
 #' This function requires the \code{neuroim2} package to be installed. It will throw an
@@ -100,6 +102,7 @@ read_func_scans.bids_project <- function(x, mask, mode = c("normal", "bigvec"),
 #'   # Provide a custom mask
 #'   mask <- create_preproc_mask(proj, thresh=0.95)
 #'   masked_scans <- read_preproc_scans(proj, mask=mask)
+#'   first_run <- masked_scans[[1]]
 #'   
 #'   # Clean up
 #'   unlink(ds_path, recursive=TRUE)
@@ -138,7 +141,11 @@ read_preproc_scans.bids_project <- function(x, mask=NULL, mode = c("normal", "bi
     stop("Package 'neuroim2' is required for this function. Install with: remotes::install_github('bbuchsbaum/neuroim2')", call. = FALSE)
   }
 
-  neuroim2::read_vec(fnames, mask=mask, mode=mode, ...)
+  scans <- lapply(fnames, function(fname) {
+    neuroim2::read_vec(fname, mask=mask, mode=mode, ...)
+  })
+  names(scans) <- fnames
+  scans
 }
 
 

tests/testthat/test_read_preproc_scans.R

@@ -0,0 +1,74 @@
+context("read_preproc_scans.bids_project")
+library(testthat)
+library(bidser)
+
+create_read_preproc_fixture <- function() {
+  tmp <- tempfile("bidser_read_preproc_")
+  dir.create(tmp, recursive = TRUE)
+
+  readr::write_tsv(
+    tibble::tibble(participant_id = "sub-01"),
+    file.path(tmp, "participants.tsv")
+  )
+  jsonlite::write_json(
+    list(Name = "ReadPreproc", BIDSVersion = "1.8.0"),
+    file.path(tmp, "dataset_description.json"),
+    auto_unbox = TRUE
+  )
+
+  dir.create(file.path(tmp, "sub-01", "func"), recursive = TRUE)
+  file.create(file.path(tmp, "sub-01", "func", "sub-01_task-rest_run-01_bold.nii.gz"))
+  file.create(file.path(tmp, "sub-01", "func", "sub-01_task-rest_run-02_bold.nii.gz"))
+
+  deriv_root <- file.path(tmp, "derivatives", "fmriprep", "sub-01", "func")
+  dir.create(deriv_root, recursive = TRUE)
+  jsonlite::write_json(
+    list(
+      Name = "fmriprep",
+      BIDSVersion = "1.8.0",
+      DatasetType = "derivative",
+      GeneratedBy = list(list(Name = "fmriprep", Version = "test"))
+    ),
+    file.path(tmp, "derivatives", "fmriprep", "dataset_description.json"),
+    auto_unbox = TRUE
+  )
+
+  bold_arr <- array(seq_len(2 * 2 * 2 * 3), dim = c(2, 2, 2, 3))
+  mask_arr <- array(1, dim = c(2, 2, 2))
+
+  for (run in c("01", "02")) {
+    RNifti::writeNifti(
+      bold_arr,
+      file.path(
+        deriv_root,
+        paste0("sub-01_task-rest_run-", run, "_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz")
+      )
+    )
+    RNifti::writeNifti(
+      mask_arr,
+      file.path(
+        deriv_root,
+        paste0("sub-01_task-rest_run-", run, "_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz")
+      )
+    )
+  }
+
+  tmp
+}
+
+test_that("read_preproc_scans returns one NeuroVec per matched file", {
+  skip_if_not_installed("RNifti")
+  skip_if_not_installed("neuroim2")
+
+  tmp <- create_read_preproc_fixture()
+  on.exit(unlink(tmp, recursive = TRUE, force = TRUE), add = TRUE)
+
+  proj <- bids_project(tmp, fmriprep = TRUE, index = "none")
+  fnames <- preproc_scans(proj, subid = "01", task = "rest", full_path = TRUE)
+  scans <- bidser:::read_preproc_scans.bids_project(proj, subid = "01", task = "rest")
+
+  expect_type(scans, "list")
+  expect_length(scans, 2)
+  expect_equal(names(scans), fnames)
+  expect_true(all(vapply(scans, inherits, logical(1), "NeuroVec")))
+})