add content covering the Cook's distance diagnostic plot

[github-actions]

Draft PR opened by @claude to address #857.

Triggered by workflow run.

Addresses #857.

[claude]

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

---

Code Review: PR #858 — Cook's Distance Diagnostic Plot

• Gather context and read changed files
• Review new Cook's distance section
• Review changes to existing files
• Review bibliography entry
• Summarize findings

---

Summary

The PR adds a new _sec_linreg_diag_cooks_distance.qmd subfile (116 lines), wires it into _sec_linreg_diagnostics.qmd, adds a brief cross-reference in the conditional-residuals section, and adds the Cook (1977) BibTeX entry. The mathematical content is correct and well-structured, but there are several issues to address before merging.

---

Issues

1. Slide breaks use --- instead of {{< slidebreak >}} (CLAUDE.md violation)

_sec_linreg_diag_cooks_distance.qmd uses --- for all 8 slide breaks. CLAUDE.md states:

Use {{< slidebreak >}} instead of --- for slide breaks

Every --- in the new file (lines 9, 27, 40, 51, 69, 83, 91, 99) should be replaced with {{< slidebreak >}}.

Fix this →

---

2. Forward reference to @def-cooks-distance (CLAUDE.md violation)

_sec_linreg_diag_conditional_resid.qmd, line 95 (new text):

(see @def-cooks-distance )

#def-cooks-distance is defined in _sec_linreg_diag_cooks_distance.qmd, which is included after the conditional-residuals section in _sec_linreg_diagnostics.qmd (lines 33 vs. 35–37). CLAUDE.md:

Introduce concepts before using them — no forward references.

Fix: Remove the see @def-cooks-distance cross-reference from the residuals-vs-leverage notes, or rephrase it to refer forward explicitly (e.g., "see the Cook's distance section below"). Alternatively, add a brief parenthetical definition inline.

Fix this →

---

3. Extra space before ) in the same line

Same line in _sec_linreg_diag_conditional_resid.qmd:

(see @def-cooks-distance )
                          ^

There is a spurious space before the closing parenthesis.

---

4. Rule-of-thumb thresholds stated without citation (CLAUDE.md violation)

_sec_linreg_diag_cooks_distance.qmd, lines 73–77 (inside ::: notes):

A commonly cited rule of thumb flags observation $i$ as influential if
$$D_i > 1$$
A more conservative threshold is $D_i > 4/n$.

These are factual claims. CLAUDE.md:

Factual claims must have a specific citation.

Fix: Add a citation such as [@cook1977detection] or a textbook reference that states these specific thresholds.

Fix this →

---

5. Figure #fig-bw-cooks-distance not cross-referenced in text

The Cook's distance plot figure is defined at line 59:

