Estimate a Dynamic Causal Model for fMRI

Source: R/DCM.R

Inverts a fully-specified DCM using variational Laplace inversion. This is the main user-facing entry point of the package. Mirrors SPM25's dcm_estimate. Progress is reported via message() and can be silenced with suppressMessages().

dcm_estimate(P, save = FALSE)

Arguments

P

A DCM list, or a path to an .RData/.rds file containing one.

save

Logical. If TRUE and P is a file path, the estimated DCM is saved back to that path.

Value

The estimated DCM (a list) with posterior fields populated. The main fields of interest are Ep (posterior expectations, with Ep$A, Ep$B, Ep$C the connectivity estimates), Cp (posterior covariance), Pp (posterior probabilities), and F (the negative free energy, used for model comparison).

Supported model variants

This release implements only the deterministic, single-state fMRI DCM. The two-state (options$two_state), stochastic (options$stochastic) and spectral / cross-spectral-density (options$induced) variants are not yet implemented: switching any of them on causes dcm_estimate to stop with an informative error. These variants are planned for a future update. Non-linear DCM (a non-empty d array) is supported.

See also

dcm_nlsi_GN for the underlying inversion, dcm_fmri_priors for the priors it constructs.

Examples

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

# \donttest{
# Full inversion of the bundled three-region model (takes about a minute).
# Progress reporting goes through message(), so it can be silenced.
fit <- suppressMessages(dcm_estimate(toy_dcm))
round(fit$Ep$A, 3)   # posterior connectivity estimates
#>        [,1]   [,2]  [,3]
#> [1,] -0.023 -0.449 0.060
#> [2,] -0.214  0.081 0.087
#> [3,] -0.090 -0.012 0.132
round(fit$Pp$A, 3)   # posterior probability each connection is non-zero
#>       [,1]  [,2]  [,3]
#> [1,] 0.550 1.000 0.747
#> [2,] 0.981 0.742 0.881
#> [3,] 0.771 0.520 0.863
fit$F                # negative free energy, for model comparison
#> [1] -859.2568
# }