Resolve metadata for a BIDS file — get

Retrieves JSON metadata for a target BIDS file. When inherit = TRUE, this method applies BIDS-style inheritance by merging matching sidecars from less specific to more specific locations.

Usage

get_metadata(
  x,
  file,
  inherit = TRUE,
  scope = c("auto", "raw", "derivatives", "all"),
  provenance = FALSE,
  ...
)

# S3 method for class 'bids_project'
get_metadata(
  x,
  file,
  inherit = TRUE,
  scope = c("auto", "raw", "derivatives", "all"),
  provenance = FALSE,
  ...
)

Arguments

x

A bids_project object.

file

Target file path (relative to project root or absolute path).

inherit

If TRUE, merge inherited metadata from parent sidecars.

scope

Scope used when applying inheritance:

"auto": infer from file location
"raw": raw data inheritance
"derivatives": derivatives inheritance
"all": allow full project ancestry

provenance

If TRUE, return list(metadata = ..., sources = ...), where sources records the ordered sidecar paths, inheritance levels, precedence, and fields used to resolve the effective metadata. The default FALSE preserves the historical metadata-list return value.

...

Additional arguments for methods.

Value

A named list of metadata fields, or a metadata/provenance object when provenance = TRUE.

Details

If multiple sidecars are equally specific at the same directory depth, they are merged in deterministic path order after less specific ancestors, so the final values are reproducible.

Examples

# \donttest{
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  f <- func_scans(proj, subid = "01")[1]
  if (!is.null(f)) get_metadata(proj, f)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) message("Example requires internet: ", e$message))
#> $RepetitionTime
#> [1] 2
#> 
#> $TaskName
#> [1] "balloon analog risk task"
#> 
# }