add intro to mcmc techniques for Bayesian inference

[github-actions]

Draft PR opened by @claude to address #836.

Triggered by workflow run.

Addresses #836.

[claude]

Claude finished @d-morrison's task in 3m 41s —— View job

---

Code Review — PR #837: Intro to MCMC Techniques

• Gather context and read changed files
• Review _subfiles/intro-bayes/_sec-mcmc.qmd
• Review chapters/intro-bayes.qmd modifications
• Check against CLAUDE.md conventions
• Post findings

---

Summary

The new _sec-mcmc.qmd subfile adds a well-structured introduction to MCMC covering Monte Carlo integration, the Metropolis–Hastings algorithm, Gibbs sampling, burn-in, convergence diagnostics, and posterior inference. The content is accurate and the writing follows the prose style of the book. However, there are several issues ranging from a rendering-breaking undefined macro to convention violations that need to be addressed before this is ready to merge.

---

Critical

1. \bfy macro is undefined — will break rendering

\bfy is used 13 times throughout _sec-mcmc.qmd (e.g., lines 4, 13, 16, 24, 33, 36, 48, 92, 104, 111, 118, 124, 172), but no such macro exists in latex-macros/macros.qmd or anywhere else in the codebase. The defined macro for a bold/vector $y$ is \vy (defined as \vecf{y}).

Every occurrence of \bfy should be replaced with \vy.

Fix this →

---

Significant

