From 298f1f2449567a2c80b02f6b1e44284697b6bda6 Mon Sep 17 00:00:00 2001
From: Ethan Buckley <ethanbuckley@users.noreply.github.com>
Date: Mon, 27 Jul 2026 10:07:29 +0100
Subject: [PATCH] docs(level-factors): name the SP/RW adjusters as
 baseline-predictor associations (#389 finding 5)

In the factor families the speech-accuracy (deapp_c) and phonological-memory (erbto)
adjusters are read at the child's baseline (t1) value so the randomised contrast is
not conditioned on a treatment-affected descendant (#247 timing). Their coefficients
are therefore baseline-predictor associations, not contemporaneous per-wave factors
-- a distinction the level report did not state.

Add a term-gated note to the shared _results_factors.qmd (rendered by the gain and
level families) that names these adjusters as baseline predictors wherever they
appear in the factor summary, and stays silent for models without them. Correct for
both families (both baseline-time SP/RW per #247); no other report changes.

Addresses #389 finding 5.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/models/_partials/_results_factors.qmd | 30 ++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/models/_partials/_results_factors.qmd b/docs/models/_partials/_results_factors.qmd
index 9ef1d68b..6c14d733 100644
--- a/docs/models/_partials/_results_factors.qmd
+++ b/docs/models/_partials/_results_factors.qmd
@@ -221,6 +221,36 @@ if factor_summary is not None and "role" in factor_summary.columns:
         print("\n:::")
 ```
 
+```{python}
+# | echo: false
+# | output: asis
+# SP / RW baseline-timing note (#389 finding 5). Speech accuracy (deapp_c) and
+# phonological memory (erbto) are read at the child's BASELINE (t1) value so the
+# randomised contrast is not conditioned on a treatment-affected descendant (#247
+# timing); their coefficients are therefore baseline-predictor associations, not
+# contemporaneous per-wave factors. Term-gated, so it prints only where such an
+# adjuster is actually in the summary (and stays silent for models without one).
+if factor_summary is not None and "term" in factor_summary.columns:
+    _terms = set(factor_summary["term"].astype(str))
+    _baseline_adj = {
+        "gamma_deapp_c": "speech accuracy",
+        "gamma_erbto": "phonological memory (nonword repetition)",
+    }
+    _present = [lbl for t, lbl in _baseline_adj.items() if t in _terms]
+    if _present:
+        _names = " and ".join(_present)
+        _plural = len(_present) > 1
+        print(
+            f"\n_Timing of the {_names} adjuster{'s' if _plural else ''}:_ read at "
+            f"the child's **baseline (t1)** value — so the randomised contrast is not "
+            f"conditioned on a treatment-affected descendant of the intervention "
+            f"(#247 timing) — {'these are' if _plural else 'so this is'} a "
+            f"**baseline-predictor association** applied across all of a child's "
+            f"observations, **not** a contemporaneous per-wave factor. Hearing, being "
+            f"exogenous, is read contemporaneously instead."
+        )
+```
+
 ```{python}
 # | echo: false
 # | output: asis