Address R16 polish (2 P3-informational, 2 no-action) on PreTrendsPower

igerber · claude · igerber · commit a6f11d8c7974 · 2026-05-17T07:43:13.000-04:00
R16 verdict was ✅ Looks good (6th overall ✅), with all findings classified
P3-informational. Two of the four findings ("None in this PR" / "TODO rows
are correct") required no action; addressing the two with concrete polish
suggestions.

- P3 helper docstring: `compute_pretrends_power` and `compute_mdv` both
  accept `violation_type` but don't accept `violation_weights`, so
  `violation_type="custom"` is unusable from either helper today. Added
  an explicit Note in the `violation_type` docstring entry of both
  convenience functions pointing users to instantiate `PreTrendsPower`
  directly for custom weights, and cross-referencing the TODO row that
  tracks the helper-extension follow-up.
- P3 METHODOLOGY_REVIEW.md "four power calculations" target: now reads
  "at a pinned revision" with cross-reference to the TODO row that
  tracks the R-package revision pin. Until that lands, the R-package
  surface claims in the paper review remain provisional.

Pyright diagnostics in pretrends.py (matplotlib import, numpy/list type
conflicts, ndarray-to-tuple coercion) are pre-existing in code I did not
touch; my edits are docstring-only.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/METHODOLOGY_REVIEW.md b/METHODOLOGY_REVIEW.md
@@ -1057,7 +1057,7 @@ and covariate-adjusted specifications.)
 
 **Outstanding for promotion:**
 - Dedicated `tests/test_methodology_pretrends.py` with paper-equation-numbered Verified Components walk-through
-- R parity fixture against the `pretrends` R package (the four power calculations: linear, constant, last-period, custom). Note that `compute_pretrends_power` does not accept `violation_weights` today, so `"custom"` parity has to run through `PreTrendsPower(..., violation_weights=...)` directly until the helper is extended (TODO.md tracks the helper-extension follow-up); helper-only parity is limited to `linear` / `constant` / `last_period`.
+- R parity fixture against the `pretrends` R package at a **pinned revision** (TODO.md tracks the revision-pin follow-up; until that lands, the R-package surface claims in `docs/methodology/papers/roth-2022-review.md` are provisional). Covers the four power calculations: linear, constant, last-period, custom. Note that `compute_pretrends_power` does not accept `violation_weights` today, so `"custom"` parity has to run through `PreTrendsPower(..., violation_weights=...)` directly until the helper is extended (TODO.md tracks the helper-extension follow-up); helper-only parity is limited to `linear` / `constant` / `last_period`.
 - Verify the REGISTRY Implementation Checklist (all four items currently unchecked)
 
 ---
diff --git a/diff_diff/pretrends.py b/diff_diff/pretrends.py
@@ -1067,7 +1067,12 @@ def compute_pretrends_power(
     target_power : float, default=0.80
         Target power for MDV calculation.
     violation_type : str, default='linear'
-        Type of violation pattern.
+        Type of violation pattern. Note: this convenience helper does NOT
+        accept ``violation_weights``, so ``violation_type='custom'`` is
+        unusable from the helper (only ``linear`` / ``constant`` /
+        ``last_period`` are supported here). For custom weights, instantiate
+        ``PreTrendsPower(..., violation_weights=...)`` directly. Tracked in
+        TODO.md as a planned helper extension.
     pre_periods : list of int, optional
         Explicit list of pre-treatment periods. If None, attempts to infer
         from results. Use when you've estimated all periods as post_periods.
@@ -1114,7 +1119,12 @@ def compute_mdv(
     target_power : float, default=0.80
         Target power for MDV calculation.
     violation_type : str, default='linear'
-        Type of violation pattern.
+        Type of violation pattern. Note: this convenience helper does NOT
+        accept ``violation_weights``, so ``violation_type='custom'`` is
+        unusable from the helper (only ``linear`` / ``constant`` /
+        ``last_period`` are supported here). For custom weights, instantiate
+        ``PreTrendsPower(..., violation_weights=...)`` directly. Tracked in
+        TODO.md as a planned helper extension.
     pre_periods : list of int, optional
         Explicit list of pre-treatment periods. If None, attempts to infer
         from results. Use when you've estimated all periods as post_periods.
