API reference

RegressionDynamicCausalModeling

A Julia package for estimating whole-brain effective connectivity using the regression dynamic causal modeling (rDCM) framework.

The alias rDCM is exported for the package name.

DCM

Abstract supertype for a DCM.

mutable struct LinearDCM <: DCM

Representation of a linear DCM.

Fields

• a::BitMatrix: Binary indicator matrix for endogenous connectivity

• c::BitMatrix: Binary indicator matrix for driving inputs

• scans::Int64: number of data points per region

• nr::Int64

• U::Union{Nothing, InputU}: input structure with information about driving input

• Y::Union{Nothing, BoldY}: data structure containing BOLD signal

• Ep::RegressionDynamicCausalModeling.TrueParamLinear: connectivity parameters (A and C matrix)

• Conf::Union{Nothing, Confound}: confound structure

LinearDCM(a, c, scans, nr, U, Y, Ep, Conf)

Constructor with sanity checks for LinearDCM. See type description for information about arguments.

LinearDCM(
    a::Array{T1<:Number, 2},
    c::Array{T2<:Number, 2},
    scans::Int64,
    nr::Int64,
    U::Union{Nothing, InputU},
    Y::Union{Nothing, BoldY},
    Ep::RegressionDynamicCausalModeling.TrueParamLinear
) -> LinearDCM

Create linear DCM.

Arguments

• a::Matrix: Binary indicator matrix for endogenous connectivity
• c::Matrix: Binary indicator matrix for driving inputs
• scans::Int: Number of data points per region
• nr::Int: Number of regions
• U::InputU: Input structure
• Y::Union{BoldY,Nothing}: Data structure containing BOLD signal, can be nothing
• EP::TrueParamLinear: Connectivity parameters containing A and C matrix

LinearDCM(dcm::DCM) -> LinearDCM

Create linear DCM from a bilinear or nonlinear DCM dcm.

LinearDCM(
    rdcm::RDCM,
    output::RegressionDynamicCausalModeling.ModelOutput
) -> LinearDCM

Create linear DCM from an rDCM structure rdcm and output from model inversion output.

mutable struct BiLinearDCM <: DCM

Representation of a bi-linear DCM.

Fields

• a::BitMatrix: Binary indicator matrix for endogenous connectivity

• b::BitArray{3}: Binary indicator matrix for bi-linear dynamics.

• c::BitMatrix: Binary indicator matrix for driving inputs

• scans::Int64: number of data points per region

• nr::Int64

• U::Union{Nothing, InputU}: input structure with information about driving input

• Y::Union{Nothing, BoldY}: data structure containing BOLD signal

• Ep::RegressionDynamicCausalModeling.TrueParamBiLinear: connectivity parameters (A, B and C matrix)

• Conf::Union{Nothing, Confound}: confound structure

BiLinearDCM(a, b, c, scans, nr, U, Y, Ep, Conf)

Constructor with sanity checks for BiLinearDCM. See type description for information about arguments.

mutable struct NonLinearDCM <: DCM

Representation of a non-linear DCM.

Fields

• a::BitMatrix: Binary indicator matrix for endogenous connectivity

• b::BitArray{3}: Binary indicator matrix for bi-linear dynamics.

• c::BitMatrix: Binary indicator matrix for driving inputs

• d::BitArray{3}: Binary indicator matrix for non-linear dynamics

• scans::Int64: number of data points per region

• nr::Int64

• U::Union{Nothing, InputU}: input structure with information about driving input

• Y::Union{Nothing, BoldY}: data structure containing BOLD signal

• Ep::RegressionDynamicCausalModeling.TrueParamNonLinear: connectivity parameters (A, B, C and D matrix)

• Conf::Union{Nothing, Confound}: confound structure

NonLinearDCM(a, b, c, d, scans, nr, U, Y, Ep, Conf)

Constructor with sanity checks for NonLinearDCM. See type description for information about arguments.

struct InputU

Input structure for a DCM.

Fields

• u::Matrix{Float64}: Driving input

• dt::Float64: Sampling interval

• name::Vector{String}: Input names

mutable struct BoldY

Struct for BOLD signal.

Fields

• y::Union{Nothing, Matrix{Float64}}: BOLD signal

• dt::Float64: Sampling interval

• name::Union{Nothing, Vector{String}}: Brain region names

struct Confound

Information about confounds.

Fields

• X0::VecOrMat{Float64}: Confound matrix of size number of datapoints times number of confounds.

