Box ch. 11 content into numbered divs and callouts

[d-morrison]

Requested by Ezra · project thread

Part of #77

Before: ch. 11 (why model?) had 2 definitions and 3 examples in numbered divs. Most of the chapter was plain prose, bullet lists, or speaker notes. Fine Points 11.1-11.2 and Technical Point 11.1 were callouts that mixed definitions and claims, so none of them could be cross-referenced.

After: 52 numbered boxes. Every definition comes before its first use.

• 18 definitions: parametric conditional mean model (with functional form and parametric estimator), OLS residual and predicted value, borrowing information, model and correct specification, parsimonious model, identifiability vs. modeling assumptions, Fisher consistency, linear in the parameters, smoothing, calibrated interval, bias-variance trade-off, credible interval, conditional mean model with a link function, semiparametric model, kernel regression and GAM. The existing def-saturated-model and def-nonparametric-estimator are kept. The saturated-model definition now says when counting parameters works.
• 2 propositions, each with a proof I wrote:
  • OLS with a dichotomous treatment reproduces the two sample averages. This is the book's "not a coincidence", with the condition that both groups are nonempty.
  • A model nested in a larger one: if the smaller model is correctly specified, so is the larger one.
• 15 examples: the existing exm-linear-model, exm-saturated and exm-quadratic-model are kept. The HIV setting (each figure uses its own 16-person data set), the three treatment codings, and link functions are new.
• 15 remarks, 1 algorithm (two-step parametric estimation) and 1 crossref table (tbl-two-models).
• Callouts: 5 warning, 1 important and 1 tip.
• Book boxes: Fine Points 11.1-11.2 and Technical Point 11.1 follow the ch. 7 (Box ch. 7 content into numbered divs and callouts #124) convention. Each keeps its titled .callout-note with a short intro, and its definitions and remarks follow as sibling divs. No div sits inside a callout or .notes. Win#122 added no ch. 11 callouts, and none were missing.
• Every existing id and heading is kept (sec-bias-variance too). One added word, invertible, went into inst/WORDLIST.

How: existing text was wrapped, and wording that tracked the book closely was paraphrased. An 8-gram check against pdftotext of the chapter leaves only two short quoted, cited phrases.

Corrections found in review:

• The displayed arithmetic now marks 216.9 and 197.1 as coming from the unrounded estimates.
• "Smoothest" is limited to the polynomial models discussed.
• Interpolation now requires distinct doses.
• The log link is described by a positive conditional mean, not positive outcomes.

Checks:

• quarto render chapters/11-why-model.qmd to html, docx and revealjs succeeds with no warnings, and there are no unresolved ?@ refs. PDF could not be rendered locally because TeX is not installed. No div title contains math.
• The gha check-new-line-breaks passes on the added lines.
• Two rounds of adversarial review by a separate Claude (sonnet) reviewer. All findings were addressed except page ranges in the existing ## headings, which are left so the anchors stay stable.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Gh7L9vJhwrpvpBhzYMdjPK

---

Generated by Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Claude finished review — View run

---

Review: PR #126 — Box ch. 11 content into numbered divs and callouts

Scope: Restructures chapters/11-why-model.qmd to turn most prose/bullets/speaker-notes into 52 numbered, cross-referenceable Quarto divs (definitions, examples, remarks, 2 propositions with proofs, 1 algorithm, 1 crossref table), plus one inst/WORDLIST addition (invertible).

Verification performed

• Fenced-div balance: 70 opening ::: {...} / 70 closing ::: — balanced.
• Cross-reference integrity: every @exm-*, @def-*, @rem-*, @prp-*, @alg-*, @tbl-*, @sec-* reference in the file resolves to a div ID defined in the same file; no duplicate IDs; no dangling refs. Cross-chapter links (10-random-variability.qmd#def-super-population, #def-estimand-estimator, #def-consistent-estimator-sample-size; 02-randomized-experiments.qmd#def-exchangeability; 03-observational-studies.qmd#def-positivity, #def-consistency) all point to anchors that exist in those files.
• inst/WORDLIST: invertible is inserted in the correct case-insensitive sorted position; full-file sort check passes with zero out-of-order entries (per the lab-manual/repo convention).
• Math/statistics checked for correctness:
  • CI widths in the new "Price of Flexibility" remark (108.7 for the 3-parameter model, 89.5 for the 2-parameter model) are arithmetically correct from the existing (142.8, 251.5) and (172.1, 261.6) intervals.
  • "Plugging in the rounded ones gives $24.55 + 90 \times 2.14 = 217.15$" is correct, and resolves a real inconsistency in the old text (which displayed 24.55 + 90 × 2.14 = 216.9, which is wrong — $217.15 \ne 216.9$). The new version marks the headline numbers ≈ 216.9 / ≈ 197.1 as coming from unrounded estimates and moves the rounded-arithmetic discrepancy into an explanatory note — a genuine correctness fix.
  • prp-saturated-ols-sample-means and its proof (splitting the least-squares sum by group, each a convex quadratic in its own mean) is a correct, standard derivation, correctly conditioned on "each treatment level occurs at least once."
  • prp-nested-models (nested-model correctness propagates upward) is logically sound and correctly applied in exm-linear-vs-quadratic-bias.
  • Canonical-link claims (identity↔normal, log↔Poisson, logit↔Bernoulli) and the kernel-regression/GAM/semiparametric definitions are all standard and accurate.
• Quarto conventions: box-heading style (## as the first line inside each fenced div), .proof, .callout-warning/.callout-important/.callout-tip/.callout-note, the {#tbl-...} table+caption pattern, and [text](chapter.qmd#anchor) cross-chapter links all match patterns used identically elsewhere in the book (checked against chapters 02, 03, 04, 06, 07, 08, 10, 12, 13, 15–20, 22, 23). No raw HTML introduced in the .qmd.
• Macro check: the latex-macros/macros.qmd submodule is present and was read. No added/changed math expression duplicates an existing macro's expansion. The only expression that recurs 3+ times in the diff, \mathcal{M}_1 / \mathcal{M}_2, is too simple (not ~5+ constituent parts) to justify a new macro.
• Hallucination check: all citations (@hernan2020causal, p. 155/156/157/159/161) match page numbers already used pre-PR or follow the same chapter's established pagination; no fabricated function/package/API references apply here (prose-only diff).
• Could not run quarto render locally (quarto binary not present in this environment), but the structural checks above (balanced divs, resolved refs, matching conventions) cover the most likely render-breaking failure modes.

Findings

None. This is a careful, well-scoped restructuring that preserves all existing IDs/headings (confirmed sec-bias-variance and other pre-existing anchors are untouched), fixes a real latent arithmetic inconsistency in the displayed equation, and follows the lab manual's Quarto cross-reference conventions throughout.

Verdict

Ready for merge

Structured Review Data (JSON)

{
  "schema_version": "1.1",
  "reviewer": "claude",
  "commit_sha": "f3af2340c8b7d755cbd170f9d70ebaac468bc6ec",
  "verdict": "CLEAN",
  "findings": [],
  "detailed_assessment": "Checked chapters/11-why-model.qmd for balanced fenced divs, resolvable cross-references, and correct arithmetic in the CI-width and predicted-value calculations; found no broken refs, no unbalanced divs, and the rounding-discrepancy fix in exm-linear-model is mathematically sound.",
  "holistic_assessment": "Verified the new div/callout/proof conventions, tbl-two-models caption pattern, and cross-chapter link style all match existing usage across chapters 02-23, and inst/WORDLIST remains case-insensitively sorted after the invertible addition, so integration and repo conventions are satisfied with no regression risk."
}

Reviewed commit: 8e40f0b

[github-actions]

💰 Cost: $0.9407 (review) — run

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://Morrison-Lab.github.io/win/pr-preview/pr-126/
Built to branch gh-pages at 2026-10-09 13:29 UTC. Preview will be ready when the GitHub Pages deployment is complete.