Package 'bidser'

Description

Anatomical parser constructor

Usage

anat_parser()

Value

An anatomical BIDS parser object for parsing anatomical files

Examples

# Create an anatomical parser
parser <- anat_parser()

# Parse an anatomical file
result <- parse(parser, "sub-01_T1w.nii.gz")

Description

Coerce to a BIDS URI object

Usage

as_bids_uri(x, ...)

## S3 method for class 'character'
as_bids_uri(x, ...)

## S3 method for class 'bids_uri'
as_bids_uri(x, ...)

Arguments

Value

A bids_uri object.

Examples

u <- as_bids_uri("bids::sub-01/anat/sub-01_T1w.nii.gz")
u$dataset_name   # ""
u$relative_path  # "sub-01/anat/sub-01_T1w.nii.gz"

Description

This function performs a simple, lightweight check of common BIDS requirements:

• Checks that participants.tsv and dataset_description.json exist at the root.

• Ensures all subject directories begin with ⁠sub-⁠.

• If sessions are present, ensures that session directories begin with ⁠ses-⁠.

Usage

bids_check_compliance(x, schema_check = TRUE, schema_version = "1.10.0")

bids_check_compliance(x, schema_check = TRUE, schema_version = "1.10.0")

Arguments

Details

Note: This is not a full BIDS validator. For complete validation, use the official BIDS validator.

Value

A list with compliance check results including passed, issues, warnings, participants_source, and schema_checked.

A list with:

• passed (logical): TRUE if all checks passed, FALSE otherwise.

• issues (character vector): Descriptions of any issues found.

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  compliance <- bids_check_compliance(proj)

  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Constructs a parser_spec list suitable for passing to register_datatype. Standard BIDS entity keys are recognised automatically and filled with canonical regex patterns and ordering; unknown keys fall back to [A-Za-z0-9]+ and are appended after standard ones.

Usage

bids_datatype_spec(
  type,
  entities = c("sub", "ses"),
  required = "sub",
  suffixes = list()
)

Arguments

Value

A parser_spec list with elements keystruc, kinds, and type, ready for gen_parser and register_datatype.

Examples

spec <- bids_datatype_spec(
  type     = "dwi",
  entities = c("sub", "ses", "acq", "run"),
  suffixes = list(
    dwi   = c(".nii.gz", ".nii", ".bvec", ".bval", ".json"),
    sbref = c(".nii.gz", ".nii")
  )
)
## Not run: 
register_datatype("dwi", spec = spec, parser_fn = gen_parser(spec),
                  folder = "dwi", scope = "raw")

## End(Not run)

Description

This function creates a heatmap visualization of a BIDS project, where the x-axis represents subjects and the y-axis represents tasks by run. Each cell in the heatmap is colored by file size, providing an intuitive view of data completeness and size distribution across the project. This is particularly useful for quality control and identifying missing data.

Usage

bids_heatmap(
  x,
  interactive = TRUE,
  color_scheme = "viridis",
  file_type = "func",
  highlight_missing = TRUE,
  text_size = 2.5,
  rotate_labels = TRUE
)

Arguments

Value

A plot object (ggplot2 or plotly depending on interactive parameter)

Examples

# Create a basic interactive heatmap for a BIDS dataset
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  bids_heatmap(proj)
  
  # Create a static heatmap with custom settings
  bids_heatmap(proj, 
               interactive = FALSE,
               color_scheme = "plasma",
               text_size = 3,
               rotate_labels = FALSE)
  
  # Visualize anatomical data with missing data highlighted
  bids_heatmap(proj, 
               file_type = "anat",
               highlight_missing = TRUE,
               color_scheme = "magma")
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Creates a lightweight on-disk index of files and parsed BIDS entities. The index is stored as an RDS file and does not change user-facing query semantics; it simply provides a cached tabular representation of the project.

Usage

bids_index(x, rebuild = FALSE, persist = TRUE)

Arguments

Value

A tibble describing indexed files.

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  idx <- bids_index(proj, persist = FALSE)
  print(idx)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) message("Example requires internet: ", e$message))

Description

These functions create parsers for different types of BIDS files using regex-based pattern matching instead of parser combinators. Create a parser for a generic BIDS file

Usage

bids_parser()

Details

This parser tries to match against various known parsers (anat, func, fmriprep anat/func).

Value

A BIDS parser object that can parse various types of BIDS files

Examples

# Create a generic BIDS parser
parser <- bids_parser()

# Parse different types of files
anat_result <- parse(parser, "sub-01_T1w.nii.gz")
func_result <- parse(parser, "sub-01_task-rest_bold.nii.gz")
prep_result <- parse(parser, "sub-01_task-rest_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz")

Description

This function creates a BIDS project object from a directory containing BIDS-formatted neuroimaging data. It can optionally load preprocessed derivatives from fMRIPrep. The function validates the basic BIDS structure and provides methods for accessing raw and preprocessed data, querying subjects, sessions, and tasks, reading event files, and checking BIDS compliance.

Usage

bids_project(
  path = ".",
  fmriprep = FALSE,
  prep_dir = "derivatives/fmriprep",
  strict_participants = TRUE,
  derivatives = c("auto", "legacy", "none"),
  pipelines = NULL,
  index = c("auto", "none"),
  index_path = NULL
)

Arguments

Value

A bids_project object representing the BIDS project structure. The object provides methods for:

• Accessing raw and preprocessed data files

• Querying subjects, sessions, and tasks

• Reading event files and confound regressors

• Checking BIDS compliance

• Extracting metadata from file names Returns NULL if the directory does not contain a valid BIDS dataset.

Examples

# Create a BIDS project
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  
  # Get all functional scans
  all_scans <- func_scans(proj)
  
  # Get scans for specific subjects
  sub_scans <- func_scans(proj, subid="0[123]")
  
  # Get scans for a specific task
  task_scans <- func_scans(proj, task="rest")
  
  # Get scans from specific runs
  run_scans <- func_scans(proj, run="0[123]")
  
  # Combine multiple filters
  filtered_scans <- func_scans(proj,
                              subid="01",
                              task="rest",
                              run="01")
  
  # Get relative paths instead of full paths
  rel_scans <- func_scans(proj, full_path=FALSE)
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Create a lightweight text report for a BIDS project

Usage

bids_report(x, ...)

Arguments

Value

An object of class bids_report.

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  rpt <- bids_report(proj)
  print(rpt)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) message("Example requires internet: ", e$message))

Description

Produces a structured report payload composed from dataset summary, compliance checks, derivative pipeline discovery, and run-level variables coverage.

Usage

bids_report_data(x, ...)

Arguments

Value

A list with report-ready summary tables and metadata.

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  rd <- bids_report_data(proj)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) message("Example requires internet: ", e$message))

Description

Loads the vendored BIDS JSON schema and caches the result in the package environment so repeated calls within a session are free.

Usage

bids_schema(version = "1.10.0")

Arguments

Value

A named list representing the compiled schema with top-level keys objects, rules, meta, etc.

See Also

bids_schema_versions

Examples

s <- bids_schema()
names(s)

Description

Returns the version strings for all BIDS schema JSON files shipped with this installation of bidser.

Usage

bids_schema_versions()

Value

Character vector of available version strings (e.g. "1.10.1").

Examples

bids_schema_versions()

Description

bids_subject returns a lightweight interface with helper functions for retrieving data associated with one subject.

bids_subject returns a lightweight facade that exposes convenience functions to work with all data associated with one subject within a BIDS project.

This function extracts a single subject's data from a BIDS project, creating a new BIDS project object containing only that subject's files and metadata.

Usage

bids_subject(x, subid, ...)

bids_subject.bids_project(x, subid, ...)

