rsDCM: Robust and Sparse Dynamic Causal Modelling for Functional MRI

rsDCM is an R package that provides a robust and sparse method for group-level Dynamic Causal Modelling (DCM) of fMRI data, together with an R implementation of single-subject DCM ported from the MATLAB SPM25 toolbox.

Installation

From GitHub (development version):

# install.packages("remotes")
remotes::install_github("Kay202/rsDCM")

From CRAN:

Quick start

The following is an example of using the main function rsDCM()

library(rsDCM)

# Real 48-subject NARPS group analysis. The inputs are precomputed
# subject-level DCM summaries (a posterior mean and covariance per subject).
data(narps_dcm)
N <- nrow(narps_dcm$eta)
p <- ncol(narps_dcm$eta)

# Per-parameter variance-component basis, and an intercept-only design.
V_list <- lapply(seq_len(p), function(k) { V <- matrix(0, p, p); V[k, k] <- 1; V })
X_G <- matrix(1, N, 1, dimnames = list(NULL, "intercept"))

# rsDCM fit
fit <- rsdcm(narps_dcm$eta, narps_dcm$Cp, X_G, V_list, verbose = FALSE)
rownames(fit$beta_mat) <- rownames(fit$inclusion) <- narps_dcm$parameter_names

# Group-level connections selected by the spike-and-slab prior (PIP > 0.5)
sel <- fit$inclusion[, 1] > 0.5
round(cbind(estimate = fit$beta_mat[sel, 1],
            PIP      = fit$inclusion[sel, 1]), 3)

# Subjects the Student-t weighting down-weights most
w <- rowMeans(matrix(fit$weights, N, p, byrow = TRUE))
narps_dcm$subject[order(w)][1:5]

The following is an example of fitting original DCM using this package:

library(rsDCM)

# Three-region toy DCM shipped with the package (482 scans, one input)
data(toy_dcm)

# Invert. Takes roughly 75 seconds on this dataset.
fit <- dcm_estimate(toy_dcm)

# Posterior connectivity
round(fit$Ep$A, 3)

# Variational free energy (log-evidence proxy)
fit$F

The introductory vignette has more detail:

vignette("introduction", package = "rsDCM")

What’s exported

User-facing entry points:

Group-level (Parametric Empirical Bayes):

Group-level (robust and sparse, Student-t + pMOM):

  • rsdcm(): robust, sparse group DCM using Student-t subject weighting, a nonlocal product-moment (pMOM) spike-and-slab prior (inclusion probabilities), and ReML variance components.
  • rsdcm_fit(): wrapper that assembles the group model from a list of dcm_estimate() fits.

The narps_dcm dataset (48 subjects, from the openly shared NARPS data) is the runnable real-data example for rsdcm().

Lower-level utilities (dcm_vec, dcm_inv, dcm_logdet, …) are also exported and have their own help pages, so you can call them directly as dcm_vec(). They are marked @keywords internal, which only keeps them out of the package index. Access is not restricted, and the ::: operator is not needed for them.

Acknowledgment

rsDCM is a derivative work of the MATLAB SPM25 toolbox, distributed under GPL-2 by the Wellcome Centre for Human Neuroimaging. See LICENSE.note for the list of ported routines and the references.

License

GPL-2.

References