2. fig-cap chunk option used instead of :::{#fig-...} div format

_sec-mcmc.qmd line 213 uses #| fig-cap: "MH chain trace plot; dashed line marks end of burn-in." as a chunk option, but CLAUDE.md requires:

Use div format (:::{#fig-...}) for figures and tables, not chunk-option fig-cap/tbl-cap

The trace plot chunk should be restructured as:

:::{#exm-trace-plot}
## Trace plot for MH chain

:::{#fig-trace-mh}
```{r}
#| code-fold: show
library(ggplot2)
burnin <- 500L
df_chain <- data.frame(iteration = seq_along(mh_chain), pi = mh_chain)
ggplot(df_chain, aes(x = iteration, y = pi)) +
  geom_line(linewidth = 0.2, alpha = 0.7) +
  geom_vline(xintercept = burnin, linetype = "dashed", colour = "red") +
  labs(x = "Iteration", y = expression(pi)) +
  theme_bw()

MH chain trace plot; dashed line marks end of burn-in.
:::

:::

[Fix this →](https://claude.ai/code?q=In%20%60_subfiles%2Fintro-bayes%2F_sec-mcmc.qmd%60%20on%20branch%20%60claude%2Fissue-836-20260527-185948%60%2C%20the%20trace%20plot%20example%20at%20lines%20207-223%20uses%20%60%23%7C%20fig-cap%3A%60%20as%20a%20chunk%20option.%20Per%20CLAUDE.md%20conventions%2C%20replace%20this%20with%20a%20%60%3A%3A%3A%7B%23fig-trace-mh%7D%60%20fenced%20div%20wrapping%20the%20code%20chunk%2C%20with%20the%20caption%20as%20plain%20text%20inside%20the%20div%20after%20the%20chunk.%20Remove%20the%20%60label%3A%20fig-trace-mh%60%20and%20%60fig-cap%3A%60%20chunk%20options.&repo=d-morrison/rme)

**3. Forward reference to `@sec-mcmc-diagnostics` in the burn-in section**

`_sec-mcmc.qmd` line 192:

The length of the burn-in period is chosen by inspection of trace plots
(see @sec-mcmc-diagnostics).

This references `{#sec-mcmc-diagnostics}`, which is not defined until line 195 (the very next section heading). CLAUDE.md states "Introduce concepts before using them — no forward references." Reorder to mention trace plots after introducing convergence diagnostics, or remove the forward cross-reference.

**4. Forward reference to `@sec-jags`**

`_sec-mcmc.qmd` line 177:

JAGS (Just Another Gibbs Sampler) automates this approach for a wide class of models;
see @sec-jags for an example.

`#sec-jags` is defined after the MCMC section in `chapters/intro-bayes.qmd` (line 112). This is a forward reference. Either remove it or restructure so the mention follows the JAGS section.

---

### Moderate

**5. `library(ggplot2)` loaded inside an example chunk**

`_sec-mcmc.qmd` line 215 calls `library(ggplot2)` inside the `#exm-trace-plot` chunk. Package loading should happen in a setup chunk at the top of the parent chapter, not buried inside an example. The parent `chapters/intro-bayes.qmd` already loads `ggplot2` earlier (lines 63, 92), but a consistent setup chunk is preferred.

**6. Implicit cross-chunk variable dependencies**

`burnin` (defined at line 215 inside `#exm-trace-plot`) is referenced in `#exm-post-summary-mh` at line 264. Similarly, `mh_chain` from `#exm-mh-bernoulli` (line 160) is used in `#exm-trace-plot` (line 216). These cross-chunk dependencies are implicit and could silently break if chunks are reordered. Consider either making each example self-contained or adding a brief comment noting the dependency.

**7. `\ndist{}` preferred over `\Normal(...)`**

`_sec-mcmc.qmd` line 136 uses `\Normal(0, \sigma^2)`, but the codebase defines `\ndist{0, \sigma^2}` (`= \Normal\paren{#1}`) which auto-sizes the parentheses. Prefer `\ndist{0, \sigma^2}` for consistency.

---

### Minor / Nits

**8. `\mathrm{Beta}` — no established macro**

`_sec-mcmc.qmd` line 48: `\mathrm{Beta}(56, 37)`. There is no `\Beta` macro in `macros.qmd`; all other distribution names use `\operatorname{...}` via defined macros (e.g., `\Ber`, `\Normal`, `\Pois`). Consider adding `\def\Beta{\operatorname{Beta}}` to `macros.qmd` for consistency.

**9. Acceptance ratio in §"Why the normalizing constant..." duplicates §"MH algorithm definition"**

The acceptance ratio formula is written out twice (lines 104–106 and lines 123–126). This is intentional (prose context vs. formal definition), which is fine, but make sure the two presentations are exactly consistent — the inline prose at lines 107–109 says "accept … with probability $\min(1, \alpha)$" while the definition at line 123 folds the `min` into the formula. The current structure works but could confuse readers who compare the two.

---

### `chapters/intro-bayes.qmd` modifications

The change adds five lines:

```qmd
# Markov Chain Monte Carlo (MCMC) {#sec-mcmc}

{{< include _subfiles/intro-bayes/_sec-mcmc.qmd >}}

and removes the blank line that preceded the JAGS section. This integration is correct: the section heading is in the parent (not the subfile), satisfying the subfile convention. No issues here beyond the forward reference noted in item 4 above.

---

Verdict

This PR should not be merged in its current state due to the undefined \bfy macro (issue 1) which will cause a rendering failure. Issues 2–4 are significant convention violations. Issues 5–9 are improvements that would raise the quality to match the rest of the book.

[d-morrison]

@claude address review comments

[github-actions]

👀 Picked up by workflow run #26543221524. R/Quarto/renv setup runs first (~3-5 min); Claude itself responds after that.

[d-morrison]

@claude review

[github-actions]

👀 Picked up by workflow run #26553161091. R/Quarto/renv setup runs first (~3-5 min); Claude itself responds after that.

[claude]

Claude finished @d-morrison's task in 2m 37s —— View job

---

Code Review — PR #837 (re-review after fixes)

• Read changed files and recent commits
• Check which issues from prior review were addressed
• Review _subfiles/intro-bayes/_sec-mcmc.qmd
• Review chapters/intro-bayes.qmd
• Post findings

---

What Was Fixed

Commit 60ed663 addressed the following from the prior review:

• ✅ \bfy → \vy — all 13 occurrences replaced; rendering will no longer break
• ✅ Forward reference to @sec-jags — removed from the Gibbs section
• ✅ Forward reference to @sec-mcmc-diagnostics — removed from the burn-in section
• ✅ library(ggplot2) inside example chunk — removed; ggplot2 is already loaded at the parent chapter level (line 63)
• ✅ #| label: fig-trace-mh and #| fig-cap: chunk options — removed from trace plot chunk

---

Remaining Issues

Significant

1. Trace plot figure has no caption and no div wrapper

The fig-cap chunk option was correctly removed from #exm-trace-plot, but the fix stopped there. CLAUDE.md requires the div format for figures:

Use div format (:::{#fig-...}) for figures and tables, not chunk-option fig-cap/tbl-cap

The trace plot currently renders as an unlabeled, uncaptioned plot inside an example div — not suitable for a textbook. The chunk at _sec-mcmc.qmd lines 208–217 should be wrapped in a :::{#fig-trace-mh} div with the caption as plain text:

:::{#fig-trace-mh}
```{r}
#| code-fold: show
burnin <- 500L
df_chain <- data.frame(iteration = seq_along(mh_chain), pi = mh_chain)
ggplot(df_chain, aes(x = iteration, y = pi)) +
  geom_line(linewidth = 0.2, alpha = 0.7) +
  geom_vline(xintercept = burnin, linetype = "dashed", colour = "red") +
  labs(x = "Iteration", y = expression(pi)) +
  theme_bw()

MH chain trace plot; dashed line marks end of burn-in.
:::

[Fix this →](https://claude.ai/code?q=In%20%60_subfiles%2Fintro-bayes%2F_sec-mcmc.qmd%60%20on%20branch%20%60claude%2Fissue-836-20260527-185948%60%2C%20wrap%20the%20R%20code%20chunk%20inside%20%60%3A%3A%3A%7B%23exm-trace-plot%7D%60%20in%20a%20%60%3A%3A%3A%7B%23fig-trace-mh%7D%60%20fenced%20div%2C%20placing%20the%20caption%20text%20%22MH%20chain%20trace%20plot%3B%20dashed%20line%20marks%20end%20of%20burn-in.%22%20as%20plain%20text%20inside%20the%20div%20after%20the%20code%20chunk.%20Per%20CLAUDE.md%20conventions%2C%20figures%20must%20use%20div%20format%20not%20chunk%20options.&repo=d-morrison/rme)

---

**Moderate**

**2. `\Normal(0, \sigma^2)` — use `\ndist{}` instead**

`_sec-mcmc.qmd` line 136:

$\varepsilon \sim \Normal(0, \sigma^2)$

`\Normal` is defined as `\operatorname{N}` (bare operator, no parentheses). The macro `\ndist{0, \sigma^2}` wraps in auto-sized parentheses and should be preferred for consistency with the rest of the book.

[Fix this →](https://claude.ai/code?q=In%20%60_subfiles%2Fintro-bayes%2F_sec-mcmc.qmd%60%20on%20branch%20%60claude%2Fissue-836-20260527-185948%60%2C%20line%20136%3A%20replace%20%60%5CNormal(0%2C%20%5Csigma%5E2)%60%20with%20%60%5Cndist%7B0%2C%20%5Csigma%5E2%7D%60.%20The%20%60%5Cndist%7B%7D%60%20macro%20is%20defined%20in%20latex-macros%2Fmacros.qmd%20and%20uses%20auto-sized%20parentheses%3B%20%60%5CNormal%60%20is%20just%20the%20bare%20operator%20name.&repo=d-morrison/rme)

**3. `\mathrm{Beta}` — no established macro**

`_sec-mcmc.qmd` line 48:

$\pi \mid \vy \sim \mathrm{Beta}(56, 37)$

`\mathrm{Beta}` is raw LaTeX. No `\Beta` macro exists in `macros.qmd`. Other distributions use `\operatorname{...}` via defined macros (`\Ber`, `\Normal`, `\Pois`). Either add `\def\Beta{\operatorname{Beta}}` to `macros.qmd` and use `\Beta(56, 37)`, or use `\operatorname{Beta}(56, 37)` inline.

[Fix this →](https://claude.ai/code?q=In%20%60_subfiles%2Fintro-bayes%2F_sec-mcmc.qmd%60%20on%20branch%20%60claude%2Fissue-836-20260527-185948%60%20line%2048%2C%20replace%20%60%5Cmathrm%7BBeta%7D%60%20with%20%60%5CoperatorName%7BBeta%7D%60%20or%20add%20%60%5Cdef%5CBeta%7B%5CoperatorName%7BBeta%7D%7D%60%20to%20latex-macros%2Fmacros.qmd%20and%20use%20%60%5CBeta%60.%20%60%5Cmathrm%7BBeta%7D%60%20is%20raw%20LaTeX%20inconsistent%20with%20the%20book%27s%20macro%20conventions%20for%20distribution%20names.&repo=d-morrison/rme)

**4. Implicit cross-chunk variable dependencies**

`burnin` is defined inside `#exm-trace-plot` (line 210) but used later in `#exm-post-summary-mh` (line 259). Similarly, `mh_chain` from `#exm-mh-bernoulli` (line 160) is consumed in both `#exm-trace-plot` and `#exm-post-summary-mh`. These cross-example dependencies will silently break if chunks are reordered. Each example could either be made self-contained (redefining `burnin` inline in `#exm-post-summary-mh`) or the dependency documented with a brief note.

---

### `chapters/intro-bayes.qmd`

No new issues. The five-line addition (section heading + include) is correct and the section heading lives in the parent file, satisfying the subfile convention.

---

### Verdict

The critical rendering blocker (`\bfy`) is now fixed. The forward references and `library()` loading issues are resolved. Three moderate issues remain (figure div wrapper, `\ndist`, `\mathrm{Beta}`) plus the implicit cross-chunk dependencies. The PR can be reviewed further once the figure caption/label is restored in div format (issue 1 above) — the others are lower priority but should be addressed before merge.

[d-morrison]

@claude iterate

[github-actions]

👀 Picked up by workflow run #26641130635. R/Quarto/renv setup runs first (~3-5 min); Claude itself responds after that.

[claude]

Claude finished @d-morrison's task in 2m 11s —— View job

---

Code Review — PR #837 (post-iterate, round 3)

• Gather context and read changed files
• Check which prior-review issues were addressed by the latest commits
• Review _subfiles/intro-bayes/_sec-mcmc.qmd (current state)
• Review chapters/intro-bayes.qmd
• Post findings

---

What Was Fixed by the Iterate Commits

Commits 2f503ea and 9765de0 addressed all remaining items from the prior review:

• ✅ Trace plot wrapped in :::{#fig-trace-mh} div with caption — :::{#fig-trace-mh} … ::: now encloses the code chunk; caption text follows as plain text inside the div. Structure is correct per CLAUDE.md.
• ✅ \Normal(0, \sigma^2) → \ndist{0, \sigma^2} — line 136 now uses the auto-paren macro.
• ✅ \mathrm{Beta} → \operatorname{Beta} — line 48 fixed; no \Beta macro needed.
• ✅ burnin cross-chunk dependency — burnin <- 500L is now re-declared at the top of #exm-post-summary-mh (line 262), so that example is self-contained.

---

One Remaining Minor Nit

\hat{\mu} — use \hmu macro

_sec-mcmc.qmd line 247:

- **Posterior mean**: $\hat{\mu} = \frac{1}{T - B} \sum_{t=B+1}^{T} \vth^{(t)}$

\hmu is defined in latex-macros/macros.qmd (line 215: \def\hmu{\hat{\mu}}). Use \hmu for consistency.

Fix this →

---

Structural Note (no action required)

mh_chain is still a cross-chunk variable: it is generated in #exm-mh-bernoulli (line 160) and consumed in #exm-trace-plot (line 212) and #exm-post-summary-mh (line 263). This is pedagogically intentional — each example builds on the previous one — and the dependency is clear from the narrative. No change is needed here.

---

Verdict

All critical and significant issues from prior reviews are resolved. The only remaining item is the low-priority \hat{\mu} → \hmu nit. The PR is otherwise ready to merge.

[d-morrison]

@claude address review comments, even nits; also why doesn't https://d-morrison.github.io/rme/pr-preview/pr-837/chapters/intro-bayes.html#sec-mcmc:~:text=a%20Bernoulli%20model)-,We%20implement%20the,-MH%20algorithm%20for have an exercise number? also fix all broken crossrefs; note in ai instructions, cross-chapter crossrefs need to handled differently from within-chapter crossrefs

[github-actions]

👀 Picked up by workflow run #26988088244. R/Quarto/renv setup runs first (~3-5 min); Claude itself responds after that.

[d-morrison]

@claude also adapt the rest of the content from dobson

[claude]

Claude finished @d-morrison's task in 4m 26s —— View job

---

Code Review — PR #837 (round 6)

• Read all changed files
• Review _subfiles/intro-bayes/_sec-mcmc.qmd
• Review chapters/intro-bayes.qmd (heavily rewritten)
• Review chapters/bayesian-examples.qmd (new)
• Review chapters/mcmc-methods.qmd (new)
• Review chapters/dobson-bayes-example.qmd
• Review CLAUDE.md, quarto config, WORDLIST
• Check macro usage, cross-refs, headings, citations
• Post findings

---

What's New in This Round

intro-bayes.qmd has been substantially rewritten from a rough draft into a full chapter: new top-level sections on paradigms, Bayes' theorem, the parameter space, priors (conjugate, informative/flat, skeptical), hierarchies, and software. Two new chapters (mcmc-methods.qmd, bayesian-examples.qmd) have been added. The MCMC content previously in intro-bayes.qmd is now in mcmc-methods.qmd via the _sec-mcmc.qmd subfile.

All fixes from rounds 1–5 are intact. Five issues remain — one of them rendering-critical.

---

Critical

1. \dev macro undefined — will break rendering in mcmc-methods.qmd

mcmc-methods.qmd line 110:

The term $\dev(\bar{\vth})$ rewards fit, while $p_D$ penalizes

\dev is not defined in latex-macros/macros.qmd. The defined macro there is \devn which maps to the residual symbol e — not the DIC deviance D. The DIC definition at lines 104–105 correctly uses D(\bar{\vth}), so line 110 should match:

The term $D(\bar{\vth})$ rewards fit, while $p_D$ penalizes

Fix this →

---

Significant

2. Forward reference to @exm-normal-credible-vs-confidence in intro-bayes.qmd

intro-bayes.qmd line 87 (inside ## Two readings of an interval estimate):

@exm-normal-credible-vs-confidence makes the contrast concrete.

#exm-normal-credible-vs-confidence is defined at line 180 — 93 lines later, in the completely different section # The parameter space. CLAUDE.md: "Introduce concepts before using them — no forward references." Either move the example earlier (immediately after the credible interval definition) or remove the forward pointer.

Fix this →

3. Forward reference to @sec-bayes-conjugate in intro-bayes.qmd

intro-bayes.qmd line 132 (inside :::{#exm-normal-normal}):

the prior is called **conjugate** (@sec-bayes-conjugate).

#sec-bayes-conjugate is defined at line 265. This points forward to the conjugate-priors section from inside an example 133 lines earlier. Either drop the forward pointer, or move the example to after ## Conjugate priors.

Fix this →

4. "Recall the Beta-Bernoulli model" without a cross-chapter link (_sec-mcmc.qmd line 46)

_sec-mcmc.qmd line 46:

Recall the Beta-Bernoulli model with
$n = 91$ observations and $r = 55$ successes.

The Beta-Bernoulli model with these exact numbers is now formally introduced in #exm-beta-bernoulli in intro-bayes.qmd. Since _sec-mcmc.qmd is rendered inside mcmc-methods.qmd (a different .html file), @exm-beta-bernoulli won't resolve — use the cross-chapter link syntax:

Recall the Beta-Bernoulli model of
[Example B](intro-bayes.qmd#exm-beta-bernoulli),
with $n = 91$ observations and $r = 55$ successes.

Fix this →

---

Moderate (carry-forward from round 5)

5. Missing citation for JAGS claim (_sec-mcmc.qmd line 176)

JAGS (Just Another Gibbs Sampler) automates this approach for a wide class of models.

No citation. CLAUDE.md: "Factual claims must have a specific citation." Should add [@dobson4e, Chapter 13] or a JAGS-specific reference.

6. \hat{R} — no \hR macro (_sec-mcmc.qmd lines 234, 236, 238)

Three occurrences of $\hat{R}$. The codebase has \hmu, \hth, \hb etc. in macros.qmd. Add \def\hR{\hat{R}} to macros.qmd near the other hat-letter macros (around line 221) and replace all three.

7. \mathrm{DIC} should be \operatorname{DIC} (mcmc-methods.qmd line 105)

Inside the definition:

\mathrm{DIC} &\eqdef D(\bar{\vth}) + 2\,p_D = \overline{D} + p_D.

Distribution/operator names use \operatorname{} throughout the book. Replace with \operatorname{DIC} or add a \def\DIC{\operatorname{DIC}} macro.

---

Minor

8. \operatorname{logit} and ^\top — use macros (bayesian-examples.qmd line 41)

$\operatorname{logit}(\pi_i) = \vx_i^\top \vbeta$

Two raw-LaTeX usages:

• \operatorname{logit}(\pi_i) → \logitf{\pi_i} (macro defined in macros.qmd)
• \vx_i^\top → \tp{\vx_i} (transpose macro)

---

New Files — No Issues

chapters/dobson-bayes-example.qmd: The round-5 fixes ({{< slidebreak >}}, ## heading level, citation) are all in place. No new issues.

chapters/bayesian-examples.qmd: Content is well-structured; stub sections (logistic, survival, random-effects, BMA) are acknowledged with a ::: notes block as work-in-progress. Cross-chapter links use the correct [text](other-chapter.qmd#id) format throughout. ✅

_quarto-website.yml / _quarto-book.yml / _quarto-handout.yml: Both new chapters added to render lists and navbar correctly. ✅

CLAUDE.md: The theorem-div heading rule and cross-chapter cross-reference conventions added in round 5 are correct and well-placed. ✅

inst/WORDLIST: All 7 new entries (BMA, hyperprior, noninformative, reparameterization, reparameterizing, unconverged, WinBUGS) are legitimate technical terms. ✅

---

Verdict

One rendering-critical bug remains (\dev undefined, issue 1). Two significant forward-reference violations were introduced in the new intro-bayes.qmd content (issues 2–3). The "Recall" pointer (issue 4) and JAGS citation gap (issue 5) carry over from round 5 and still need addressing. The PR should not merge until at minimum issues 1–4 are resolved.

[claude]

Claude finished @d-morrison's task in 5m 2s —— View job

---

Code Review — PR #837 (round 7)

• Read current state of all changed files
• Check which round-6 issues were addressed by latest commits
• Review _subfiles/intro-bayes/_sec-mcmc.qmd
• Review chapters/intro-bayes.qmd
• Review chapters/mcmc-methods.qmd
• Review chapters/bayesian-examples.qmd
• Check macro definitions
• Post findings

---

What's New Since Round 6

Commit a8ad558 restructured the Bayesian appendix into three chapters, and commit 57dfc01 added worked JAGS examples (logistic regression, survival, random-effects) to bayesian-examples.qmd. The new content is well-structured and the R/JAGS code is technically correct (including proper zeros-trick censored likelihood). All round-5 fixes are intact.

None of the seven round-6 findings were addressed by these commits — they remain open.

---

Carry-forward: Critical

1. \dev macro undefined — will break rendering (mcmc-methods.qmd line 110)

The term $\dev(\bar{\vth})$ rewards fit, while $p_D$ penalizes

\dev is not defined in latex-macros/macros.qmd. The only deviance-related macro is \devn (= \deviation = the residual letter e), which is unrelated. The definition at line 104 uses D(\bar{\vth}), so line 110 should match:

The term $D(\bar{\vth})$ rewards fit, while $p_D$ penalizes

Fix this →

---

Carry-forward: Significant

2. Forward reference @exm-normal-credible-vs-confidence (intro-bayes.qmd line 87)

@exm-normal-credible-vs-confidence is defined at line 180 (in # The parameter space), 93 lines after it is referenced. CLAUDE.md: no forward references.

Fix this →

3. Forward reference @sec-bayes-conjugate (intro-bayes.qmd line 132)

Inside :::{#exm-normal-normal} (line 132):

the prior is called **conjugate** (@sec-bayes-conjugate).

#sec-bayes-conjugate is defined at line 265. Forward reference, 133 lines ahead.

Fix this →

4. "Recall the Beta-Bernoulli model" needs cross-chapter link (_sec-mcmc.qmd line 46)

Recall the Beta-Bernoulli model with
$n = 91$ observations and $r = 55$ successes.

#exm-beta-bernoulli is now formally defined in intro-bayes.qmd. Since _sec-mcmc.qmd renders inside mcmc-methods.qmd (a different HTML file), @exm-beta-bernoulli would not resolve. Use the cross-chapter link format per CLAUDE.md:

Recall the Beta-Bernoulli model of
[Example B](intro-bayes.qmd#exm-beta-bernoulli),
with $n = 91$ observations and $r = 55$ successes.

Fix this →

---

Carry-forward: Moderate

5. Missing citation for JAGS claim (_sec-mcmc.qmd line 176)

JAGS (Just Another Gibbs Sampler) automates this approach for a wide class of models.

CLAUDE.md: "Factual claims must have a specific citation." Add [@dobson4e, Chapter 13].

Fix this →

---

Carry-forward: Minor nits

6. \hat{R} — no \hR macro

Used in three places in _sec-mcmc.qmd (lines 234, 236, 238) and once in bayesian-examples.qmd (line 95, where it appears as $\hat R$ in the psrf description). Add \def\hR{\hat{R}} to latex-macros/macros.qmd near the other hat-letter macros (\hmu, \hth, \hb, line ~221) and replace all four occurrences.

Fix this →

7. \mathrm{DIC} — use \operatorname{DIC} (mcmc-methods.qmd line 105)

\mathrm{DIC} &\eqdef D(\bar{\vth}) + 2\,p_D = \overline{D} + p_D.

Distribution/operator names use \operatorname{} throughout the book. Replace with \operatorname{DIC} (or add a \def\DIC{\operatorname{DIC}} macro).

Fix this →

8. \operatorname{logit} and ^\top — use macros (bayesian-examples.qmd line 41)

$\operatorname{logit}(\pi_i) = \vx_i^\top \vbeta$

Two raw-LaTeX usages:

• \operatorname{logit}(\pi_i) → use the macro \logit(\pi_i) (defined as \operatorname{logit})
• \vx_i^\top → use \tp{\vxi} (macro: \providecommand{\tp}[1]{{#1}\'}, listed in CLAUDE.md as a key macro; \vxi = \vecf{x}_i)

Fix this →

---

New content — no issues

The three new JAGS examples in bayesian-examples.qmd (logistic regression, exponential survival with zeros trick, random-intercept model) are technically correct: the censored log-likelihoods are right, the priors are appropriate, the monitored derived quantities (OR, HR, sigma, tau) are correctly specified, and the JAGS model strings match the data list. initsfunction is in scope because dobson-bayes-example.qmd is included at line 36, before all three uses. The BMA section correctly limits itself to prose (no unimplemented stub example). Cross-chapter links in the new sections all use the correct [text](other-chapter.qmd#id) format. ✅

---

Verdict

Seven issues carry forward from round 6 (all still present), with issue 1 (\dev) a rendering-critical blocker. Issue 6 now extends to bayesian-examples.qmd line 95 in addition to the three existing locations. The new JAGS examples are otherwise clean.

[d-morrison]

@claude address reviews

[github-actions]

👀 Picked up by workflow run #27047682804. R/Quarto/renv setup runs first (~3-5 min); Claude itself responds after that.

[claude]

Claude finished @d-morrison's task in 2m 51s —— View job

---

Code Review — PR #837 (round 8)

• Read current state of changed files
• Verify round-7 carry-forward issues
• Check macro definitions
• Post findings

---

What Was Fixed Since Round 7

All seven round-7 findings were addressed:

• ✅ \dev → D(\bar{\vth}) — mcmc-methods.qmd line 110 now uses D(\bar{\vth}) directly; no undefined macro.
• ✅ \mathrm{DIC} → \operatorname{DIC} — line 105 of mcmc-methods.qmd corrected.
• ✅ JAGS citation — [@dobson4e, Chapter 13] added at _sec-mcmc.qmd line 178.
• ✅ "Recall" → cross-chapter link — _sec-mcmc.qmd line 46–48 now reads Recall the Beta-Bernoulli model of [the conjugate-prior example](intro-bayes.qmd#exm-beta-bernoulli), with…
• ✅ Forward reference @exm-normal-credible-vs-confidence — removed from intro-bayes.qmd; the example itself now sits in # The parameter space without a prior pointer.
• ✅ Forward reference @sec-bayes-conjugate — removed from inside :::{#exm-normal-normal}; the section text at line 130–131 introduces the term "conjugate" informally without a forward cross-reference.
• ✅ \operatorname{logit} / ^\top — bayesian-examples.qmd line 41 now uses \logit(\pi_i) = \tp{\vxi}\vbeta.

---

One Remaining Nit

\hat{R} / \hat R — no \hR macro (4 occurrences)

\hat{R} is used raw in three lines of _subfiles/intro-bayes/_sec-mcmc.qmd:

• Line 236: The **Gelman--Rubin statistic** $\hat{R}$
• Line 238: $\hat{R} \approx 1$ indicates convergence
• Line 240: A common rule of thumb is $\hat{R} < 1.1$.

And once in chapters/bayesian-examples.qmd:

• Line 95: the convergence statistic \psrf` ($\hat R$) is near $1$.`

The codebase defines \hmu (\def\hmu{\hat{\mu}}), \hth (\def\hth{\hat\theta}), \hb (\def\hb{\hat \beta}) etc. in latex-macros/macros.qmd near line 221. There is no \hR macro. To match the convention, add \def\hR{\hat{R}} to macros.qmd near line 221 (next to \hmu) and replace all four raw \hat{R} / \hat R occurrences with \hR.

Fix this →

---

Verdict

All critical, significant, and moderate issues from all prior rounds are resolved. The only remaining item is the low-priority \hat{R} → \hR nit (4 occurrences). The PR is ready to merge after that fix.

[claude]

Claude finished @d-morrison's task in 2m 41s —— View job

---

Code Review — PR #837 (round 9)

• Read current state of changed files
• Verify round-8 carry-forward nit (\hat{R} → \hR)
• Review new BMA illustration in bayesian-examples.qmd
• Check macro definitions
• Post findings

---

What's New Since Round 8

Commit 4db7585 added a concrete BMA illustration (#exm-bayes-bma) to bayesian-examples.qmd, completing the previously-prose-only # Bayesian model averaging section with a working R example that enumerates all $2^3 = 8$ subsets of three predictors, computes BIC-based model weights, posterior inclusion probabilities, and a model-averaged slope. The structure and R code are technically correct.

---

Carry-forward: Nit

1. \hat{R} / \hat R — no \hR macro (4 occurrences)

Still unresolved from round 8. Raw \hat{R} appears in three lines of _subfiles/intro-bayes/_sec-mcmc.qmd:

• Line 236: The **Gelman--Rubin statistic** $\hat{R}$
• Line 238: $\hat{R} \approx 1$ indicates convergence
• Line 240: A common rule of thumb is $\hat{R} < 1.1$.

And once in chapters/bayesian-examples.qmd:

• Line 95: the convergence statistic `psrf` ($\hat R$) is near $1$.

No \hR macro exists in latex-macros/macros.qmd. The codebase defines \hmu, \hth, \hb, etc. near line 221. Add \def\hR{\hat{R}} there and replace all four occurrences.

Fix this →

---

New issue from the BMA addition

2. \mathrm{BIC} — use \operatorname{BIC} (bayesian-examples.qmd line 248)

$p(m \mid \vy) \propto \expf{-\tfrac{1}{2}\mathrm{BIC}_m}$

\mathrm{BIC} is raw LaTeX. The same issue was caught and fixed for \mathrm{DIC} → \operatorname{DIC} in mcmc-methods.qmd (round 7). The convention throughout the book is \operatorname{} for operator/criterion names. Replace with \operatorname{BIC}_m.

Fix this →

---

New content — no issues

bayesian-examples.qmd BMA section:

• \expf is correctly used (defined in macros.qmd line 293) ✅
• @schwarz1978estimating key exists in references.bib ✅
• :::{#exm-bayes-bma} uses #### heading per convention ✅
• Cross-chapter links (mcmc-methods.qmd#sec-mcmc-dic, predictor-selection.qmd) use the correct file-path format ✅
• R code enumerates all $2^3 = 8$ subsets correctly (via combn with 0:3), BIC weights, PIP computation, and model-averaged slope are all technically correct ✅

---

Verdict

Two items remain: the carry-forward \hat{R} nit (1 macro + 4 substitutions) and the new \mathrm{BIC} → \operatorname{BIC} nit from the BMA addition. Both are minor. The PR is otherwise ready to merge.

[claude]

Claude finished @d-morrison's task in 2m 34s —— View job

---

Code Review — PR #837 (round 10)

• Read current state of changed files
• Verify round-9 nits (\hR macro and \operatorname{BIC}) were addressed
• Scan for any new issues
• Post findings

---

What Was Fixed Since Round 9

Commit 8949cba addressed both remaining items:

• ✅ \def\hR{\hat{R}} added to macros.qmd — defined at line 100, adjacent to \hb, \hvb, \hk and other hat-letter macros.
• ✅ All 4 raw \hat{R} / \hat R occurrences replaced with \hR — _subfiles/intro-bayes/_sec-mcmc.qmd lines 236, 238, 240 and chapters/bayesian-examples.qmd line 95.
• ✅ \mathrm{BIC} → \operatorname{BIC} — bayesian-examples.qmd line 248.

---

No Remaining Issues

A scan of all changed files for lingering raw-LaTeX operator names (\mathrm{}), raw \hat{} hat-macros, --- slidebreaks, ## headings inside theorem/def/exm divs, forward references, and broken cross-chapter links found nothing outstanding.

---

Verdict

All critical, significant, moderate, and minor issues from rounds 1–9 are resolved. The PR is ready to merge.

[claude]

Claude finished @d-morrison's task in 3m 59s —— View job

---

Code Review — PR #837 (round 11)

• Read current state of all changed files
• Check macro definitions (\hR, \operatorname{BIC}, \operatorname{DIC})
• Verify all prior-round fixes are intact
• Scan for new issues in all changed files
• Post findings

---

What Was Fixed Since Round 10

The merge commit 24488af brought in origin/main; no content changes were made since round 10. All fixes from rounds 1–10 are intact:

• ✅ \hR macro added to latex-macros/macros.qmd line 100
• ✅ All 4 \hat{R} / \hat R occurrences replaced with \hR
• ✅ \mathrm{BIC} → \operatorname{BIC} in bayesian-examples.qmd line 248
• ✅ #### headings in all theorem/def/exm divs — confirmed across all four changed .qmd files
• ✅ No undefined macros, no forward references, no cross-chapter @id references without file paths
• ✅ CLAUDE.md cross-reference and theorem-div heading conventions in place

---

One Nit

library(ggplot2) inside #exm-normal-credible-vs-confidence (intro-bayes.qmd line 208)

ggplot2 is already loaded for every chapter via chapters/r-config.qmd (loaded through shared-config.qmd). The library(ggplot2) call inside the example chunk is redundant and inconsistent with the pattern used everywhere else in the book — including the analogous fix made to _sec-mcmc.qmd in round 2. It can be removed without affecting rendering.

Fix this →

---

Verdict

All critical, significant, and moderate issues from all prior rounds are resolved. The only remaining item is the low-priority redundant library(ggplot2) call. The PR is ready to merge once that nit is addressed (or can merge as-is since it is non-breaking).

[github-actions]

PR Preview Action v1.8.1
🚀 Preview available at: https://d-morrison.github.io/rme/pr-preview/pr-837/

_{Built to branch gh-pages at 2026-06-09 08:16 UTC.}