bids_subject(x, subid, ...)

Arguments

Value

A list of helper functions for the subject.

A list containing subject-specific helper functions. Each function automatically filters results for the specified subject. The returned object contains the following callable functions:

events(...)

Returns nested tibble with event data for this subject. Equivalent to read_events(project, subid = "XX", ...). Additional arguments (task, session, run, nest, etc.) can be passed.

event_files(...)

Returns character vector of event file paths for this subject. Equivalent to event_files(project, subid = "XX", ...). Additional arguments (task, session, run, full_path, etc.) can be passed.

scans(...)

Returns character vector of functional scan file paths for this subject. Equivalent to func_scans(project, subid = "XX", ...). Additional arguments (task, session, run, kind, full_path, etc.) can be passed.

confounds(...)

Returns confound data for this subject (requires fMRIPrep derivatives). Equivalent to read_confounds(project, subid = "XX", ...). Additional arguments (task, session, run, cvars, npcs, etc.) can be passed.

preproc_scans(...)

Returns preprocessed scan paths for this subject (requires fMRIPrep derivatives). Equivalent to preproc_scans(project, subid = "XX", ...). Additional arguments (task, session, run, space, variant, etc.) can be passed.

brain_mask(...)

Creates brain mask for this subject (requires fMRIPrep derivatives). Equivalent to brain_mask(project, subid = "XX", ...). Additional arguments (thresh, etc.) can be passed.

A new bids_project object containing only the specified subject's data. Returns NULL if the subject is not found in the project.

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  subj <- bids_subject(proj, "01")
  subj$events()
  subj$scans()
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})


tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  
  # Create subject interface for subject 01
  subj <- bids_subject(proj, "01")
  
  # Get functional scan paths for this subject
  scan_paths <- subj$scans()
  print(paste("Subject 01 has", length(scan_paths), "functional scans"))
  
  # Get event file paths for this subject
  event_paths <- subj$event_files()
  print(paste("Subject 01 has", length(event_paths), "event files"))
  
  # Read event data for this subject
  event_data <- subj$events()
  print("Event data structure:")
  print(event_data)
  
  # You can still pass additional filtering arguments
  # For example, get only specific tasks:
  task_scans <- subj$scans(task = "balloonanalogrisktask")
  
  # Dataset cache is intentionally retained for performance.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})


# Create a subject interface
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  
  # Create subject interface for subject 01  
  subj <- bids_subject(proj, "01")
  
  # Use the helper functions
  scans <- subj$scans()
  events <- subj$event_files()
  print(paste("Subject 01:", length(scans), "scans,", length(events), "events"))
  
  # Dataset cache is intentionally retained for performance.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Provides a quick summary of dataset statistics, including:

• Number of subjects

• Number of sessions (if applicable)

• Available tasks and the number of runs per task

• Total number of runs

Usage

bids_summary(x)

bids_summary(x)

Arguments

Value

A list containing summary statistics about the BIDS dataset

A list with summary information:

• n_subjects: number of participants

• n_sessions: number of sessions (if any), otherwise NULL

• tasks: a data frame with task and n_runs columns

• total_runs: total number of runs across the dataset

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  summary <- bids_summary(proj)
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

This function orchestrates the process of selecting files from a BIDS project, applying a transformation to each file, and saving the output in a new BIDS derivative directory. It leverages the existing bidser parsing and search infrastructure.

Usage

bids_transform(x, transformer, pipeline_name, ...)

Arguments

Value

A character vector of paths to the newly created files.

Examples

tryCatch({
  ds_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds_path)

  # Create a simple transformer that adds a description
  add_desc_transformer <- function(infile, outdir) {
    entities <- encode(basename(infile))
    entities$desc <- if (is.null(entities$desc)) "smooth6mm" else 
                     paste(entities$desc, "smooth6mm", sep="")
    
    # Generate new filename
    new_name <- decode_bids_entities(entities)
    outfile <- file.path(outdir, new_name)
    
    # For demo, just copy the file (real transformer would process it)
    file.copy(infile, outfile)
    return(outfile)
  }

  # Apply transformation to functional files for subject 01
  new_files <- bids_transform(proj, add_desc_transformer, "smoothed",
                              subid = "01", suffix = "bold.nii.gz")
  print(length(new_files))

}, error = function(e) {
  message("Example failed: ", e$message)
})

Description

Parses a BIDS URI string of the form ⁠bids:<dataset_name>:<relative_path>⁠ and returns an S3 object of class bids_uri.

Usage

bids_uri(uri)

Arguments

Value

An object of class bids_uri with fields dataset_name, relative_path, and uri.

Examples

u <- bids_uri("bids::sub-01/func/sub-01_task-rest_bold.nii.gz")
u$dataset_name   # ""
u$relative_path  # "sub-01/func/sub-01_task-rest_bold.nii.gz"

# URI with a named dataset link
u2 <- bids_uri("bids:deriv1:sub-01/anat/sub-01_T1w.nii.gz")
u2$dataset_name  # "deriv1"

Description

Get the BIDS version of a dataset

Usage

bids_version(x, ...)

## S3 method for class 'bids_project'
bids_version(x, ...)

## S3 method for class 'mock_bids_project'
bids_version(x, ...)

## S3 method for class 'bids_dataset_description'
bids_version(x, ...)

Arguments

Value

A character scalar BIDS version string, or NA_character_.

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  desc <- read_dataset_description(ds001_path)
  bids_version(desc)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) message("Example requires internet: ", e$message))

Description

This convenience function wraps create_preproc_mask() and returns a brain mask volume for a given subject.

Usage

brain_mask(x, subid, ...)

## S3 method for class 'bids_project'
brain_mask(x, subid, ...)

Arguments

Value

A logical mask volume

Examples

# Download and load a BIDS project with fMRIPrep derivatives
tryCatch({
  ds001_deriv_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds001_deriv_path, fmriprep=TRUE)
  mask <- brain_mask(proj, subid="01")
  
  # Create mask for multiple subjects
  multi_mask <- brain_mask(proj, subid=".*")
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires derivatives dataset: ", e$message)
})

Description

Creates a structured list or tibble containing all available data for a single subject, organized by data type. This provides a comprehensive view of all available files for a subject, useful for batch processing and pipeline ingestion.

Usage

build_subject_graph(x, subid, session = ".*", flatten = FALSE, ...)

## S3 method for class 'bids_project'
build_subject_graph(x, subid, session = ".*", flatten = FALSE, ...)

## S3 method for class 'mock_bids_project'
build_subject_graph(x, subid, session = ".*", flatten = FALSE, ...)

Arguments

Value

If flatten = FALSE (default), a named list with class bids_subject_graph:

subid

Subject identifier (without "sub-" prefix)

sessions

Character vector of available sessions

epi

Named list of preprocessed EPI file paths, keyed by task.run

anat

List with t1w and masks sublists

transforms

Named list of transform files, keyed by from_to_to format

surfaces

Nested list by space, then hemisphere (L/R)

confounds

Character vector of confound file paths

If flatten = TRUE, a tibble with columns:

file_type

Type of file (epi, anat, transform, surface, confound)

path

File path

subid, session, task, run, space, hemi, from, to

BIDS metadata

Examples

