Concept map: dependency diagram + descendants table for all definitions and results (#872)

.claude/commands/new-chapter.md

@@ -14,9 +14,12 @@ First, parse `$ARGUMENTS`: the first whitespace-delimited token is the **slug**
 Steps:
 
 1. Create `chapters/<slug>.qmd` with YAML frontmatter holding just `title:` (set to the title). Do NOT set `date:` — the book sets `date: last-modified` globally, and a per-page `date:` would override it. Do NOT add a top-level `#` heading in the body — Quarto renders the frontmatter `title:` as the page heading.
-2. Register the chapter in the `book.chapters:` list in `_quarto-book.yml` at a logical position (read the file first). If it belongs to an existing `part:`, nest it under that part.
+2. Register the chapter in the `book.chapters:` list in `_quarto-book.yml` at a logical position (read the file first). If it belongs to an existing `part:`, nest it under that part. **Also** add an entry to the appropriate navbar dropdown (`Chapters` or `Appendices`) in `_quarto-website.yml`, and ensure the file is in the `render:` list. The navbar is NOT auto-generated from `_quarto-book.yml` -- manual addition is required.
 3. If the chapter is long, you may split content into includes under `chapters/_subfiles/<slug>/`. Subfiles must NOT start with a heading and must NOT contain a references section.
 4. Confirm it renders: `quarto render chapters/<slug>.qmd --to html`.
+5. If the chapter contains `def`/`thm`/`lem`/`cor`/`prp` callout divs,
+   re-run `Rscript data-raw/callout-graph.R` to refresh
+   `inst/extdata/callout-graph.rds` and keep the concept map current.
 
 Style rules (see `.github/instructions/`):
 

_quarto-book.yml

@@ -57,6 +57,7 @@ book:
     - chapters/CONTRIBUTING.qmd
     - chapters/exam-formula-sheet.qmd
     - chapters/practice-exam-mle-linreg.qmd
+    - chapters/concept-map.qmd
   back-to-top-navigation: true
   page-navigation: true
 

_quarto-website.yml

@@ -36,6 +36,7 @@ project:
     - chapters/CONTRIBUTING.qmd
     - chapters/exam-formula-sheet.qmd
     - chapters/package-versions.qmd
+    - chapters/concept-map.qmd
 
 website:
   title: "Regression Models for Epidemiology"
@@ -125,6 +126,8 @@ website:
             href: chapters/exam-formula-sheet.qmd
           - text: "Package Versions"
             href: chapters/package-versions.qmd
+          - text: "Concept Map"
+            href: chapters/concept-map.qmd
 
 bibliography: references.bib
 

chapters/concept-map.qmd

@@ -0,0 +1,187 @@
+---
+title: "Concept Map: Definitions and Results"
+---
+
+{{< include shared-config.qmd >}}
+
+This appendix shows how the definitions and results
+(`def`, `thm`, `lem`, `cor`, `prp` callouts)
+in the notes depend on one another.
+
+We say result $B$ is a **descendant** of result $A$
+if $A$ is referenced inside the statement or proof of $B$
+(directly, or transitively through a chain of intermediate results).
+The more descendants a result has,
+the more of the rest of the notes rests on it ---
+so descendant count is a rough measure of how foundational a result is.
+
+The dependency graph is built by `data-raw/callout-graph.R`,
+which scans the source `.qmd` files and saves the result to
+`inst/extdata/callout-graph.rds`.
+This appendix reads that saved file rather than re-scanning the notes on
+every render, so **re-run that script whenever divs are added, removed, or
+re-titled** to refresh the diagram and table below.
+
+```{r}
+#| label: load-concept-graph
+#| code-fold: true
+#| message: false
+#| warning: false
+
+library(igraph)
+library(ggraph)
+library(ggrepel)
+
+cg <- readRDS(here::here("inst/extdata/callout-graph.rds"))
+
+type_levels <- c("def", "thm", "lem", "cor", "prp")
+type_labels <- c(
+  def = "Definition", thm = "Theorem", lem = "Lemma",
+  cor = "Corollary", prp = "Proposition"
+)
+type_palette <- c(
+  def = "#1b9e77", thm = "#d95f02", lem = "#7570b3",
+  cor = "#e7298a", prp = "#66a61e"
+)
+```
+
+There are `r nrow(cg$nodes)` labeled definitions and results in the notes,
+connected by `r nrow(cg$edges)` direct dependency links.
+
+## Dependency diagram
+
+::: {.content-visible unless-format="pdf"}
+::: {.content-visible unless-format="docx"}
+
+@fig-concept-map shows the results that participate in at least one
+dependency link, laid out so that connected results sit near each other.
+Color encodes the type of result.
+Results with no detected dependency links are omitted from the diagram.
+Node labels are larger for results with more total descendants,
+so the most foundational results are visually prominent.
+Zoom in with Ctrl+scroll (or pinch on mobile) to read individual labels.
+Lines from labels to dots indicate where ggrepel moved a label to avoid overlap.
+
+:::{#fig-concept-map}
+
+```{r}
+#| label: concept-map-ggraph
+#| code-fold: true
+#| message: false
+#| warning: false
+#| fig-width: 50
+#| fig-height: 50
+#| out-width: "100%"
+#| fig-format: "svg"
+
+connected <- cg$nodes$id[cg$nodes$id %in% c(cg$edges$from, cg$edges$to)]
+core <- graph_from_data_frame(
+  cg$edges,
+  vertices = cg$nodes[cg$nodes$id %in% connected, ],
+  directed = TRUE
+)
+V(core)$type <- factor(V(core)$type, levels = type_levels)
+
+set.seed(204)
+# Fruchterman-Reingold applies repulsion between all node pairs (not just
+# connected ones), spreading nodes more evenly across the canvas. Normalise
+# axes afterwards to fill the full canvas and eliminate edge whitespace.
+layout <- create_layout(core, layout = "fr", niter = 2000)
+norm_axis <- function(x) {
+  r <- diff(range(x))
+  if (r == 0) return(x)
+  (x - min(x)) / r * 2 - 1
+}
+layout$x <- norm_axis(layout$x)
+layout$y <- norm_axis(layout$y)
+
+ggraph(layout) +
+  geom_edge_link(
+    arrow = arrow(length = unit(1.8, "mm"), type = "closed"),
+    end_cap = circle(2, "mm"),
+    edge_alpha = 0.25, edge_width = 0.3
+  ) +
+  geom_node_point(color = "grey60", size = 0.8, alpha = 0.7) +
+  geom_label_repel(
+    data = as.data.frame(layout),
+    aes(x = x, y = y, label = title, fill = type, size = n_desc),
+    inherit.aes = FALSE,
+    color = "white",
+    fontface = "bold",
+    max.overlaps = Inf,
+    force = 3,
+    force_pull = 0.5,
+    box.padding = unit(0.25, "lines"),
+    label.padding = unit(0.1, "lines"),
+    label.r = unit(0.05, "lines"),
+    label.size = 0.1,
+    alpha = 0.88,
+    segment.color = "grey60",
+    segment.alpha = 0.6,
+    segment.size = 0.3,
+    min.segment.length = 0,
+    seed = 204
+  ) +
+  scale_fill_manual(
+    values = type_palette, labels = type_labels, name = "Type", drop = FALSE
+  ) +
+  scale_size_continuous(range = c(8.0, 16.0), guide = "none") +
+  theme_void() +
+  theme(legend.position = "bottom")
+```
+
+Dependency structure of the definitions and results in the notes.
+An arrow points from a result to each result that uses it.
+Color indicates result type (see legend).
+Label font size is proportional to the number of total descendants.
+
+:::
+
+:::
+:::
+
+::: {.content-visible when-format="pdf"}
+
+The dependency diagram is only available in the
+[HTML version of the notes](https://d-morrison.github.io/rme/chapters/concept-map.html).
+
+:::
+
+::: {.content-visible when-format="docx"}
+
+The dependency diagram is only available in the
+[HTML version of the notes](https://d-morrison.github.io/rme/chapters/concept-map.html).
+
+:::
+
+## Descendants of each result {#sec-descendants-table}
+
+@tbl-descendants lists every result that has at least one descendant,
+sorted by the number of total descendants (direct or transitive).
+
+::: {#tbl-descendants}
+
+```{r}
+#| label: descendants-table-build
+#| code-fold: true
+#| message: false
+#| warning: false
+
+ranked <- cg$nodes[cg$nodes$n_desc >= 1, ]
+ranked <- ranked[order(-ranked$n_desc, ranked$id), ]
+
+descendant_table <- data.frame(
+  Result               = ranked$title,
+  Type                 = type_labels[ranked$type],
+  `Direct descendants`  = ranked$n_direct,
+  `Total descendants`   = ranked$n_desc,
+  check.names = FALSE, row.names = NULL, stringsAsFactors = FALSE
+)
+
+knitr::kable(descendant_table, format = "pipe", align = "llrr")
+```
+
+All results with at least one descendant,
+sorted by number of total descendants (most-foundational first).
+
+:::