• name::Vector{String}: Confound names

RDCM

Abstract supertype for a rigid or sparse rDCM.

mutable struct RigidRdcm <: RDCM

Representation of an rDCM with fixed network architecture.

Fields

• a::BitMatrix: Binary indicator matrix for endogenous connectivity

• c::BitMatrix: Binary indicator matrix for driving inputs

• scans::Int64: Number of data points per region

• nr::Int64

• U::InputU: Input structure with information about driving input

• Y::BoldY: Data structure containing BOLD signal

• Ep::RegressionDynamicCausalModeling.TrueParamLinear: Connectivity parameters (A and C matrix)

• Conf::Confound: Confound structure

• hrf::Vector{Float64}: Hemodynamic response function

RigidRdcm(a, c, scans, nr, U, Y, Ep, Conf, hrf)

Constructor with sanity checks for RigidRdcm. See type description for information about arguments.

RigidRdcm(dcm::LinearDCM) -> RigidRdcm

Construct a RigidRdcm based on a linear DCM.

struct RigidOutput <: RegressionDynamicCausalModeling.ModelOutput

Output after inversion of RigidRdcm.

Fields

• F::Float64: Negative free energy of the whole model

• F_r::Vector{Float64}: Region specific negative free energy

• iter_all::Vector{Int64}: Number of iterations per region until convergence

• α::Vector{Float64}: Posterior shape parameter for noise

• β::Vector{Float64}: Posterior rate parameter for noise

• μ::Matrix{Float64}: Posterior mean for connectivity parameters

• Σ::Vector{SparseArrays.SparseMatrixCSC{Float64, Int64}}: Posterior covariance for connectivity parameters

• inversion::String: Inversion method

mutable struct SparseRdcm <: RDCM

Representation of a sparse rDCM (sparsity constraints on network architecture).

Fields

• a::BitMatrix: Binary indicator matrix for endogenous connectivity

• c::BitMatrix: Binary indicator matrix for driving inputs

• scans::Int64: Number of data points per region

• nr::Int64

• U::InputU: Input structure with information about driving input

• Y::BoldY: Data structure containing BOLD signal

• Ep::RegressionDynamicCausalModeling.TrueParamLinear: Connectivity parameters (A and C matrix)

• Conf::Confound: Confound structure

• hrf::Vector{Float64}: Hemodynamic response function

• inform_p0::Bool: Inform region specific sparseness (e.g., by anatomical information)

• p0::Float64: Prior belief about network sparseness

SparseRdcm(
    a,
    c,
    scans,
    nr,
    U,
    Y,
    Ep,
    Conf,
    hrf,
    inform_p0,
    p0
)

Constructor with sanity checks for SparseRdcm. See type description for information about arguments.

SparseRdcm(dcm::LinearDCM; inform_p0, p0) -> SparseRdcm

Construct a SparseRdcm based on a linear DCM.

Arguments

• dcm: DCM model
• inform_p0::Bool: Inform region specific sparseness (e.g., by anatomical information)
• p0::Float64: Prior belief about network sparseness

struct SparseOutput <: RegressionDynamicCausalModeling.ModelOutput

Output after inversion of SparseRdcm.

Fields

• F::Float64: Negative free energy of the whole model

• F_r::Vector{Float64}: Region specific negative free energy

• iter_all::Vector{Int64}: Number of iterations per region until convergence

• α::Vector{Float64}: Posterior shape parameter for noise

• β::Vector{Float64}: Posterior rate parameter for noise

• μ::Matrix{Float64}: Posterior mean for connectivity parameters

• Σ::Vector{SparseArrays.SparseMatrixCSC{Float64, Int64}}: Posterior covariance for connectivity parameters

• Z::Matrix{Float64}: Posterior for binary indicator variables

• inversion::String: Inversion method

load_DCM(path::String;verbose=true)

Load a DCM from a specified path and return either a linear, bilinear or nonlinear DCM based on the contents of the file.

Arguments

• path::String: Path to the file to load. Can end with .mat for Matlab files or .jls for data serialized by Julia.
• verbose::Bool: Verbosity
• dcm_key::String: It is assumed that the variable in MATLAB that was saved as a DCM.mat file was called "DCM". If this is not the case, set dcm_key to the variable name that was used (applies only when loading .mat files).

Output

• dcm: DCM struct (can be a linear, bilinear on nonlinear DCM)

Examples