# Build subject graph
tryCatch({
  ds_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds_path, fmriprep = TRUE)

  # Get nested structure
  graph <- build_subject_graph(proj, "01")
  names(graph)

  # Get flat tibble
  flat <- build_subject_graph(proj, "01", flatten = TRUE)
  head(flat)

  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

check_confounds() reports nuisance columns that are unsuitable for model matrices, such as zero-variance columns within a run. clean_confounds() drops the flagged columns and stores the diagnostics on the returned object.

Usage

check_confounds(x, checks = c("zero_variance", "rank"), group_vars = NULL)

clean_confounds(
  x,
  clean = c("zero_variance", "rank"),
  group_vars = NULL,
  inform = TRUE
)

Arguments

Details

These helpers understand both nested bids_confounds objects returned by read_confounds(..., nest = TRUE) and flat confound tables. For flat tables, checks are run within the identifier columns present in the data (participant_id, task, session, and run by default).

Value

check_confounds() returns a tibble of diagnostics. clean_confounds() returns x with flagged columns removed and a confound_diagnostics attribute containing the same diagnostic rows.

Examples

df <- tibble::tibble(
  participant_id = "01",
  task = "rest",
  run = "01",
  cosine00 = c(1, 0, -1),
  cosine01 = c(0, 0, 0)
)
check_confounds(df)
clean_confounds(df)

Description

This function performs a comprehensive inspection of functional scans within a BIDS project, providing detailed summaries of scan counts and file sizes per subject and task. It helps identify potential issues such as missing scans, inconsistent file sizes, or unexpected variations in the data.

Usage

check_func_scans(x)

Arguments

Value

A list containing:

• scans: A tibble with details of all functional scans, including:

  • Subject ID

  • Task name

  • Run number

  • File size

  • Full file path

• tasklist: A vector of unique tasks found in the project

• scans_per_subject: A summary tibble showing the number of scans per subject

If multiple tasks are present, also includes:

• scans_per_task: Summary of scan counts by task

• scans_per_task_subject: Summary of scan counts by subject and task

• size_per_task: Tibble with file size statistics by task

If only one task is present:

• size_per_subject: Tibble with file size statistics by subject

Examples

# Check functional scans in a BIDS dataset
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  scan_check <- check_func_scans(proj)
  print(scan_check)
  
  # Filter for specific subjects
  sub01_check <- check_func_scans(proj, subid="01")
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Clears the session-level cache of downloaded example BIDS datasets. This can be useful to free up memory or force re-download of datasets.

Usage

clear_example_bids_cache()

Value

Invisible NULL

Examples

# Clear the cache
clear_example_bids_cache()

Description

This function retrieves a vector of confound files from a BIDS project that match specified criteria. Confound files in BIDS derivatives (typically from fMRIPrep) contain nuisance variables that can be used for denoising fMRI data, such as motion parameters, physiological signals, and other noise components.

Searches the mock BIDS structure for files matching typical confound file patterns (e.g., ⁠*_confounds*.tsv⁠, ⁠*_regressors*.tsv⁠, ⁠*_timeseries*.tsv⁠) within the derivatives directory.

Usage

confound_files(x, ...)

## S3 method for class 'bids_project'
confound_files(x, subid = ".*", task = ".*", session = ".*", ...)

## S3 method for class 'mock_bids_project'
confound_files(
  x,
  subid = ".*",
  task = ".*",
  session = ".*",
  run = ".*",
  full_path = FALSE,
  ...
)

Arguments

Details

This function assumes confound files reside in the derivatives path specified by x$prep_dir and were defined in the file_structure passed to create_mock_bids with fmriprep=TRUE.

Value

A character vector of file paths to confound files matching the specified criteria. If no matching files are found, returns NULL.

A character vector of file paths

A character vector of relative or full paths to potential confound files, or NULL if none are found.

Examples

# Get all confound files from a BIDS project with fMRIPrep derivatives
tryCatch({
  ds_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds_path, fmriprep=TRUE)
  conf_files <- confound_files(proj)
  
  # Get confound files for specific subjects and tasks
  confound_files(proj, subid="sub-01", task="balloonanalogrisktask")
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

# Setup mock project with a derivative confound file
participants_df <- tibble::tibble(participant_id = "01")
file_structure_df <- tibble::tribble(
  ~subid, ~session, ~datatype, ~task, ~run, ~suffix, ~fmriprep, ~desc,
  "01",   NA,       "func",    "taskA", "01", 
  "desc-confounds_timeseries.tsv", TRUE, "confounds"
)
mock_proj <- create_mock_bids("ConfoundMock", participants_df, file_structure_df)

# Find confound files
confound_files(mock_proj)

# Find for specific subject
confound_files(mock_proj, subid="01")

Description

Provides predefined, version-robust groups of confound variable names as described in the fMRIPrep documentation. These sets abstract over naming changes between fMRIPrep releases via the internal alias resolver used by read_confounds().

Usage

confound_set(name, n = NULL)

Arguments

Details

In addition to exact names, wildcard patterns are supported by the confound resolver:

• ⁠prefix*⁠ selects all columns that start with prefix (e.g., ⁠cosine_*⁠, ⁠motion_outlier_*⁠, ⁠a_comp_cor_*⁠).

• ⁠prefix*[N]⁠ selects the first N matches (e.g., ⁠a_comp_cor_*[6]⁠).

• Suffix combinations such as ⁠_derivative1⁠, ⁠_power2⁠, and ⁠_derivative1_power2⁠ are resolved across both old and new base names (e.g., trans_x_derivative1 also finds X_derivative1 if present).

Available sets (case-insensitive):

• "motion6": 6 rigid-body motion parameters: trans_x, trans_y, trans_z, rot_x, rot_y, rot_z.

• "motion12": motion6 + first temporal derivatives (adds ⁠*_derivative1⁠).

• "motion24": motion12 + quadratic terms of base and derivatives (adds ⁠*_power2⁠ and ⁠*_derivative1_power2⁠).

• "global3": global signals: csf, white_matter, global_signal.

• "9p": motion6 + global3 (9 parameters total).

• "36p": motion24 + global3 plus their derivatives and quadratics (i.e., the canonical 36-parameter set).

• "acompcor": anatomical CompCor components (⁠a_comp_cor_*⁠). Use n to cap the number of components retained, e.g., n = 6 -> ⁠a_comp_cor_*[6]⁠.

• "tcompcor": temporal CompCor components (⁠t_comp_cor_*⁠). Supports n as above.

• "compcor": both anatomical and temporal CompCor (applies n to each family if provided).

• "cosine": discrete cosine-basis regressors (matches both ⁠cosine_*⁠ and ⁠cosine*⁠).

• "outliers": outlier/censoring covariates including framewise_displacement, rmsd (if present), ⁠motion_outlier_*⁠, and ⁠non_steady_state_outlier*⁠.

• "dvars": DVARS family: dvars, std_dvars, non_std_dvars, vx_wisestd_dvars (resolved to whichever names exist in your dataset).

• "fd": framewise displacement only (framewise_displacement).

Value

A character vector of confound variable names and/or wildcard tokens that can be passed to read_confounds(..., cvars = confound_set(...)).

Examples

# Common usage: 24-parameter motion set
confound_set("motion24")

# 36-parameter model (Satterthwaite/Friston-style)
confound_set("36p")

# First 6 anatomical CompCor components
confound_set("acompcor", n = 6)

# All cosine regressors and outlier indicators
confound_set("cosine")
confound_set("outliers")

Description

Creates a structured confound strategy object that specifies which variables to reduce via PCA and which to keep as-is. Pass the result directly to read_confounds(..., cvars = confound_strategy(...)).

Usage

confound_strategy(
  name = NULL,
  pca_vars = NULL,
  raw_vars = NULL,
  perc_var = -1,
  npcs = -1
)

Arguments

Details

When a strategy is passed to read_confounds, the function:

1. Selects the pca_vars columns and reduces them via PCA (retaining perc_var\

2. Selects the raw_vars columns and keeps them unchanged.

3. Column-binds the PCA scores with the raw columns.

Available named strategies:

"pcabasic80"

PCA over motion24 + aCompCor + tCompCor + CSF + white matter, retaining 80\ Discrete cosine regressors are appended un-reduced.

Value

A confound_strategy object (S3 class) that can be passed as the cvars argument to read_confounds().

Examples

# Named strategy
confound_strategy("pcabasic80")

# Custom strategy: PCA motion + compcor to 5 PCs, keep cosine regressors
confound_strategy(
  pca_vars = c(confound_set("motion24"), confound_set("compcor")),
  raw_vars = confound_set("cosine"),
  npcs = 5
)

Description

Generates an in-memory representation of a BIDS project, suitable for testing and demonstration without requiring actual data files. Can optionally create a "stub" directory structure on disk.

Usage

create_mock_bids(
  project_name,
  participants,
  file_structure,
  dataset_description = NULL,
  event_data = list(),
  confound_data = list(),
  create_stub = FALSE,
  stub_path = NULL,
  prep_dir = "derivatives/fmriprep"
)

Arguments

Value

An object of class mock_bids_project.

Examples

# --- Example Setup ---
participants_df <- tibble::tibble(participant_id = c("01", "02"), age = c(25, 30))

file_structure_df <- tibble::tribble(
  ~subid, ~session, ~datatype, ~task,   ~run, ~suffix,                  ~fmriprep, ~desc,
  "01",   NA,       "anat",    NA,      NA,   "T1w.nii.gz",             FALSE,     NA,
  "01",   NA,       "func",    "taskA", "01", "bold.nii.gz",            FALSE,     NA,
  "01",   NA,       "func",    "taskA", "01", "events.tsv",             FALSE,     NA,
  "02",   "test",   "anat",    NA,      NA,   "T1w.nii.gz",             FALSE,     NA,
  "02",   "test",   "func",    "taskA", "01", "bold.nii.gz",            FALSE,     NA,
  "02",   "test",   "func",    "taskA", "01", "events.tsv",             FALSE,     NA,
  # Example derivative
  "01",   NA,       "func",    "taskA", "01", "preproc_bold.nii.gz",    TRUE,      "preproc"
)

# Define event data (paths must match generated structure)
event_data_list <- list()
event_data_list[["sub-01/func/sub-01_task-taskA_run-01_events.tsv"]] <- tibble::tibble(
  onset = c(1.0, 5.0), duration = c(0.5, 0.5), trial_type = c("condA", "condB")
)
event_data_list[["sub-02/ses-test/func/sub-02_ses-test_task-taskA_run-01_events.tsv"]] <-
  tibble::tibble(
    onset = c(1.5, 5.5), duration = c(0.5, 0.5), trial_type = c("condC", "condD")
)

# Create the mock project (in memory only)
mock_proj <- create_mock_bids(
  project_name = "MockTaskA",
  participants = participants_df,
  file_structure = file_structure_df,
  event_data = event_data_list
)

# Create the mock project and write stubs
mock_proj_stub <- create_mock_bids(
  project_name = "MockTaskA_stub",
  participants = c("01", "02"), # Example using just IDs
  file_structure = file_structure_df,
  event_data = event_data_list,
  create_stub = TRUE,
  stub_path = tempdir() # Use a temporary directory for example
)

# --- Using the Mock Project ---
print(mock_proj)
print(participants(mock_proj))
print(tasks(mock_proj))
print(sessions(mock_proj)) # Should return "test"

print(func_scans(mock_proj, subid = "01"))
print(event_files(mock_proj, subid = "02", session = "test"))

# Read the injected event data
events_sub1 <- read_events(mock_proj, subid = "01")
print(events_sub1)
if (nrow(events_sub1) > 0) print(tidyr::unnest(events_sub1, cols = data))

# Search for derivatives
print(search_files(mock_proj, suffix = "preproc_bold.nii.gz"))

# Check stub directory (if created)
stub_files <- list.files(mock_proj_stub$path, recursive = TRUE)
print(head(stub_files))

# Read one injected stub event file if present
stub_event_path <- file.path(mock_proj_stub$path, names(event_data_list)[1])
if (file.exists(stub_event_path)) {
  print(readLines(stub_event_path, n = 1))
}

# Cleanup is intentionally omitted in this example.

Description

Create a preprocessing mask from BIDS data

Usage

create_preproc_mask(x, subid, thresh = 0.99, ...)

Arguments

Value

A logical mask volume

Examples

# Download and load a BIDS project with fMRIPrep derivatives
tryCatch({
  ds001_deriv_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds001_deriv_path, fmriprep=TRUE)
  mask <- create_preproc_mask(proj, subid=".*")
  
  # Create mask for single subject
  sub01_mask <- create_preproc_mask(proj, subid="01")
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires derivatives dataset: ", e$message)
})

Description

This function creates a binary brain mask from preprocessed functional scans in a BIDS project. It searches for BOLD brain mask files in the fMRIPrep derivatives directory (i.e., files in the func/ folder matching the pattern *_desc-brain_mask.nii.gz or the older *_brainmask.nii.gz), reads them with neuroim2, averages them, and thresholds the result to produce a consensus binary mask.

Usage

## S3 method for class 'bids_project'
create_preproc_mask(
  x,
  subid,
  thresh = 0.99,
  task = ".*",
  space = ".*",
  mask_kinds = c("brainmask", "mask"),
  ...
)

Arguments

Details

The search is restricted to functional brain masks by requiring the task BIDS entity (anatomical masks do not carry task). When masks from multiple output spaces are discovered the function raises an error; pass a specific space value to disambiguate.

Value

A logical mask volume (LogicalNeuroVol) suitable for use with preprocessed functional data.

Examples

tryCatch({
  ds_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds_path, fmriprep=TRUE)

  # Mask for one subject in a specific space
  mask <- create_preproc_mask(proj, subid="01",
                              space="MNI152NLin2009cAsym")

  # Consensus mask across all subjects / runs
  all_mask <- create_preproc_mask(proj, subid=".*",
                                  space="MNI152NLin2009cAsym")

  # Restrict to a single task
  task_mask <- create_preproc_mask(proj, subid=".*",
                                  task="balloonanalogrisktask",
                                  space="MNI152NLin2009cAsym")

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

Description

This function is not implemented for mock_bids_project objects as they do not contain actual image data required to create a mask.

Usage

## S3 method for class 'mock_bids_project'
create_preproc_mask(x, ...)

Arguments

Value

Throws an error indicating the function is not applicable to mock objects.

Examples

mock <- create_mock_bids("Test", c("01"), tibble::tibble(
  subid = "01", datatype = "func",
  suffix = "bold.nii.gz", fmriprep = FALSE
))
try(create_preproc_mask(mock))

Description

This creates a transformer function that adds a smoothing description to BIDS filenames. This is a lightweight example - real implementations would perform actual image processing.

Usage

create_smooth_transformer(fwhm, suffix_pattern = "bold\\.nii")

Arguments

Value

A transformer function for use with bids_transform.

Examples

# Create a smoothing transformer
smooth_6mm <- create_smooth_transformer(6)

# Apply it to a toy BIDS-like file path
in_dir <- tempdir()
out_dir <- tempdir()
infile <- file.path(in_dir, "sub-01_task-rest_bold.nii.gz")
file.create(infile)
new_file <- smooth_6mm(infile, out_dir)
basename(new_file)
unlink(infile)
unlink(new_file)

Description

Get the dataset_description object from a BIDS project

Usage

dataset_description(x, ...)

## S3 method for class 'bids_project'
dataset_description(x, ...)

Arguments

Value

A bids_dataset_description object, or NULL.

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  desc <- dataset_description(proj)
  print(desc)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) message("Example requires internet: ", e$message))

Description

Get fields from a BIDS dataset description

Usage

dataset_name(x, ...)

dataset_type(x, ...)

Arguments

Value

A character scalar.

Description

This function reconstructs a BIDS filename from parsed entities, using the standard BIDS entity ordering.

Usage

decode_bids_entities(entities)

Arguments

Value

A character string representing the BIDS filename.

Examples

# Parse a filename and reconstruct it
entities <- encode("sub-01_task-rest_run-01_bold.nii.gz")
filename <- decode_bids_entities(entities)
print(filename)

# Modify entities and create new filename
entities$desc <- "smooth6mm"
new_filename <- decode_bids_entities(entities)
print(new_filename)

Description

Convenience wrapper around query_files() that restricts results to derivative pipelines.

Usage

derivative_files(x, pipeline = NULL, ...)

Arguments

Value

Character vector of file paths (or tibble when return = "tibble").

Examples

tryCatch({
  ds_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds_path, fmriprep = TRUE)
  df <- derivative_files(proj)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) message("Example requires internet: ", e$message))

