---
title: "Introduction to rsDCM"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to rsDCM}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

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

```{r setup}
library(rsDCM)
```

# Robust and sparse group inference

For participant \(n\), 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.

```{r}
data(narps_dcm)
dim(narps_dcm$eta)
length(narps_dcm$Cp)
```

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.

```{r, eval = FALSE}
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.

```{r}
data(toy_dcm)
str(toy_dcm, max.level = 1)
```

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

```{r, eval = FALSE}
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>
