Search files in BIDS structure — search

This function searches for files in a BIDS project that match a specified pattern and optional key-value criteria. It can be used to find files in both raw data and preprocessed derivatives based on filename patterns and BIDS metadata.

This function searches for files in a BIDS project that match a specified pattern and optional key-value criteria. It can search in both raw data and preprocessed derivatives (if available).

Usage

search_files(x, ...)

# S3 method for class 'bids_project'
search_files(x, regex = ".*", full_path = FALSE, strict = TRUE, ...)

Arguments

x: A bids_project object.
...: Additional key-value pairs to filter files (e.g., subid = "01", task = "wm"). These are matched against the corresponding metadata in the BIDS files.
regex: A regular expression to match against filenames. Default is ".*" (all files).
full_path: If TRUE, return full file paths. If FALSE, return paths relative to the project root.
strict: If TRUE, require that all queried keys must exist in matched files. If FALSE, allow matches for files missing queried keys.

Value

A character vector of file paths matching the criteria, or NULL if no matches found.

Examples

# \donttest{
# Search for event files in a BIDS dataset  
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path, fmriprep=FALSE)
  event_files <- search_files(proj, regex="events\\.tsv$")
  
  # Search with additional criteria
  sub01_files <- search_files(proj, regex="bold\\.nii\\.gz$", subid="01", 
                              task="balloonanalogrisktask")
  
  # Get full paths
  full_paths <- search_files(proj, regex="events\\.tsv$", full_path=TRUE)
  
  # Search with strict matching
  strict_matches <- search_files(proj, regex="\\.tsv$", strict=TRUE, 
                                 task="balloonanalogrisktask")
  
  # Clean up
  unlink(ds001_path, recursive=TRUE)
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})
# }
# \donttest{
# Search for event files in a BIDS dataset
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path, fmriprep=FALSE)
  event_files <- search_files(proj, regex="events\\.tsv$")
  
  # Search with additional criteria (note: ds001 only has one subject '01')
  sub01_files <- search_files(proj, regex="bold\\.nii\\.gz$", subid="01", 
                              task="balloonanalogrisktask")
  
  # Get full paths
  full_paths <- search_files(proj, regex="events\\.tsv$", full_path=TRUE)
  
  # Clean up
  unlink(ds001_path, recursive=TRUE)
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})
# }