Description

Returns a tibble describing the derivative pipelines currently attached to a bids_project. This is the preferred inspection entry point for new code; legacy fmriprep / prep_dir fields remain available for compatibility.

Usage

derivative_pipelines(x)

Arguments

Value

A tibble with one row per derivative pipeline and columns pipeline, root, description, and source.

Examples

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

Description

This function parses a BIDS filename and extracts its components into a key-value list. It understands standard BIDS entities like subject, session, task, run, etc.

Usage

encode(x, ...)

## S3 method for class 'character'
encode(x, ...)

Arguments

Value

A list of key-value pairs extracted from the filename

Examples

# Encode an anatomical file
encode("sub-01_T1w.nii.gz")

# Encode a functional file
encode("sub-01_task-rest_run-01_bold.nii.gz")

# Encode a file with session information
encode("sub-01_ses-pre_task-rest_run-01_bold.nii.gz")

Description

This function retrieves a vector of event files (events.tsv) from a BIDS project that match specified criteria. Event files in BIDS contain trial information for task-based functional MRI data, including onset times, durations, and trial types.

Finds event files matching the given subject, task, run, and session criteria.

Usage

event_files(x, ...)

## S3 method for class 'bids_project'
event_files(
  x,
  subid = ".*",
  task = ".*",
  run = ".*",
  session = ".*",
  full_path = TRUE,
  ...
)

