# Diagnostics and Spike-and-Slab Summaries

# Introduction

This vignette illustrates how to inspect convergence diagnostics and how to interpret spike-and-slab summaries in bgms models. For some of the model variables spike-and-slab priors introduce binary indicator variables that govern whether the effect is included or not. Their posterior distributions can be summarized with inclusion probabilities and Bayes factors.

# Example fit

We use a subset of the Wenchuan dataset:

    library(bgms)
    data = Wenchuan[, 1:5]
    fit = bgm(data, seed = 1234)

# Convergence diagnostics

The quality of the Markov chain can be assessed with common MCMC diagnostics:

    summary(fit)$pairwise
    #>                          mean          sd        mcse      n_eff      Rhat
    #> intrusion-dreams  0.629828116 0.002291221 0.068169698  885.21501 1.0023691
    #> intrusion-flash   0.338792038 0.001941041 0.064550269 1105.92738 1.0022895
    #> intrusion-upset   0.180137907 0.083207282 0.008851147   88.37381 1.0068669
    #> intrusion-physior 0.194800560 0.072469527 0.005694849  161.93715 0.9997835
    #> dreams-flash      0.499629583 0.001461122 0.060718053 1726.88119 1.0002101
    #> dreams-upset      0.230678286 0.002217843 0.054921881  613.23815 1.0029526
    #> dreams-physior    0.006216451 0.024502216 0.001357229  325.91525 1.0038382
    #> flash-upset       0.011001866 0.033799896 0.002088839  261.83080 1.0207491
    #> flash-physior     0.306863313 0.001546074 0.053879439 1214.46631 1.0047284
    #> upset-physior     0.714164491 0.001964224 0.061314942  974.42987 1.0007066

- R-hat values close to 1 (typically below 1.01) suggest convergence (Vehtari et al., 2021).
- The effective sample size (ESS) reflects the number of independent samples that would provide equivalent precision. Larger ESS values indicate more reliable estimates.
- The Monte Carlo standard error (MCSE) measures the additional variability introduced by using a finite number of MCMC draws. A small MCSE relative to the posterior standard deviation indicates stable estimates, whereas a large MCSE suggests that more samples are needed.

Advanced users can inspect traceplots by extracting raw samples and using external packages such as `coda` or `bayesplot`. Here is an example using the `coda` package to create a traceplot for a pairwise effect parameter.

    library(coda)

    param_index = 1
    chains = lapply(fit$raw_samples$pairwise, function(mat) mat[, param_index])
    mcmc_obj = mcmc.list(lapply(chains, mcmc))

    traceplot(mcmc_obj,
      col = c("firebrick", "steelblue", "darkgreen", "goldenrod"),
      main = "Traceplot of pairwise[1]"
    )

# Spike-and-slab summaries

The spike-and-slab prior yields posterior inclusion probabilities for edges:

    coef(fit)$indicator
    #>           intrusion dreams  flash  upset physior
    #> intrusion     0.000  1.000 1.0000 0.8860   0.941
    #> dreams        1.000  0.000 1.0000 1.0000   0.062
    #> flash         1.000  1.000 0.0000 0.0985   1.000
    #> upset         0.886  1.000 0.0985 0.0000   1.000
    #> physior       0.941  0.062 1.0000 1.0000   0.000

- Values near 1.0: strong evidence the edge is present.
- Values near 0.0: strong evidence the edge is absent.
- Values near 0.5: inconclusive (absence of evidence).

# Bayes factors

When the prior inclusion probability for an edge is equal to 0.5 (e.g., using a Bernoulli prior with `inclusion_probability = 0.5` or a symmetric Beta prior, `main_alpha = main_beta`), we can directly transform inclusion probabilities into Bayes factors for edge presence vs absence:

    # Example for one edge
    p = coef(fit)$indicator[1, 5]
    BF_10 = p / (1 - p)
    BF_10
    #> [1] 15.94915

Here the Bayes factor in favor of inclusion (H1) is small, meaning that there is little evidence for inclusion. Since the Bayes factor is transitive, we can use it to express the evidence in favor of exclusion (H0) as

    1 / BF_10
    #> [1] 0.06269926

This Bayes factor shows that there is strong evidence for the absence of a network relation between the variables `intrusion` and `physior`.

# Next steps

- See Getting Started for a simple one-sample workflow.
- See Model Comparison for group differences.

Vehtari, A., Gelman, A., Simpson, D., Carpenter, B., & Bürkner, P.-C. (2021). Rank-normalization, folding, and localization: An improved \(\hat{R}\) for assessing convergence of MCMC. Bayesian Analysis, 16(2), 667–718. https://doi.org/10.1214/20-BA1221