:::{#fig-bw-cooks-distance}

But the ::: notes block immediately before it (lines 55–57) only describes what autoplot does — it never links to the figure via @fig-bw-cooks-distance. Other diagnostic figures in the adjacent section (e.g. @fig-bw_lm2-resid-vs-fitted) are always cited by label in their surrounding prose. Add @fig-bw-cooks-distance to the notes narrative.

---

Correct / Good

• Mathematical content: Both the definitional formula (@eq-cooks-distance-def) and the closed-form shortcut (@eq-cooks-distance-formula) are correct.
• Exercise solution: Uses rstandard() (internally standardized residuals) — the right function for the shortcut formula. The manual computation (r_prime^2 / p) * (h / (1 - h)) is mathematically correct.
• Subfile does not start with a heading: The file opens with a callout tip div — CLAUDE.md compliant.
• Back-reference in Cook's distance section: @fig-bw_lm2_resid-vs-leverage (line 87) refers back to the preceding conditional-residuals section — correct direction.
• Bibliography entry (cook1977detection): Title, author, journal, volume, pages, year, DOI all look correct for the Cook (1977) Technometrics paper.
• _sec_linreg_diagnostics.qmd wiring: The new section include and its {#sec-cooks-distance} anchor are correctly placed.
• Macros used: \hvb, \tp{}, \mX, \hs^2, \stdresid_i are all defined in latex-macros/macros.qmd.

---

[claude]

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

---

Code Review: PR #858 — Cook's Distance Diagnostic Plot

• Read changed files
• Review new Cook's distance section
• Review changes to existing files
• Review bibliography entry
• Summarize findings

---

Summary

The PR adds _sec_linreg_diag_cooks_distance.qmd (116 lines), wires it into _sec_linreg_diagnostics.qmd, adds a cross-reference in the conditional-residuals section, and adds the Cook (1977) BibTeX entry. The mathematical content is correct and well-structured, but there are six issues to address before merging.

---

Issues

1. All 8 slide breaks use --- instead of {{< slidebreak >}} (CLAUDE.md violation)

_sec_linreg_diag_cooks_distance.qmd at lines 9, 27, 40, 51, 69, 83, 91, and 99 all use bare --- for slide breaks. CLAUDE.md states:

Use {{< slidebreak >}} instead of --- for slide breaks

All 8 occurrences must be replaced with {{< slidebreak >}}.

Fix this →

---

2. Forward reference to @def-cooks-distance (CLAUDE.md violation)

_sec_linreg_diag_conditional_resid.qmd, line 95:

(see @def-cooks-distance ).

#def-cooks-distance is defined in _sec_linreg_diag_cooks_distance.qmd, which is included after _sec_linreg_diag_conditional_resid.qmd in _sec_linreg_diagnostics.qmd (line 33 vs. lines 35–37). CLAUDE.md:

Introduce concepts before using them — no forward references.

Fix: Remove the cross-reference, or replace it with a plain-prose forward-reference note like (see the Cook's distance section below).

Fix this →

---

3. Spurious space before ) on the same line

Same line 95 of _sec_linreg_diag_conditional_resid.qmd:

(see @def-cooks-distance ).
                          ^ space before )

Should be (see @def-cooks-distance). with no space before the closing parenthesis.

---

4. Rule-of-thumb thresholds stated without citation (CLAUDE.md violation)

_sec_linreg_diag_cooks_distance.qmd, lines 72–76:

A commonly cited rule of thumb flags observation $i$ as influential if
$$D_i > 1$$
A more conservative threshold is $D_i > 4/n$.

CLAUDE.md:

Factual claims must have a specific citation.

Fix: Add a specific citation after the threshold statements, such as [@cook1977detection] (if Cook (1977) states them) or a textbook reference like [@dobson4e] that documents these thresholds.

Fix this →

---

5. Figure #fig-bw-cooks-distance not cross-referenced in surrounding prose

The notes block immediately before the figure (lines 55–57) reads:

::: notes
We can visualize Cook's distances for all observations using `autoplot` with `which = 4`.
:::

But it never cites @fig-bw-cooks-distance. The established pattern in adjacent sections is to cite the figure label inside the notes block — for example, _sec_linreg_diag_conditional_resid.qmd lines 25–26:

we can plot the residuals $\resid_i$ against the fitted values $\hat y_i$ (@fig-bw_lm2-resid-vs-fitted).

Fix: Change the notes to end with a reference to @fig-bw-cooks-distance, e.g.:

We can visualize Cook's distances for all observations using `autoplot` with `which = 4` (@fig-bw-cooks-distance).

---

6. Inconsistent transpose notation within a single formula

_sec_linreg_diag_cooks_distance.qmd, lines 19–20:

(\hvb_{(-i)} - \hvb)^{\prime}
\tp{\mX}\mX

^{\prime} (the prime symbol $'$) and \tp{} (which expands to ^{\top}, the $\top$ symbol) are two different notations for transpose used in the same formula. The rest of the codebase consistently uses \tp{} — e.g., _sec_linreg_diag_residuals.qmd line 118: \mX(\tp{\mX}\mX)^{-1}\tp{\mX}.

Fix: Replace (\hvb_{(-i)} - \hvb)^{\prime} with \tp{(\hvb_{(-i)} - \hvb)} to use consistent \tp{} notation.

Fix this →

---

Correct / Good

• Mathematical content: Both the definitional formula (@eq-cooks-distance-def) and the closed-form shortcut (@eq-cooks-distance-formula) are mathematically correct.
• R code: rstandard() for internally standardized residuals and hatvalues() for leverage are the right functions; the manual computation (r_prime^2 / p) * (h / (1 - h)) matches the formula exactly.
• Subfile structure: File does not begin with a section heading (opens with a callout tip div) — CLAUDE.md compliant.
• Back-references only: @def-stred and @def-hat-matrix both resolve to _sec_linreg_diag_residuals.qmd, which is included before Cook's distance in _sec_linreg_diagnostics.qmd — correct direction. Similarly, @fig-bw_lm2_resid-vs-leverage (line 86) is a backward reference.
• BibTeX entry (cook1977detection): Author, title, journal, volume 19, number 1, pages 15–18, year 1977, DOI all look correct for the Cook (1977) Technometrics paper.
• Wiring in _sec_linreg_diagnostics.qmd: The {{< include >}} directive and {#sec-cooks-distance} anchor are correctly placed after the conditional-residuals section.
• Macros: \hvb, \tp{}, \mX, \hs^2, \stdresid_i are all defined in latex-macros/macros.qmd.

[d-morrison]

@claude address review comments and update branch from main

[github-actions]

👀 Picked up by workflow run #27028683136. 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 #27031654573. R/Quarto/renv setup runs first (~3-5 min); Claude itself responds after that.

[d-morrison]

Claude Code CLI (local session) is working on this — paws off until I'm done. Fixing the :;: div-fence corruption and the open review findings.

[claude]

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

---

Code Review: PR #858 — Cook's Distance Diagnostic Plot

• Read changed files
• Review new Cook's distance section
• Review changes to existing files
• Review bibliography entry
• Summarize findings

---

Summary

All six issues flagged in the previous two reviews have been fixed. The PR is nearly ready to merge — one substantive citation concern and one minor structural note remain.

---

Fixes Confirmed

#	Issue	Status
1	Slide breaks --- → {{< slidebreak >}}	✅ Fixed (all 8 occurrences)
2	Forward @def-cooks-distance cross-reference	✅ Fixed — replaced with plain prose "see the Cook's distance section below"
3	Spurious space before ) on the same line	✅ Fixed
4	Rule-of-thumb thresholds lacked citations	✅ Fixed — [@dobson4e, §6.3] and [@cook1977detection] added
5	Figure #fig-bw-cooks-distance not cited in notes	✅ Fixed — notes now end with (@fig-bw-cooks-distance)
6	Inconsistent transpose: ^{\prime} vs \tp{}	✅ Fixed — now uses \tp{(\hvb_{(-i)} - \hvb)} throughout

---

Remaining Issues

1. Citation accuracy: Di > 4/n threshold likely misattributed

_sec_linreg_diag_cooks_distance.qmd, line 77:

A more conservative threshold is $D_i > 4/n$ [@cook1977detection].

Cook's original 1977 paper is only 4 pages (pp. 15–18) and introduces the distance measure itself — it does not state the 4/n rule of thumb. That threshold is commonly attributed to later literature (e.g., Cook & Weisberg (1982) Residuals and Influence in Regression, or Bollen & Jackman (1990)). Per CLAUDE.md:

Factual claims must have a specific citation. Only cite a page number after verifying it directly from the source.

Fix: Verify whether Cook (1977) actually states Di > 4/n. If not, replace with a source that does — or remove the citation until one is verified.

Fix this →

---

2. (Minor) No {#exm-...} div example follows #def-cooks-distance

CLAUDE.md says:

After every definition or concept, include a concrete example — preferably numerical — to illustrate the abstract idea; use a {#exm-...} div

#def-cooks-distance (lines 11–25) has no formal {#exm-...} example immediately after it. Numerical illustration of Cook's distance values is present later in the section (via the R code block cooks.distance(bw_lm2) and the exercise solution), but it is not packaged in an {#exm-...} div. This is minor since the numerical content exists — but adding a brief {#exm-...} with a small worked example (or pointing to the R output as an example) would satisfy the CLAUDE.md convention.

---

Correct / Good

• Mathematical content: Both the definitional formula (@eq-cooks-distance-def) and the closed-form shortcut (@eq-cooks-distance-formula) are correct.
• R code: rstandard() (internally standardized residuals) and hatvalues() are the right functions; (r_prime^2 / p) * (h / (1 - h)) matches the formula.
• Di > 1 citation: [@dobson4e, §6.3] is a plausible location for this threshold.
• Back-references only: @def-stred, @def-hat-matrix, and @fig-bw_lm2_resid-vs-leverage all refer to sections/figures defined/included before the Cook's distance section — correct direction.
• Wiring: _sec_linreg_diagnostics.qmd correctly inserts the new section between "Conditional distributions of residuals" and "Diagnostics constructed by hand".
• BibTeX entry (cook1977detection): Author, title, journal (Technometrics), volume 19, number 1, pages 15–18, year 1977, DOI all correct.
• Macros: \hvb (line 99), \mX (line 340), \hs (line 106), \stdresid (line 157/530), \tp (line 367) are all defined in latex-macros/macros.qmd.

[d-morrison]

@claude address review comments

[github-actions]

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

[claude]

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

---

Code Review: PR #858 — Cook's Distance Diagnostic Plot

• Read changed files
• Review new Cook's distance section
• Review changes to existing files
• Review bibliography entry
• Summarize findings

---

Summary

All six issues from prior reviews are confirmed fixed. Two issues remain open from the most recent review: one citation accuracy concern and one structural convention from CLAUDE.md.

---

Confirmed Fixed

#	Issue	Status
1	Slide breaks --- → {{< slidebreak >}}	✅ Fixed (all 8 occurrences)
2	Forward @def-cooks-distance cross-reference	✅ Fixed — plain prose "see the Cook's distance section below"
3	Spurious space before )	✅ Fixed
4	Rule-of-thumb thresholds lacked citations	✅ [@dobson4e, §6.3] and [@cook1977detection] added
5	#fig-bw-cooks-distance not cited in notes	✅ Notes end with (@fig-bw-cooks-distance)
6	Inconsistent transpose ^{\prime} vs \tp{}	✅ Now uses \tp{(\hvb_{(-i)} - \hvb)}

---

Remaining Issues

1. Citation accuracy: Di > 4/n threshold likely misattributed to Cook (1977)

_sec_linreg_diag_cooks_distance.qmd, line 77:

A more conservative threshold is $D_i > 4/n$ [@cook1977detection].

Cook's original 1977 paper (Technometrics vol. 19, pp. 15–18) is a 4-page note that introduces the distance measure itself — it does not state the 4/n rule of thumb. That threshold is commonly attributed to later literature, such as Cook & Weisberg (1982) Residuals and Influence in Regression or Bollen & Jackman (1985). Per CLAUDE.md: "Factual claims must have a specific citation. Only cite a page number after verifying it directly from the source."

Fix: Verify whether Cook (1977) explicitly states Di > 4/n. If it does not, either replace [@cook1977detection] with a source that does state it, or remove the citation until one is verified.

Fix this →

---

2. No {#exm-...} div after #def-cooks-distance (CLAUDE.md convention)

#def-cooks-distance is at lines 11–25. CLAUDE.md states:

After every definition or concept, include a concrete example — preferably numerical — to illustrate the abstract idea; use a {#exm-...} div.

The numerical content exists later in the section (the cooks.distance(bw_lm2) output and the exercise solution), but none of it is wrapped in a {#exm-...} div immediately following the definition. The closed-form expression and its interpretation at lines 29–49 come first, then the R output at line 97.

Fix: Add a brief {#exm-...} div after #def-cooks-distance (e.g., after line 25) that gives a small numerical illustration — even just two or three $D_i$ values with their interpretation — or promote the existing cooks.distance(bw_lm2) output block into an {#exm-...} div.

Fix this →

---

Correct / Good

• Mathematical content: @eq-cooks-distance-def and @eq-cooks-distance-formula are both correct. The R code (rstandard(), hatvalues(), (r_prime^2 / p) * (h / (1 - h))) matches the formula exactly.
• Wiring: _sec_linreg_diagnostics.qmd inserts Cook's distance between "Conditional distributions of residuals" and "Diagnostics constructed by hand" with correct {#sec-cooks-distance} anchor.
• Back-references only: @def-stred, @def-hat-matrix, @fig-bw_lm2_resid-vs-leverage all resolve backward — correct.
• Conditional-residuals cross-reference: Plain-prose "see the Cook's distance section below" at line 95 of _sec_linreg_diag_conditional_resid.qmd correctly avoids a Quarto cross-reference link.
• BibTeX entry (cook1977detection): Author, title, journal, volume 19, number 1, pages 15–18, year 1977, DOI all correct.
• Macros: \hvb, \tp{}, \mX, \hs^2, \stdresid_i are all defined in latex-macros/macros.qmd.
• Di > 1 citation: [@dobson4e, §6.3] is a plausible location for this threshold.

[claude]

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

---

Code Review: PR #858 — Cook's Distance Diagnostic Plot

• Gather context and read changed files
• Review _sec_linreg_diag_cooks_distance.qmd (new file)
• Review _sec_linreg_diag_conditional_resid.qmd (modified)
• Review _sec_linreg_diagnostics.qmd (modified)
• Review references.bib (modified)
• Summarize findings

---

Summary

All six issues from prior reviews are confirmed fixed, including the citation-accuracy problem for Di > 4/n (now correctly citing [@bollen1990regression] — Bollen & Jackman 1990 — instead of Cook 1977) and the missing {#exm-...} div. One new structural issue was found in the added example.

---

Confirmed Fixed

#	Issue	Status
1	Slide breaks --- → {{< slidebreak >}}	✅ All 8 replaced
2	Forward @def-cooks-distance cross-reference	✅ Plain prose "see the Cook's distance section below"
3	Spurious space before )	✅ Fixed
4	Rule-of-thumb thresholds lacked citations	✅ [@dobson4e, §6.3] and [@bollen1990regression] added
5	#fig-bw-cooks-distance not cited in notes	✅ (@fig-bw-cooks-distance) added
6	Transpose ^{\prime} vs \tp{} inconsistency	✅ Now uses \tp{(\hvb_{(-i)} - \hvb)}
7	Di > 4/n misattributed to Cook (1977)	✅ Changed to [@bollen1990regression]
8	Missing {#exm-...} div after definition	✅ {#exm-cooks-distance} added

---

Issue

{#exm-cooks-distance} uses the shortcut formula before it is introduced (CLAUDE.md violation)

_sec_linreg_diag_cooks_distance.qmd, lines 26–34:

:::{#exm-cooks-distance}
Consider a regression with $p = 2$ parameters.
Suppose observation $i$ has standardized residual $\stdresid_i = 2$ and leverage $h_{ii} = 0.3$.
Then

$$
D_i = \frac{(2)^2}{2} \cdot \frac{0.3}{1 - 0.3} = 2 \cdot 0.43 \approx 0.86.
$$
:::

The computation $D_i = \stdresid_i^2/p \cdot h_{ii}/(1-h_{ii})$ follows the shortcut formula @eq-cooks-distance-formula, which is not introduced until lines 38–48 (the next slide). At lines 26–34 the reader has only seen @eq-cooks-distance-def, which uses the leave-one-out vector $\hvb_{(-i)}$ — a quantity that does not appear in the example. A reader seeing the example before @eq-cooks-distance-formula is introduced will not know where the computation comes from.

CLAUDE.md: "Introduce concepts before using them — no forward references."

Fix options (pick one):

1. Move {#exm-cooks-distance} to immediately after @eq-cooks-distance-formula is introduced (after line 48). The CLAUDE.md requirement "example after every definition" is satisfied by any example in the section; it does not have to follow the definition block directly if the prerequisite formula isn't in scope yet.

2. Keep the example in place but add a forward-reference note inside the div, e.g.:
   "Using the shortcut formula introduced below (@eq-cooks-distance-formula):"
   (Quarto renders forward cross-references to equations as clickable links, so this is less problematic than a forward reference to a definition or section.)

Fix this →

---

Good

• Math correctness: @eq-cooks-distance-def and @eq-cooks-distance-formula are both correct. The example arithmetic $\frac{(2)^2}{2} \cdot \frac{0.3}{0.7} \approx 0.86$ is correct.
• R code: rstandard(), hatvalues(), and (r_prime^2 / p) * (h / (1 - h)) exactly match @eq-cooks-distance-formula.
• bollen1990regression BibTeX entry: @incollection{bollen1990regression} — Bollen & Jackman (1990) ch. in Modern Methods of Data Analysis, Sage. This is the standard attribution for the 4/n threshold. Entry looks correct.
• Back-references: @def-stred, @def-hat-matrix, and @fig-bw_lm2_resid-vs-leverage all resolve backward — correct direction.
• Wiring: _sec_linreg_diagnostics.qmd correctly inserts Cook's distance between "Conditional distributions of residuals" and "Diagnostics constructed by hand" with {#sec-cooks-distance} anchor.
• Conditional-residuals change: Three added lines (plain prose "see the Cook's distance section below") are correctly scoped to the notes block with no forward Quarto cross-reference.

[claude]

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

---

Code Review: PR #858 — Cook's Distance Diagnostic Plot

• Gather context and read changed files
• Review _sec_linreg_diag_cooks_distance.qmd (new file)
• Review _sec_linreg_diag_conditional_resid.qmd (modified)
• Review _sec_linreg_diagnostics.qmd (modified)
• Review references.bib (modified)
• Summarize findings

---

Summary

All issues from previous review rounds have been resolved. The PR is ready to merge.

---

Confirmed Fixed

#	Issue	Status
1	Slide breaks --- → {{< slidebreak >}}	✅ All 9 occurrences use {{< slidebreak >}}
2	Forward @def-cooks-distance cross-reference	✅ Plain prose "see the Cook's distance section below"
3	Spurious space before )	✅ Fixed
4	Rule-of-thumb thresholds lacked citations	✅ [@dobson4e, §6.3] and [@bollen1990regression] added
5	#fig-bw-cooks-distance not cited in notes	✅ (@fig-bw-cooks-distance) added
6	Inconsistent transpose ^{\prime} vs \tp{}	✅ Now uses \tp{(\hvb_{(-i)} - \hvb)}
7	Di > 4/n misattributed to Cook (1977)	✅ Changed to [@bollen1990regression]
8	Missing {#exm-cooks-distance} div	✅ Added after @eq-cooks-distance-formula is introduced, with explicit Applying @eq-cooks-distance-formula,

---

Good

• Mathematical content: @eq-cooks-distance-def (leave-one-out) and @eq-cooks-distance-formula (shortcut) are both correct. Example arithmetic $\frac{4}{2} \cdot \frac{0.3}{0.7} \approx 0.86$ is correct.
• Example placement: {#exm-cooks-distance} (lines 41–49) correctly appears after @eq-cooks-distance-formula (lines 32–34) and explicitly references it — no forward reference violation.
• R code: rstandard(), hatvalues(), (r_prime^2 / p) * (h / (1 - h)) exactly match @eq-cooks-distance-formula.
• Back-references only: @def-stred (line 495 of _sec_linreg_diag_residuals.qmd), @def-hat-matrix (line 111), and @fig-bw_lm2_resid-vs-leverage all resolve to earlier sections — correct direction.
• BibTeX entries: cook1977detection (Technometrics vol. 19, pp. 15–18, 1977) and bollen1990regression (Sage incollection, 1990, pp. 257–291) both look correct.
• Wiring: _sec_linreg_diagnostics.qmd correctly inserts Cook's distance between "Conditional distributions of residuals" and "Diagnostics constructed by hand" with {#sec-cooks-distance} anchor.
• _sec_linreg_diag_conditional_resid.qmd addition: Three lines added inside an existing ::: notes block — no new slide breaks needed and no forward Quarto cross-reference.

[github-actions]

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

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