## S3 method for class 'mock_bids_project'
event_files(
  x,
  subid = ".*",
  task = ".*",
  run = ".*",
  session = ".*",
  full_path = TRUE,
  ...
)

Arguments

Value

A character vector of file paths to event files matching the specified criteria. If no matching files are found, returns NULL.

A character vector of file paths to event files. If no matching files are found, returns an empty character vector.

Examples

# Get all event files from a BIDS project
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  event_files(proj)
  
  # Get event files for specific subjects and tasks
  if (length(participants(proj)) > 0) {
    event_files(proj, subid=participants(proj)[1], task="balloonanalogrisktask")
  }
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})


# Get event files for a specific subject and task
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  x <- bids_project(ds001_path)
  files <- event_files(x, subid="01", task="balloonanalogrisktask")
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

This function matches pairs of related files (e.g., BOLD and event files) in a BIDS project, returning a tibble with matched filenames. It's useful for verifying that corresponding files exist for each subject and task, such as ensuring every BOLD file has an associated events file.

Usage

file_pairs(
  x,
  pair = c("bold-events", "preproc-events"),
  task = ".*",
  matchon = c("run", "task"),
  ...
)

Arguments

Value

A tibble with columns:

• subid: The subject ID

• task: The task name

• ⁠[type1]⁠: The name of the first file type (e.g., "bold" or "preproc")

• ⁠[type2]⁠: The matched file of the second type (e.g., "events"), or NA if no match found

• Additional columns for matched metadata (e.g., run, session)

Examples

# Create a BIDS project object
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  
  # Match BOLD files with their corresponding event files
  bold_pairs <- file_pairs(proj, pair="bold-events")
  
  # Check pairs for a specific task
  task_pairs <- file_pairs(proj, 
                          pair="bold-events",
                          task="balloonanalogrisktask")
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

This function returns a flattened (non-hierarchical) representation of a BIDS project formatted as a data frame. It extracts file paths or file names from the BIDS tree structure, filtering for entries that start with "sub-" to focus on subject-level data.

Usage

flat_list(x, ...)

## S3 method for class 'bids_project'
flat_list(x, full_path = TRUE, ...)

Arguments

Value

A data frame containing either full paths to files (if full_path=TRUE) or just the file names (if full_path=FALSE). Each row represents one file in the BIDS project.

Examples

# Get flat representation with full paths
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  flat_list(proj)
  
  # Get flat representation with just file names
  flat_list(proj, full_path=FALSE)
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Fieldmap parser constructor

Usage

fmap_parser()

Value

A fieldmap BIDS parser object for parsing fieldmap files

Examples

# Create a fieldmap parser
parser <- fmap_parser()

# Parse a fieldmap file
result <- parse(parser, "sub-01_magnitude1.nii.gz")

Description

fMRIPrep anatomical parser constructor

Usage

fmriprep_anat_parser()

Value

An fMRIPrep anatomical parser object for parsing preprocessed anatomical files

Examples

# Create an fMRIPrep anatomical parser
parser <- fmriprep_anat_parser()

# Parse a preprocessed anatomical file
result <- parse(parser, "sub-01_space-MNI152NLin2009cAsym_desc-preproc_T1w.nii.gz")

Description

fMRIPrep functional parser constructor

Usage

fmriprep_func_parser()

Value

An fMRIPrep functional parser object for parsing preprocessed functional files

Examples

# Create an fMRIPrep functional parser
parser <- fmriprep_func_parser()

# Parse a preprocessed functional file
result <- parse(parser, "sub-01_task-rest_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz")

Description

Functional parser constructor

Usage

func_parser()

Value

A functional BIDS parser object for parsing functional MRI files

Examples

# Create a functional parser
parser <- func_parser()

# Parse a functional file
result <- parse(parser, "sub-01_task-rest_run-01_bold.nii.gz")

Description

This function extracts functional scan files from a BIDS project that match specified criteria such as subject ID, task name, run number, and session. It can return either full paths or relative paths to the files.

Usage

func_scans(x, ...)

## S3 method for class 'mock_bids_project'
func_scans(
  x,
  subid = ".*",
  task = ".*",
  run = ".*",
  session = ".*",
  kind = "bold",
  suffix = "nii(\\.gz)?$",
  full_path = TRUE,
  ...
)

Arguments

Value

A character vector of file paths to functional scans matching the criteria. Returns NULL if no matching files are found.

Examples

# Create a BIDS project object
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  
  # Get all functional scans
  all_scans <- func_scans(proj)
  
  # Get scans for specific subjects
  if (length(participants(proj)) > 0) {
    sub_scans <- func_scans(proj, subid=participants(proj)[1])
  }
  
  # Get scans for a specific task and run
  if (length(tasks(proj)) > 0) {
    task_scans <- func_scans(proj, task=tasks(proj)[1], run="01")
  }
  
  # Get scans with relative paths
  rel_scans <- func_scans(proj, full_path=FALSE)
  
  # Also try with a dataset that has sessions
  ds007_path <- get_example_bids_dataset("ds007")
  ds007_proj <- bids_project(ds007_path)
  if (length(sessions(ds007_proj)) > 0) {
    session_scans <- func_scans(ds007_proj, session=sessions(ds007_proj)[1])
  }
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
  unlink(ds007_path, recursive=TRUE)
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

This method extracts functional scan files from a BIDS project based on specified criteria such as subject ID, task name, run number, and session. It can return either full or relative file paths to the functional scans.

