Extract ROI timeseries and connectivity matrices

Given a postprocessed BOLD NIfTI file and one or more atlas images, this function computes the mean timeseries within each ROI and optionally computes ROI-to-ROI correlation matrices.

Usage

extract_rois(
  bold_file,
  atlas_files,
  out_dir,
  log_file = NULL,
  cor_method = c("pearson", "spearman", "kendall", "cor.shrink"),
  roi_reduce = c("mean", "median", "pca", "huber"),
  brain_mask = NULL,
  min_vox_per_roi = 5,
  save_ts = TRUE,
  rtoz = FALSE,
  overwrite = FALSE
)

Arguments

bold_file

Path to a 4D NIfTI file containing postprocessed BOLD data.

atlas_files

Character vector of atlas NIfTI files with integer ROI labels.

out_dir

Directory where output files should be written.

log_file

If not NULL, the log file to which details should be written.

cor_method

Correlation method(s) to use when computing functional connectivity. Supported options include "pearson", "spearman", "kendall", and "cor.shrink". Use "none" to skip correlation computation. Multiple methods may be supplied.

roi_reduce

Method used to summarize voxel time series within each ROI. Options are "mean" (default), "median", "pca", or "huber".

brain_mask

Optional brain mask NIfTI file. If NULL, a mask is generated by excluding voxels with zero variance across time.

min_vox_per_roi

The minimum number of voxels required for an ROI to be extracted and entered into correlations. If the ROI is smaller than this, it show up as NA in the outputs, keeping the dimensionality of the connectivity matrix consistent across inputs. Default: 5

save_ts

If TRUE, save the ROI time series (aggregated using roi_reduce method) to _timeseries.tsv. files. Useful for running external analyses on the ROIs. Default: TRUE.

rtoz

If TRUE, using Fisher's z (aka atanh) transformation on correlations to make them continuous and unbounded, rather than [0,1]. The diagonal of the correlation matrices beccomes 15 to approximate the 1.0 correlation, rather than making it Inf.

overwrite

If TRUE, overwrite existing timeseries.tsv or connectivity.tsv files.

Value

A named list. Each element corresponds to an atlas and contains paths to the written timeseries (timeseries) and correlation matrix (correlation, or NULL if not computed).

Details

Voxels labelled in the atlas but lying outside the brain are automatically excluded by intersecting with a brain mask derived from the input timeseries.