Getting started with boldR • boldR

fmriprep gets you clean data. boldR gets you useful data.

boldR picks up exactly where fMRIPrep leaves off. It reads preprocessed BIDS derivatives and transforms them into analysis-ready outputs: ROI timeseries, functional connectivity matrices, and voxelwise quality metrics — all exportable to syncR for integration with sleep and circadian data.

Installation

# install.packages("pak")
pak::pak("circadia-bio/boldR")

Basic workflow

1. Read fMRIPrep derivatives

library(boldR)

fprep <- read_fmriprep(
  derivatives_dir = "data/derivatives/fmriprep",
  subject         = "01",
  task            = "rest",
  space           = "MNI152NLin2009cAsym"
)
fprep

2. Prepare the BOLD object

bold <- prepare_bold(
  fmriprep    = fprep,
  tr          = 2,      # seconds; or NULL to read from NIfTI header
  drop_volumes = 4      # discard first 4 dummy scans
)
bold

3. Load an atlas and parcellate

boldR ships with several built-in atlases and accepts any custom NIfTI label image via the boldR_atlas schema.

# See available built-ins
list_atlases()

# Load Schaefer 100-parcel atlas
atlas <- load_atlas("schaefer100_7n")

# Extract mean timeseries per ROI
parcel <- parcellate(bold, atlas)
dim(parcel$timeseries)  # timepoints × 100

Custom atlas

custom <- load_atlas(
  atlas  = "my_parcellation.nii.gz",
  labels = paste0("Region_", 1:80),
  space  = "MNI152NLin2009cAsym"
)
parcel_custom <- parcellate(bold, custom)

4. Compute metrics

# Functional connectivity matrix (Fisher z)
fc <- compute_fc(parcel)
dim(fc$z)  # 100 × 100

# ROI summary statistics
roi_stats <- compute_roi_metrics(parcel)
roi_stats

# Voxelwise temporal SNR
tsnr <- compute_tsnr(bold)
tsnr$median_tsnr

5. Export for syncR

bold_export <- export_bold(parcel, fc = fc)
bold_export

# In your syncR pipeline:
# syncR::sync(
#   zeitR    = actigraphy_metrics,
#   slumbR   = sleep_diary,
#   tallieR  = questionnaires,
#   bold     = bold_export
# )

Ecosystem

boldR is part of the Circadia Lab R ecosystem. See circadia-lab.uk for the full package suite.