Usage

## S3 method for class 'bids_project'
func_scans(
  x,
  subid = ".*",
  task = ".*",
  run = ".*",
  session = ".*",
  kind = "bold",
  full_path = TRUE,
  ...
)

Arguments

Value

A character vector of file paths to functional scans matching the criteria. Returns NULL if:

• No matching files are found

• The project doesn't contain functional data

• The specified criteria don't match any files

Examples

# Create a BIDS project
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  
  # Get all functional scans
  all_scans <- func_scans(proj)
  
  # Get scans for specific subjects
  sub_scans <- func_scans(proj, subid="0[123]")
  
  # Get scans for a specific task
  task_scans <- func_scans(proj, task="rest")
  
  # Get scans from specific runs
  run_scans <- func_scans(proj, run="0[123]")
  
  # Combine multiple filters
  filtered_scans <- func_scans(proj,
                              subid="01",
                              task="rest",
                              run="01")
  
  # Get relative paths instead of full paths
  rel_scans <- func_scans(proj, full_path=FALSE)
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Converts a parser_spec list (as returned by bids_datatype_spec or the internal func_spec() etc.) into a parser object suitable for passing to register_datatype.

Usage

gen_parser(spec, typename = "kind")

Arguments

Value

A regex-based parser object.

See Also

bids_datatype_spec, register_datatype

Examples

spec <- bids_datatype_spec(
  type     = "dwi",
  entities = c("sub", "ses", "acq", "run"),
  suffixes = list(dwi = c(".nii.gz", ".nii", ".bvec", ".bval", ".json"))
)
parser <- gen_parser(spec)

Description

Downloads and extracts an example BIDS dataset for testing and demonstration purposes. The datasets are sourced from the official BIDS examples repository on GitHub.

Usage

get_example_bids_dataset(dataset_name = "ds001")

Arguments

Details

This function requires an internet connection to download data from GitHub. The datasets are cached in the temporary directory AND in memory for the session, so repeated calls with the same dataset_name will reuse the already downloaded data. Note: Don't call unlink() on the returned path in examples, as this defeats the caching mechanism and forces re-downloads.

Value

Character string containing the path to the downloaded dataset directory.

Examples

tryCatch({
  ds_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds_path)
  print(participants(proj))
  
  # Dataset cache is intentionally retained for performance.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

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"),
  ...
)

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

Arguments

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.

Value

A named list of metadata fields.

Examples

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))

Description

This function attempts to find and return the repetition time (TR) for a given subject, task, and run (and optionally session) by locating the associated BOLD sidecar JSON file and extracting the 'RepetitionTime' field. If not found, returns NA.

Usage

get_repetition_time(x, subid, task, run = ".*", session = ".*", ...)

Arguments

Value

A numeric value representing the RepetitionTime in seconds, or NA if not found.

Examples

# Download and get TR for a specific subject and task
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  
  if (length(participants(proj)) > 0 && length(tasks(proj)) > 0) {
    tr <- get_repetition_time(proj, 
                             subid=participants(proj)[1], 
                             task=tasks(proj)[1])
    cat("TR:", tr, "seconds\n")
  }
  
  # Try with a dataset that has sessions
  ds007_path <- get_example_bids_dataset("ds007")
  ds007_proj <- bids_project(ds007_path)
  if (length(participants(ds007_proj)) > 0 && length(sessions(ds007_proj)) > 0) {
    tr_session <- get_repetition_time(ds007_proj,
                                     subid=participants(ds007_proj)[1],
                                     session=sessions(ds007_proj)[1])
    cat("TR with session:", tr_session, "seconds\n")
  }
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
  unlink(ds007_path, recursive=TRUE)
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Given a path to a BOLD NIfTI file (⁠*.nii⁠ or ⁠*.nii.gz⁠) or its JSON sidecar (⁠*.json⁠), this function locates the appropriate sidecar JSON and returns the TR (in seconds). It prefers the JSON RepetitionTime field (BIDS-compliant). If that is not available, it falls back to computing TR as the median difference of VolumeTiming (if present). Optionally, when the sidecar cannot be found or is missing both fields, the function attempts to read TR from the NIfTI header (pixdim[4]) if an appropriate reader is installed.

Usage

infer_tr(x, ...)

## S3 method for class 'character'
infer_tr(
  x,
  prefer = c("json", "nifti"),
  fallback = TRUE,
  coerce_units = c("strict", "auto"),
  verbose = FALSE,
  ...
)

Arguments

Details

For NIfTI inputs, the JSON sidecar is resolved by replacing the ⁠*.nii⁠/⁠*.nii.gz⁠ suffix with .json in the same directory. If that file is not found, the function searches the directory for a .json file with the same stem (filename without the NIfTI extension).

Value

Numeric TR in seconds, or NA_real_ if it cannot be determined. The return value includes attributes: source (e.g., json:RepetitionTime, json:VolumeTiming, nifti:pixdim4), path (the file used), and optionally variable = TRUE if VolumeTiming indicates non-constant TR; a unit = "ms->s" attribute is added if units were auto-converted.

Examples

tmp_json <- tempfile(fileext = ".json")
writeLines('{"RepetitionTime": 2}', tmp_json)
infer_tr(tmp_json)
unlink(tmp_json)

tmp_json2 <- tempfile(fileext = ".json")
writeLines('{"VolumeTiming": [0, 2, 4, 6]}', tmp_json2)
infer_tr(tmp_json2)
unlink(tmp_json2)

Description

Test whether an object is a BIDS URI

Usage

is_bids_uri(x)

Arguments

Value

TRUE if x inherits from "bids_uri", FALSE otherwise.

Examples

u <- bids_uri("bids::sub-01/anat/sub-01_T1w.nii.gz")
is_bids_uri(u)      # TRUE
is_bids_uri("bids::sub-01/anat/sub-01_T1w.nii.gz")  # FALSE

Description

Returns the names and short descriptions of the predefined confound sets usable with confound_set().

Usage

list_confound_sets()

Value

A data.frame with columns set and description.

Examples

list_confound_sets()

Description

Returns the names and short descriptions of the predefined confound strategies usable with confound_strategy().

Usage

list_confound_strategies()

Value

A data.frame with columns strategy and description.

Examples

list_confound_strategies()

Description

Returns the names of all datatypes currently registered in the bidser runtime registry.

Usage

list_datatypes(scope = c("all", "raw", "derivative", "both"))

Arguments

Value

A character vector of datatype names.

Examples

list_datatypes()
list_datatypes(scope = "raw")

Description

This function lists the contents of a BIDS archive created by pack_bids, showing file sizes and identifying which files are stubs.

Usage

list_pack_bids(archive_path, verbose = TRUE)

Arguments

Value

A data frame with columns:

Examples

# Create and inspect a packed BIDS archive
tryCatch({
  ds_path <- get_example_bids_dataset("ds001") 
  proj <- bids_project(ds_path)
  archive_path <- pack_bids(proj, verbose = FALSE)
  
  # List contents
  contents <- list_pack_bids(archive_path)
  
  # Show stub files
  stub_files <- contents[contents$is_stub, ]
  print(head(stub_files))
  
  # Clean up
  unlink(archive_path)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example failed: ", e$message)
})

Description

Searches for and reads event files (events.tsv) from a BIDS project, combining them into a single (potentially nested) tibble.

This function searches for all events.tsv files that match the provided filters (subid, task, run, session) and loads them into a single tibble. If full_path=TRUE, full file paths are returned; otherwise relative paths.

Usage

load_all_events(x, ...)

## S3 method for class 'bids_project'
load_all_events(
  x,
  subid = ".*",
  task = ".*",
  run = ".*",
  session = ".*",
  full_path = TRUE,
  ...
)