julia> dcm = load_DCM("myDCM.jls";verbose=false)

save_DCM(path, dcm)

Save a DCM struct either as .mat or .jls file.

Arguments

• path::String: Path defining where to save file. If ends with .mat -> saves as Matlab file. If ends with .jls -> Serializes using Julias Serialization.
• dcm<:DCM: DCM struct (can be a linear, bilinear on nonlinear DCM)

Examples

julia> save_DCM("./myDCM.mat",dcm)

export_to_SPM(path, rdcm, output)

Export a DCM with output after model inversion as an SPM compatible .mat file.

Arguments

• path::String: Path defining where to save file. Needs to end with .mat
• rdcm::RigidRdcm: An rDCM model.
• output::RigidOutput: Output after model inversion.

Examples

julia> export_to_SPM("DCM.mat",rdcm,output)

load_example_DCM()

Loads an example DCM (linear DCM with 50 regions). The network architecture is based on the S50 structure introduced in Smith et al. (2011). Network modelling methods for FMRI. NeuroImage. This DCM can be used to generate synthetic data.

Examples

julia> dcm = load_example_DCM()
julia> y_noise, _, _, _ = generate_BOLD(dcm;SNR=10)

generate_BOLD(dcm; SNR, TR=NaN, rng=Xoshiro(), triple_input=true)

Generate synthetic BOLD signal timeseries based on a DCM.

Arguments

• dcm::T where T <: DCM: DCM structure (can be a linear, bilinear on nonlinear DCM)
• SNR::Real: Signal to noise ratio
• TR::Real: Sampling interval in seconds (can be omitted if dt is specified in dcm.Y)
• rng::AbstractRNG: Random number generator for noise sampling.
• triple_input::Bool: whether or not to triple the input (to avoid edge effects during

convolution with HRF)

Output

• y_noise::Matrix{Float64}: BOLD signal timeseries with noise
• y::Matrix{Float64}: BOLD signal timeseries without noise
• x::Matrix{Float64}: Neuronal signal
• h::Vector{Float64}: Hemodynamic response function

Examples

julia> y_noise, y, x, h = generate_BOLD(load_example_DCM();SNR=10)

predict(
    rdcm::RDCM,
    output::RegressionDynamicCausalModeling.ModelOutput
) -> Any

Predict BOLD signal based on parameter estimates after model inversion.

Arguments

• rdcm: rDCM struct that was used to estimate parameters.
• output: Output of model inversion.

Output

• y_pred::Matrix{Float64}: predicted BOLD signal

struct RigidInversionParams <: RegressionDynamicCausalModeling.AbstractInvParam

Settings for model inversion specific to rigid rDCM (fixed network architecture).

Fields

• maxIter::Int64: Maximum number of iterations per region

• tol::Float64: Tolerance for convergence

RigidInversionParams(; maxIter=500, tol=1.0e-5)

Constructor for RigidInversionParams. See type description for information about arguments.

struct SparseInversionParams <: RegressionDynamicCausalModeling.AbstractInvParam

Settings for model inversion specific to sparse rDCM.

Fields

• maxIter::Int64: Maximum number of iterations per region

• tol::Float64: Tolerance for convergence

• reruns::Int64: Number of reruns

• restrictInputs::Bool: Whether or not to estimate sparsity for C matrix. If true, the Bernoulli posteriors for the C matrix are not pruned.

SparseInversionParams(; maxIter=500, tol=1.0e-5, reruns=100, restrictInputs=true)

Constructor for SparseInversionParams. See type description for information about arguments.

struct Options{T<:RegressionDynamicCausalModeling.AbstractInvParam}

Settings for model inversion.

Fields

• invParams::RegressionDynamicCausalModeling.AbstractInvParam: Model specific inversion settings.

• verbose::Int64: Verbosity during inversion (0,1 or 2)

• synthetic::Bool: Whether or not synthetic data is used.

• testing::Bool: Used for testing

• rng::Random.AbstractRNG: Random number generator

Options(invParams::T;synthetic::Bool,verbose=1,testing=false,rng=Xoshiro())

Constructor for Options. See type description for information about arguments.

invert(rdcm::RigidRdcm, opt::Options) -> RigidOutput

Invert an rDCM model specified by rdcm with fixed network architecture using specific inversion settings defined in opt.

invert(rdcm::SparseRdcm, opt::Options) -> SparseOutput

Invert a sparse rDCM model specified by rdcm using specific inversion settings defined in opt.