Discover image files and create a catalog

Sweeps a directory tree for files matching a glob pattern and extracts metadata from file paths using regex capture groups.

Usage

image_catalog(root, pattern = "**/*.nii*", path_regex = NULL, recursive = TRUE)

Arguments

root

Root directory to search.

pattern

Glob pattern for file discovery (e.g., "sub-*/analysis/*.nii.gz"). Supports * for single directory level and ** for recursive matching.

path_regex

Optional regex with named capture groups for metadata extraction. Named groups like (?<subject>[^/]+) become metadata columns.

recursive

Whether to search subdirectories. Default TRUE. Only used if pattern does not contain **.

Value

An image_catalog object.

Examples

# Create a small study tree (empty placeholder files are enough for discovery)
root <- tempfile("study_")
for (s in c("01", "02", "03")) {
  d <- file.path(root, paste0("sub-", s), "analysis")
  dir.create(d, recursive = TRUE)
  invisible(file.create(file.path(d, c("cope1.nii.gz", "varcope1.nii.gz"))))
}

# Discover files with subject extraction
catalog <- image_catalog(
  root = root,
  pattern = "sub-*/analysis/*.nii.gz",
  path_regex = "sub-(?<subject>[^/]+)"
)
catalog
#> Image Catalog
#>   Files: 6
#>   Root: /tmp/Rtmp17Odxi/study_1cec2c99d30b
#>   Pattern: sub-*/analysis/*.nii.gz
#>   Metadata columns: subject
#>   Subjects: 3 (01, 02, 03)
catalog$metadata[, c("basename", "subject")]
#>          basename subject
#> 1    cope1.nii.gz      01
#> 2 varcope1.nii.gz      01
#> 3    cope1.nii.gz      02
#> 4 varcope1.nii.gz      02
#> 5    cope1.nii.gz      03
#> 6 varcope1.nii.gz      03

unlink(root, recursive = TRUE)