Arguments

Value

A tibble containing the combined event data.

A tibble combining all matched event files, with columns .subid, .task, .run, .session and all event columns. If no events are found, returns an empty tibble.

Examples

# Example with a bids_project (assuming events exist)
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  all_events <- load_all_events(proj)
  print(all_events)
  
  # Load specific subject/task
  if (length(participants(proj)) > 0) {
    sub01_events <- load_all_events(proj, subid=participants(proj)[1], task="balloonanalogrisktask")
    print(sub01_events)
  }
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Retrieves paths to brain mask files from a BIDS project, optionally filtered by subject, session, and coordinate space. Mask files are typically found in fMRIPrep derivatives and include brain masks and tissue segmentation masks.

Usage

mask_files(
  x,
  subid = ".*",
  session = ".*",
  space = ".*",
  full_path = TRUE,
  ...
)

## S3 method for class 'bids_project'
mask_files(
  x,
  subid = ".*",
  session = ".*",
  space = ".*",
  full_path = TRUE,
  ...
)

## S3 method for class 'mock_bids_project'
mask_files(
  x,
  subid = ".*",
  session = ".*",
  space = ".*",
  full_path = TRUE,
  ...
)

Arguments

Value

Character vector of file paths matching the criteria, or NULL if no matching files are found.

Examples

# Get all mask files
tryCatch({
  ds_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds_path, fmriprep = TRUE)

  # All masks
  all_masks <- mask_files(proj)

  # Masks in MNI space
  mni_masks <- mask_files(proj, space = "MNI152")

  # Masks for specific subject
  sub01_masks <- mask_files(proj, subid = "01")

  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

This function creates a compressed archive (tar.gz or zip) of a BIDS project, either replacing large imaging files (.nii, .nii.gz) with 0-byte stub files or downsampling them to lower resolution while preserving all metadata files (JSON, TSV, etc.) with their full content. This is useful for sharing BIDS project structure and metadata without the large imaging data.

Usage

pack_bids(
  x,
  output_file = NULL,
  format = NULL,
  include_derivatives = TRUE,
  downsample_factor = NULL,
  downsample_method = "box",
  ncores = 1,
  max_file_size = "10MB",
  exclude = NULL,
  strict_bids = FALSE,
  verbose = TRUE,
  temp_dir = NULL,
  cleanup = TRUE
)

Arguments

Details

The function works by:

1. Creating a temporary copy of the BIDS project structure

2. Replacing all .nii and .nii.gz files with 0-byte stub files

3. Preserving all other files (JSON, TSV, TXT, etc.) with full content

4. Creating a compressed archive of the modified structure

This allows researchers to share BIDS dataset structure and metadata without the large imaging files, which is useful for:

• Sharing dataset organization and metadata for review

• Creating lightweight references for dataset structure

• Testing BIDS tools without full datasets

Value

Character string containing the path to the created archive file. Returns NULL if the operation fails.

Examples

# Create a BIDS project and pack it
tryCatch({
  ds_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds_path)
  
  # Pack with default settings (tar.gz with stub files)
  archive_path <- pack_bids(proj)
  
  # Pack with size limit and exclusion pattern
  archive_filtered <- pack_bids(proj,
                                max_file_size = "1MB",
                                exclude = "\\.h5$",
                                output_file = "ds001_filtered.tar.gz")
  
  # Pack with downsampling (4x reduction)
  archive_downsampled <- pack_bids(proj, 
                                   downsample_factor = 0.25,
                                   output_file = "ds001_low4x.tar.gz")
  
  # Pack with downsampling using parallel processing
  if (requireNamespace("future", quietly = TRUE)) {
    archive_parallel <- pack_bids(proj, 
                                 downsample_factor = 0.5,
                                 ncores = 2,
                                 output_file = "ds001_low2x.tar.gz")
  }
  
  # Pack as zip file
  zip_path <- pack_bids(proj, output_file = "ds001_metadata.zip")
  
  # Pack without derivatives
  archive_no_deriv <- pack_bids(proj, include_derivatives = FALSE)
  
  # Pack with strict BIDS mode (exclude non-BIDS files)
  archive_strict <- pack_bids(proj, strict_bids = TRUE,
                              output_file = "ds001_strict.tar.gz")
  
  # Clean up
  unlink(c(archive_path, archive_filtered, archive_downsampled, zip_path, 
           archive_no_deriv, archive_strict))
  if (exists("archive_parallel")) unlink(archive_parallel)
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example failed: ", e$message)
})

Description

This generic function parses a BIDS filename into its component parts. It uses a parser combinator approach to match the filename against known BIDS patterns and extract relevant metadata such as subject ID, session, task, run, and modality.

Usage

parse(x, fname, ...)

Arguments

Value

A parsed representation of the BIDS filename, typically a list with extracted components

Examples

# Parse an anatomical file
parser <- anat_parser()
parse(parser, "sub-01_T1w.nii.gz")

# Parse a functional file
parser <- func_parser()
parse(parser, "sub-01_task-rest_run-01_bold.nii.gz")

# Use the generic BIDS parser
parser <- bids_parser()
parse(parser, "sub-01_ses-pre_task-rest_run-01_bold.nii.gz")

Description

Retrieves participant information from a BIDS project. By default returns a sorted character vector of unique participant IDs (without the "sub-" prefix).

Usage

participants(x, ...)

## S3 method for class 'bids_project'
participants(x, as_tibble = FALSE, ...)

Arguments

Details

When as_tibble = TRUE, a tibble is returned instead containing the full participants.tsv data (or inferred IDs when the file is missing) plus a source column indicating whether each ID came from the "table" or the "filesystem".

Value

A character vector of unique participant IDs, or a tibble when as_tibble = TRUE.

Examples

# Get participants from a BIDS project
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  participants(proj)

  # Get full tibble with provenance
  participants(proj, as_tibble = TRUE)

  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Extracts the unique participant IDs from the mock project definition. Note: Returns IDs without the "sub-" prefix for consistency with bids_project methods.

Usage

## S3 method for class 'mock_bids_project'
participants(x, as_tibble = FALSE, ...)

Arguments

Value

Character vector of unique participant IDs (e.g., c("01", "02")), sorted. If as_tibble = TRUE, a tibble with participant metadata.

Examples

# Create a mock project
parts <- data.frame(participant_id = c("sub-01", "sub-02"))
fs <- data.frame(subid=c("01", "02"), datatype="func", suffix="bold.nii.gz", fmriprep=FALSE)
mock_proj <- create_mock_bids("SimpleMock", parts, fs)

# Get participant IDs
participants(mock_proj)

Description

This function creates a multi-panel visualization of a BIDS project structure, showing file distributions, completeness, and data characteristics.

Usage

plot_bids(
  x,
  interactive = TRUE,
  color_scheme = "viridis",
  include_derivatives = TRUE,
  file_size_scale = "log",
  highlight_missing = TRUE,
  visualization_mode = "standard",
  debug = FALSE
)

Arguments

Value

A plot object (ggplot2, plotly, or other depending on settings)

Examples

# Create a basic BIDS project and plot it
tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  plot_bids(proj)
  
  # Create an interactive plot
  plot_bids(proj, interactive=TRUE)
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Visualize principal component scores and loadings returned by read_confounds(..., npcs = ...). When multiple runs are present, the default view facets per run for scores (up to max_panels) and aggregates loadings across runs.

Usage

## S3 method for class 'bids_confounds'
plot(
  x,
  view = c("auto", "run", "aggregate"),
  pcs = NULL,
  top_n = 8,
  max_panels = 6,
  ...
)

Arguments

Value

A ggplot object, or a list of ggplot objects when patchwork is not available.

Examples

