Introduction to rsDCM

Source: vignettes/introduction.Rmd

Overview

rsDCM has two related components. The novel group method performs robust and sparse inference from subject-specific DCM posterior summaries. The MATLAB- ported component provides deterministic single-state fMRI DCM inversion and Gaussian Parametric Empirical Bayes routines based on SPM25.

library(rsDCM)
#> rsDCM loaded: robust and sparse group dynamic causal modeling.

Robust and sparse group inference

For participant nn, the group method receives a first-level posterior mean and covariance. It combines the latter with a between-subject covariance and pre-whitens the resulting block. A Student-t likelihood then downweights atypical residual coordinates in the chosen whitening basis. A Gaussian-spike and nonlocal pMOM-slab prior separates negligible from supported group effects.

The mode-fitting stage is a multistart generalized EM algorithm with conditional maximization. After the empirical-Bayes mode and hyperparameters are selected, parallel-tempering MCMC integrates the coefficient-level slab responsibilities. This produces posterior inclusion probabilities and Monte Carlo standard errors. The fit also returns conditional Laplace standard deviations at the selected mode.

The bundled narps_dcm data contain corrected posterior summaries for 48 participants and 22 connectivity parameters.

data(narps_dcm)
dim(narps_dcm$eta)
#> [1] 48 22
length(narps_dcm$Cp)
#> [1] 48

The following code constructs an intercept-only design and a diagonal between-subject covariance basis. It is not evaluated while building the vignette because the parallel-tempering calculation is intentionally substantial.

N <- nrow(narps_dcm$eta)
p <- ncol(narps_dcm$eta)
X <- matrix(1, N, 1, dimnames = list(NULL, "intercept"))
V <- lapply(seq_len(p), function(j) {
  z <- matrix(0, p, p)
  z[j, j] <- 1
  z
})

fit <- rsdcm(
  narps_dcm$eta, narps_dcm$Cp, X, V,
  nu = 3, pi = 0.5,
  start_seed = 1, pip_mcmc_seed = 2
)  # takes ~3 mins in macOS 26.6.2 

fit$beta_mat
fit$beta_sd_approx
fit$inclusion
fit$inclusion_mcse
fit$pip_max_chain_range

The displayed pi is an example setting. New studies should tune hyperparameters independently of the data used for evaluation.

Single-subject DCM

The package also includes a three-region DCM specification.

data(toy_dcm)
str(toy_dcm, max.level = 1)
#> List of 11
#>  $ name   : chr "DCM_model"
#>  $ n      : int 3
#>  $ v      : num 482
#>  $ Y      :List of 5
#>  $ U      :List of 3
#>  $ xY     :List of 3
#>  $ a      : num [1:3, 1:3] 1 1 1 1 1 1 1 1 1
#>  $ b      : num [1:3, 1:3, 1] 0 0 0 1 0 0 0 1 0
#>  $ c      : num [1:3, 1] 0 0 1
#>  $ options:List of 10
#>  $ TE     : num 0.04

Full inversion can be run as follows. It is not evaluated during vignette building because it is computationally expensive.

dcm_fit <- dcm_estimate(toy_dcm)  # takes ~1 min in macOS 26.6.2
round(dcm_fit$Ep$A, 3)
dcm_fit$F

Reproducibility

For stochastic PIP integration, set both start_seed and pip_mcmc_seed. Inspect converged, objective_monotone, q_monotone, multi_start_summary, inclusion_mcse, pip_swap_acceptance, and pip_max_chain_range before interpreting a fit.

References

Arhin, G. and Sanyal, N. (2026). Robust and Sparse Group Dynamic Causal Modeling via Student-t Parametric Empirical Bayes and Nonlocal Priors. https://doi.org/10.48550/arXiv.2609.06379

Friston, K. J., Harrison, L., and Penny, W. (2003). Dynamic causal modelling. NeuroImage, 19(4), 1273–1302. https://doi.org/10.1016/S1053-8119(03)00202-7