Query files in BIDS structure with explicit semantics

This function provides a stricter, more explicit querying interface than search_files(), with support for exact-vs-regex entity matching, optional entity-existence requirements, and raw/derivatives scope selection.

Usage

query_files(x, ...)

# S3 method for class 'bids_project'
query_files(
  x,
  regex = ".*",
  full_path = FALSE,
  match_mode = c("regex", "exact", "glob"),
  require_entity = FALSE,
  scope = c("all", "raw", "derivatives"),
  pipeline = NULL,
  return = c("paths", "tibble"),
  use_index = c("auto", "never"),
  strict = TRUE,
  refresh = FALSE,
  ...
)

# S3 method for class 'mock_bids_project'
query_files(
  x,
  regex = ".*",
  full_path = FALSE,
  match_mode = c("regex", "exact", "glob"),
  require_entity = FALSE,
  scope = c("all", "raw", "derivatives"),
  pipeline = NULL,
  return = c("paths", "tibble"),
  use_index = c("auto", "never"),
  strict = TRUE,
  refresh = FALSE,
  ...
)

Arguments

x

A bids_project or mock_bids_project object.

...

Additional entity filters (e.g., subid = "01", task = "rest", extension = ".nii.gz", datatype = "func"). The special filters extension and datatype are handled post-hoc and support the same matching modes as other entities.

regex

A regular expression applied to filenames. Default is ".*".

full_path

If TRUE, return full paths. If FALSE, return paths relative to the dataset root.

match_mode

Matching mode for entity filters in ...:

• "regex": values are treated as regex patterns (default)

• "exact": values are treated as exact string matches

• "glob": values are shell-style globs (e.g., "sub-0*")

require_entity

If TRUE, queried entity keys must be present on a file for it to match. If FALSE, wildcard patterns can match files where that entity is missing.

scope

Which dataset scope to query:

• "all": raw + derivatives

• "raw": raw data only

• "derivatives": derivatives only

pipeline

Optional derivative pipeline name(s) used when scope = "derivatives" or scope = "all".

return

Whether to return matching file paths ("paths") or a tibble with parsed entities ("tibble").

use_index

Whether to use a persisted file index when available:

• "auto": use a cached index if present

• "never": always query the in-memory tree

strict

Passed through to search methods. If TRUE, missing queried entities typically fail matching (except wildcard behavior in legacy paths).

refresh

If FALSE (default), reuse the index built when the project was created without re-scanning the filesystem, which makes repeated queries fast (comparable to an indexed lookup). Set TRUE to re-scan the manifest paths and re-stat files, picking up additions, content changes, and removals without rebuilding the project object.

Value

A character vector of matching files, a tibble of indexed rows (sorted by subid, session, task, run, path), or NULL if no matches are found.

Examples

# \donttest{
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path, fmriprep = FALSE)

  # Exact entity matching for reproducible filters in new workflows
  exact_bold <- query_files(
    proj,
    regex = "bold\\.nii\\.gz$",
    subid = "01",
    task = "balloonanalogrisktask",
    match_mode = "exact"
  )

  # Regex entity matching when selecting multiple runs or tasks
  regex_bold <- query_files(
    proj,
    regex = "bold\\.nii\\.gz$",
    subid = "0[12]",
    task = "balloon.*|mixedgamblestask",
    match_mode = "regex"
  )

  # Require task labels to actually exist on the matched files
  task_annotated <- query_files(
    proj,
    regex = "\\.nii\\.gz$",
    task = ".*",
    require_entity = TRUE,
    scope = "raw"
  )

  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})
# }
# \donttest{
tryCatch({
  deriv_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj_deriv <- bids_project(deriv_path, fmriprep = TRUE)

  deriv_only <- query_files(
    proj_deriv,
    regex = "bold\\.nii\\.gz$",
    desc = "preproc",
    scope = "derivatives",
    pipeline = "fmriprep",
    match_mode = "exact"
  )

  all_scopes <- query_files(
    proj_deriv,
    regex = "bold\\.nii\\.gz$",
    scope = "all",
    return = "tibble"
  )

  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires derivatives dataset: ", e$message)
})
#> Example requires derivatives dataset: participants.tsv is missing
# }