parts <- c("01", "02")
fs <- tibble::tibble(
  subid = rep(c("01", "02"), each = 2),
  datatype = "func",
  suffix = rep(c("bold.nii.gz", "desc-confounds_timeseries.tsv"), 2),
  task = "rest", fmriprep = TRUE
)
conf_data <- list()
for (p in parts) {
  key <- paste0("derivatives/fmriprep/sub-", p,
                "/func/sub-", p, "_task-rest_desc-confounds_timeseries.tsv")
  conf_data[[key]] <- data.frame(
    csf = rnorm(100), white_matter = rnorm(100),
    global_signal = rnorm(100), framewise_displacement = abs(rnorm(100)),
    trans_x = rnorm(100), trans_y = rnorm(100), trans_z = rnorm(100),
    rot_x = rnorm(100), rot_y = rnorm(100), rot_z = rnorm(100)
  )
}
mock <- create_mock_bids("ConfPlot", parts, fs, confound_data = conf_data)
conf <- read_confounds(mock, npcs = 3)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot(conf)
}

Description

This method visualises the hierarchical file structure of a BIDS project. The tree is converted to a dendrogram and drawn using base graphics. Large projects can be trimmed by setting a maximum depth.

Usage

## S3 method for class 'bids_project'
plot(x, max_depth = Inf, ...)

## S3 method for class 'mock_bids_project'
plot(x, max_depth = Inf, ...)

Arguments

Value

The input object x is returned invisibly.

Examples

tryCatch({
  ds001_path <- get_example_bids_dataset("ds001")
  proj <- bids_project(ds001_path)
  plot(proj)
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

This function retrieves paths to preprocessed functional MRI scans from a BIDS project. It searches for files in the fMRIPrep derivatives directory that match specified criteria, such as subject ID, task, run, and other BIDS metadata. Preprocessed scans are identified by having either 'desc-preproc' or 'kind-preproc' in their filename.

Usage

preproc_scans(
  x,
  subid = ".*",
  task = ".*",
  run = ".*",
  session = ".*",
  variant = NULL,
  space = ".*",
  modality = "bold",
  kind = ".*",
  full_path = FALSE,
  ...
)

Arguments

Value

A character vector of file paths to preprocessed functional scans matching the criteria. If no matching files are found, returns NULL.

Examples

# Get all preprocessed scans from a BIDS project with fMRIPrep derivatives

# Download and load a BIDS project with fMRIPrep derivatives
tryCatch({
  ds001_deriv_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds001_deriv_path, fmriprep=TRUE)
  
  # Get all preprocessed scans
  scans <- preproc_scans(proj)
  
  # Get preprocessed scans for a specific subject
  if (!is.null(scans) && length(scans) > 0) {
    sub01_scans <- preproc_scans(proj, subid="01")
  }
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires derivatives dataset: ", e$message)
})

Description

This function retrieves paths to preprocessed functional MRI scans from a BIDS project's fMRIPrep derivatives. It allows filtering by various BIDS entities such as subject, task, run, session, and space. The function is particularly useful for accessing preprocessed data for analysis pipelines.

Usage

## S3 method for class 'bids_project'
preproc_scans(
  x,
  subid = ".*",
  task = ".*",
  run = ".*",
  session = ".*",
  variant = NULL,
  space = ".*",
  modality = "bold",
  kind = ".*",
  full_path = FALSE,
  ...
)

Arguments

Value

A character vector of file paths to preprocessed scans matching the criteria. Returns NULL if:

• No matching files are found

• The project doesn't have fMRIPrep derivatives

• The specified criteria don't match any files

Examples

# Create a BIDS project with fMRIPrep derivatives
tryCatch({
  ds_path <- get_example_bids_dataset("phoneme_stripped")
  proj <- bids_project(ds_path, fmriprep=TRUE)
  
  # Get all preprocessed BOLD scans
  all_scans <- preproc_scans(proj)
  
  # Get preprocessed scans for specific subjects
  sub_scans <- preproc_scans(proj, subid="0[12]")
  
  # Get scans in MNI space
  mni_scans <- preproc_scans(proj, space="MNI152NLin2009cAsym")
  
  # Get scans for a specific task with full paths
  task_scans <- preproc_scans(proj,
                             task="phoneme",
                             full_path=TRUE)
  
  # Get scans from a specific session
  session_scans <- preproc_scans(proj, session="test")
  
  # Combine multiple filters
  filtered_scans <- preproc_scans(proj,
                                 subid="01",
                                 task="phoneme",
                                 run="01",
                                 space="MNI152NLin2009cAsym")
  
  # Filter by resolution (BIDS entity 'res')
  res2_scans <- preproc_scans(proj, res = "2")
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Provides a console summary of the mock BIDS project, displaying key information like participant count, tasks, sessions, derivatives status, and discovered BIDS entities.

Usage

## S3 method for class 'mock_bids_project'
print(x, ...)

Arguments

Value

The mock_bids_project object x invisibly.

Examples

# Create a simple mock project
parts <- data.frame(participant_id = "01")
fs <- data.frame(subid = "01", datatype="func", suffix="bold.nii.gz", fmriprep=FALSE)
mock_proj <- create_mock_bids("SimpleMock", parts, fs)

# Print the summary
print(mock_proj)

Description

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,
  ...
)

## 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,
  ...
)

Arguments

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

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)
})


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)
})

Description

This function reads in fMRIPrep confound tables for one or more subjects from a BIDS project. Confound files contain nuisance variables that can be used for denoising fMRI data, such as motion parameters, physiological signals, and other noise components. The function can optionally perform PCA reduction on the confounds and return either nested or flat tibbles.

Usage

read_confounds(x, ...)

Arguments

Value

A bids_confounds tibble containing confound data. If nest=TRUE (default), returns a nested tibble with columns for subject, task, session, run, and a nested data column containing the confound variables. If nest=FALSE, returns a flat tibble with all confound variables. When PCA is requested, the object includes a pca attribute with loadings/variance for plotting. Returns NULL if no matching files are found.

Examples

# Create a BIDS project with fMRIPrep derivatives
tryCatch({
  ds_path <- get_example_bids_dataset("ds000001-fmriprep")
  proj <- bids_project(ds_path, fmriprep=TRUE)
  
  # Read all confound files
  all_conf <- read_confounds(proj)
  
  # Read confounds for specific subjects and tasks
  sub_conf <- read_confounds(proj,
                            subid="01",
                            task="balloonanalogrisktask")
  
  # Select specific confound variables
  motion_conf <- read_confounds(proj,
                               cvars=c("framewise_displacement",
                                      "trans_x", "trans_y", "trans_z",
                                      "rot_x", "rot_y", "rot_z"))
  
  # Perform PCA reduction
  pca_conf <- read_confounds(proj, npcs=5)
  
  # Get confounds as a flat tibble
  flat_conf <- read_confounds(proj, nest=FALSE)
  
  # Combine multiple options
  custom_conf <- read_confounds(proj,
                               subid="01",
                               task="balloonanalogrisktask",
                               cvars=c("framewise_displacement",
                                      "trans_x", "trans_y", "trans_z"),
                               npcs=3,
                               nest=FALSE)
  
  # Clean up
  # Example datasets are cached; leave the cache in place.
}, error = function(e) {
  message("Example requires internet connection: ", e$message)
})

Description

Reads in fmriprep confound tables for one or more subjects.

Usage

## S3 method for class 'bids_project'
read_confounds(
  x,
  subid = ".*",
  task = ".*",
  session = ".*",
  run = ".*",
  cvars = DEFAULT_CVARS,
  npcs = -1,
  perc_var = -1,
  nest = TRUE,
  clean = "zero_variance",
  na_action = "leave",
  ...
)