---
title: "Model Comparison with bgmCompare"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Model Comparison with bgmCompare}
  %\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

The function `bgmCompare()` extends `bgm()` to independent-sample designs. It
estimates whether pairwise interactions and category thresholds differ across
groups in an ordinal Markov random field [@MarsmanHaslbeck_2023_ordinal], the
member of the family that `bgm()` fits to binary and ordinal data.

Each difference is put under selection, so it carries a posterior inclusion
probability and an inclusion Bayes factor of its own -- the factor by which the
data shift the odds that the groups differ on that parameter
[@HuthEtAl_2023; @SekulovskiEtAl_2023]. `verdicts()` reads those Bayes factors
against a threshold and returns evidence of a difference, evidence of no
difference, or undecided.

# ADHD dataset

We illustrate with a subset from the `ADHD` dataset included in **bgms**.

```{r}
library(bgms)

data_adhd = ADHD[ADHD$group == 1, -1]
data_adhd = data_adhd[, 1:5]
data_no_adhd = ADHD[ADHD$group == 0, -1]
data_no_adhd = data_no_adhd[, 1:5]
```

# Fitting a model

```{r, eval = FALSE}
fit = bgmCompare(x = data_adhd, y = data_no_adhd, seed = 1234)
```

```{r, include=FALSE}
fit = bgmCompare(
  x = data_adhd, y = data_no_adhd, seed = 1234, chains = 2,
  display_progress = "none", verbose = FALSE
)
```

The baseline pairwise prior is the same at both entry points:
`interaction_prior = normal_prior(1)` in `bgm()` and in `bgmCompare()`. A
`bgmCompare()` fit set beside two separate `bgm()` fits at their stated
defaults therefore differs in the model for the groups, not in the prior on
the baseline interactions. The group differences are priced separately, by
`difference_family` (`"Normal"` by default) and `difference_scale`; these
govern both the pairwise-interaction differences and the threshold
differences, and `interaction_prior` does not reach them.

Groups often differ in which answer categories they actually use.
`bgmCompare()` models the union of the categories observed across the groups,
so a category one group uses is kept even when the other group never uses it;
only a category value that no group uses at all is dropped. When a kept
category is empty in some group, that group's data say nothing about its
threshold there, so the reported difference for that group-by-category
combination comes from the prior and will be large and very uncertain.
`bgmCompare()` warns and names each such case, and
`extract_arguments(fit)$category_support` holds the per-group category counts.
The pairwise (edge) parameters are unaffected. See `?bgmCompare` for the
details, including why Blume--Capel variables are exempt.

# Posterior summaries

The summary shows both baseline effects and group differences:

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

You can extract posterior means and inclusion probabilities:

```{r}
coef(fit)
```

Difference verdicts are scale-contingent. `bgmCompare()` prices group
differences on the association scale through `difference_scale`, and the
calibration of that default is under study, so a verdict close to a
decision threshold can move with the scale.

# Visualizing the groups

`plot()` on a `bgmCompare()` fit draws the differences by default, split by
what the data settle about each pair. `type = "groups"` draws each group's own
graph instead, on one shared layout, so the two pictures can be read side by
side: line width is that group's posterior mean association and colour carries
its sign.

```{r, fig.width = 10, fig.height = 5, out.width = "100%"}
plot(fit, type = "groups")
```

Drawing needs the **qgraph** package, which **bgms** suggests rather than
depends on. `plot(fit)` gives the difference display and
`plot(fit, type = "centrality")` the posterior strength centrality of one
group; see `?plot.bgmCompare`.

# Next steps

- For a one-sample analysis, see the *Getting Started* vignette.
- For diagnostics and convergence checks, see the *Diagnostics* vignette.
- For additional analysis tools and more advanced plotting options,
  consider using the **easybgm** package, which integrates smoothly with
  **bgms** objects.

# References