---
title: "Diagnostics and Spike-and-Slab Summaries"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Diagnostics and Spike-and-Slab Summaries}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: refs.bib
csl: apa.csl
link-citations: TRUE
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6,
  fig.height = 4
)
```

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

```{r, eval=FALSE}
library(bgms)
data = Wenchuan[, 1:5]
fit = bgm(data, seed = 1234)
```
```{r, include=FALSE}
library(bgms)
data = Wenchuan[, 1:5]
fit <- readRDS(system.file("extdata", "fit_5items.rds", package = "bgms"))
```

Note: During fitting, progress bars are shown in interactive sessions.
In this vignette, they are suppressed for clarity. Sampling can take a while; 
the progress bars usually help track progress.

# Convergence diagnostics

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

```{r}
summary(fit)$pairwise
```

- R-hat values close to 1 (typically below 1.01) suggest convergence [@VehtariEtAl_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.

```{r, fig.width= 7, fig.height= 7}
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:

```{r}
coef(fit)$indicator
```
- 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:

```{r}
# Example for one edge
p = coef(fit)$indicator[1, 5]
BF_10 = p / (1 - p)
BF_10
```

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

```{r}
1 / BF_10
```
This Bayes factor shows that there is strong evidence for the absence of a 
network relation between the variables `intrusion` and `physior`.

# Notes on runtime

- Sampling with spike-and-slab priors can take longer.
- In interactive sessions, progress bars are displayed. In this vignette,
  they are suppressed for readability.

# Next steps

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