igerber
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 1 deletion b/‎CHANGELOG.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎benchmarks/R/generate_dcdh_dynr_test_values.R‎
Lines changed: 19 additions & 10 deletions b/‎benchmarks/R/generate_dcdh_dynr_test_values.R‎
Lines changed: 19 additions & 10 deletions
diff --git a/‎diff_diff/chaisemartin_dhaultfoeuille.py‎
Lines changed: 48 additions & 3 deletions b/‎diff_diff/chaisemartin_dhaultfoeuille.py‎
Lines changed: 48 additions & 3 deletions
@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- **`ChaisemartinDHaultfoeuille.by_path` + `controls`** (DID^X residualization) — the per-baseline OLS residualization (Web Appendix Section 1.2) is now compatible with `by_path=k`. The residualization runs once on the first-differenced outcome BEFORE path enumeration, so all four downstream surfaces (analytical per-path SE, bootstrap SE, per-path placebos, per-path joint sup-t bands) consume the residualized `Y_mat` automatically (Frisch-Waugh-Lovell). Per-period effects remain unadjusted, consistent with the existing `controls` + per-period DID contract (per-period DID does not support residualization). Failed-stratum baselines (rank-deficient X) zero out `N_mat` for affected groups, which the path enumeration treats as ineligible per its existing convention. **Inherits the cross-path cohort-sharing SE deviation from R** documented for `path_effects` — bootstrap SE, placebo SE, and sup-t crit are Monte Carlo / joint-distribution analogs of the same residualized analytical IF and carry the same deviation. R-parity confirmed against `did_multiplegt_dyn(..., by_path=3, controls="X1")` via the new `multi_path_reversible_by_path_controls` golden-value scenario (per-path point estimates exact match — measured rtol ~1e-11 across all path × horizon cells; per-path SE within ~6.5% of R, well inside the Phase 2 multi-horizon envelope). Gate at `chaisemartin_dhaultfoeuille.py:988-992` removed; `by_path` docstring updated to add the new compatibility paragraph and remove `controls` from the incompatible list. R-parity test at `tests/test_chaisemartin_dhaultfoeuille_parity.py::TestDCDHDynRParityByPathControls`; cross-surface inheritance regression-tested at `tests/test_chaisemartin_dhaultfoeuille.py::TestByPathControls` (analytical + bootstrap + placebo + sup-t + `to_dataframe(level="by_path")` cband columns). See `docs/methodology/REGISTRY.md` §ChaisemartinDHaultfoeuille `Note (Phase 3 by_path ...)` → "Per-path covariate residualization (DID^X)" for the full contract.
+- **`ChaisemartinDHaultfoeuille.by_path` + `controls`** (DID^X residualization) — the per-baseline OLS residualization (Web Appendix Section 1.2) is now compatible with `by_path=k`. The residualization runs once on the first-differenced outcome BEFORE path enumeration, so all four downstream surfaces (analytical per-path SE, bootstrap SE, per-path placebos, per-path joint sup-t bands) consume the residualized `Y_mat` automatically (Frisch-Waugh-Lovell). Per-period effects remain unadjusted, consistent with the existing `controls` + per-period DID contract (per-period DID does not support residualization). Failed-stratum baselines (rank-deficient X) zero out `N_mat` for affected groups, which the path enumeration treats as ineligible per its existing convention. **Deviation from R on multi-baseline switcher panels (point estimates):** R `did_multiplegt_dyn(..., by_path, controls)` re-runs the per-baseline OLS residualization on each path's restricted subsample (path's switchers + same-baseline not-yet-treated controls), so its residualization coefficients vary per path when switchers have different baseline values. Our global-residualization architecture coincides with R on single-baseline switcher panels (every switcher shares the same `D_{g,1}`) — per-path point estimates match R exactly there. On multi-baseline panels, point estimates can diverge; the estimator emits a `UserWarning` at fit-time when this configuration is detected so practitioners do not silently consume estimates that disagree with R. **SE inherits the cross-path cohort-sharing SE deviation from R** documented for `path_effects` — bootstrap SE, placebo SE, and sup-t crit are Monte Carlo / joint-distribution analogs of the same residualized analytical IF and carry the same deviation. R-parity confirmed against `did_multiplegt_dyn(..., by_path=3, controls="X1")` via the new `multi_path_reversible_by_path_controls` single-baseline golden-value scenario (per-path point estimates exact match — measured rtol ~1e-11 across all path × horizon cells; per-path SE within ~6.5% of R, well inside the Phase 2 multi-horizon envelope). Gate at `chaisemartin_dhaultfoeuille.py:988-992` removed; `by_path` docstring updated to add the new compatibility paragraph (with the multi-baseline caveat) and remove `controls` from the incompatible list. R-parity test at `tests/test_chaisemartin_dhaultfoeuille_parity.py::TestDCDHDynRParityByPathControls`; cross-surface inheritance + multi-baseline `UserWarning` regression-tested at `tests/test_chaisemartin_dhaultfoeuille.py::TestByPathControls` (analytical + bootstrap + placebo + sup-t + `to_dataframe(level="by_path")` cband columns + multi-baseline warning). See `docs/methodology/REGISTRY.md` §ChaisemartinDHaultfoeuille `Note (Phase 3 by_path ...)` → "Per-path covariate residualization (DID^X)" for the full contract.
 - **HAD linearity-family pretests under survey (Phase 4.5 C).** `stute_test`, `yatchew_hr_test`, `stute_joint_pretest`, `joint_pretrends_test`, `joint_homogeneity_test`, and `did_had_pretest_workflow` now accept `weights=` / `survey=` keyword-only kwargs. Stute family uses **PSU-level Mammen multiplier bootstrap** via `bootstrap_utils.generate_survey_multiplier_weights_batch` (the same kernel as PR #363's HAD event-study sup-t bootstrap): each replicate draws an `(n_bootstrap, n_psu)` Mammen multiplier matrix, broadcast to per-obs perturbation `eta_obs[g] = eta_psu[psu(g)]`, weighted OLS refit, weighted CvM via new `_cvm_statistic_weighted` helper. Joint Stute SHARES the multiplier matrix across horizons within each replicate, preserving both the vector-valued empirical-process unit-level dependence AND PSU clustering. Yatchew uses **closed-form weighted OLS + pweight-sandwich variance components** (no bootstrap): `sigma2_lin = sum(w·eps²)/sum(w)`, `sigma2_diff = sum(w_avg·diff²)/(2·sum(w))` with arithmetic-mean pair weights `w_avg_g = (w_g+w_{g-1})/2`, `sigma4_W = sum(w_avg·prod)/sum(w_avg)`, `T_hr = sqrt(sum(w))·(sigma2_lin-sigma2_diff)/sigma2_W`. All three Yatchew components reduce bit-exactly to the unweighted formulas at `w=ones(G)` (locked at `atol=1e-14` by direct helper test). The pweight `weights=` shortcut routes through a synthetic trivial `ResolvedSurveyDesign` (new `survey._make_trivial_resolved` helper) so the same kernel handles both entry paths. `did_had_pretest_workflow(..., survey=, weights=)` removes the Phase 4.5 C0 `NotImplementedError`, dispatches to the survey-aware sub-tests, **skips the QUG step with `UserWarning`** (per C0 deferral), sets `qug=None` on the report, and appends a `"linearity-conditional verdict; QUG-under-survey deferred per Phase 4.5 C0"` suffix to the verdict. `HADPretestReport.qug` retyped from `QUGTestResults` to `Optional[QUGTestResults]`; `summary()` / `to_dict()` / `to_dataframe()` updated to None-tolerant rendering. Replicate-weight survey designs (BRR/Fay/JK1/JKn/SDR) raise `NotImplementedError` at every entry point (defense in depth, reciprocal-guard discipline) — parallel follow-up after this PR. **Stratified designs (`SurveyDesign(strata=...)`) also raise `NotImplementedError` on the Stute family** — the within-stratum demean + `sqrt(n_h/(n_h-1))` correction that the HAD sup-t bootstrap applies to match the Binder-TSL stratified target has not been derived for the Stute CvM functional, so applying raw multipliers from `generate_survey_multiplier_weights_batch` directly to residual perturbations would leave the bootstrap p-value silently miscalibrated. Phase 4.5 C narrows survey support to **pweight-only**, **PSU-only** (`SurveyDesign(weights=, psu=)`), and **FPC-only** (`SurveyDesign(weights=, fpc=)`) designs; stratified is a follow-up after the matching Stute-CvM stratified-correction derivation lands. Strictly positive weights required on Yatchew (the adjacent-difference variance is undefined under contiguous-zero blocks). Per-row `weights=` / `survey=col` aggregated to per-unit via existing HAD helpers `_aggregate_unit_weights` / `_aggregate_unit_resolved_survey` (constant-within-unit invariant enforced). Unweighted code paths preserved bit-exactly. Patch-level addition (additive on stable surfaces). See `docs/methodology/REGISTRY.md` § "QUG Null Test" — Note (Phase 4.5 C) for the full methodology.
 - **`ChaisemartinDHaultfoeuille.by_path` + `n_bootstrap > 0` joint sup-t bands** — per-path joint sup-t simultaneous confidence intervals across horizons `1..L_max` within each path. A single shared `(n_bootstrap, n_eligible)` multiplier weight matrix (using the estimator's configured `bootstrap_weights` — Rademacher / Mammen / Webb) is drawn per path and broadcast across all horizons of that path, producing correlated bootstrap distributions across horizons. The path-specific critical value `c_p = quantile(max_l |t_l|, 1 - α)` is used to construct symmetric joint bands `effect_l ± c_p · se_l` per horizon. Surfaced on `results.path_sup_t_bands` (dict keyed by path tuple, each entry with `crit_value / alpha / n_bootstrap / method / n_valid_horizons`); as `cband_conf_int` per horizon entry on `path_effects[path]["horizons"][l]`; and as `cband_lower` / `cband_upper` columns on `results.to_dataframe(level="by_path")` (mirrors the OVERALL `level="event_study"` schema; positive-horizon rows of banded paths get populated values, placebo / unbanded / empty-window rows get NaN). Gates: a path needs `>= 2` valid horizons (finite bootstrap SE > 0) AND a strict majority (more than 50%) of finite sup-t draws to receive a band. Empty-state contract: `path_sup_t_bands is None` when not requested; `{}` when requested but no path passes both gates. **Methodology asymmetry vs OVERALL `event_study_sup_t_bands`:** the per-path sup-t draws a fresh shared weight matrix per path AFTER the per-path SE bootstrap block has already populated `results.path_ses` via independent per-(path, horizon) draws — asymptotically equivalent to OVERALL's self-consistent reuse but NOT bit-identical. Documented intentional choice to preserve RNG-state isolation for existing per-path SE seed-reproducibility tests. Inherits the cross-path cohort-sharing SE deviation from R documented for `path_effects`. **Deviation from R:** `did_multiplegt_dyn` does not provide joint / sup-t bands at any surface — this is a Python-only methodology extension consistent with the existing OVERALL sup-t bands (also Python-only). Bands cover joint inference WITHIN a single path across horizons; they do NOT provide simultaneous coverage across paths. Pre-audit fix bundled: stale "Phase 2 placeholder" docstring on the existing `sup_t_bands` field updated to the actual contract description. Tests at `tests/test_chaisemartin_dhaultfoeuille.py::TestByPathSupTBands` (`@pytest.mark.slow`). See `docs/methodology/REGISTRY.md` §ChaisemartinDHaultfoeuille `Note (Phase 3 by_path per-path joint sup-t bands)` for the full contract.
 - **`ChaisemartinDHaultfoeuille.by_path` + `placebo=True`** — per-path backward-horizon placebos `DID^{pl}_{path, l}` for `l = 1..L_max`. The same per-path SE convention used for the event-study (joiners/leavers IF precedent: switcher-side contributions zeroed for non-path groups; cohort structure and control pool unchanged; plug-in SE with path-specific divisor `N^{pl}_{l, path}`) is applied to backward horizons via the new `switcher_subset_mask` parameter on `_compute_per_group_if_placebo_horizon`. Surfaced on `results.path_placebo_event_study[path][-l]` (negative-int inner keys mirroring `placebo_event_study`); `summary()` renders the rows alongside per-path event-study horizons; `to_dataframe(level="by_path")` emits negative-horizon rows alongside the existing positive-horizon rows. **Bootstrap** (when `n_bootstrap > 0`) propagates per-`(path, lag)` percentile CI / p-value through the same `_bootstrap_one_target` dispatch as the per-path event-study, with the canonical NaN-on-invalid contract enforced on the new surface (PR #364 library-wide invariant). **SE inherits the cross-path cohort-sharing deviation from R** documented for `path_effects` (full-panel cohort-centered plug-in vs R's per-path re-run): tracks R within tolerance on single-path-cohort panels, diverges materially on cohort-mixed panels — the bootstrap SE is a Monte Carlo analog of the analytical SE and inherits the same deviation. R-parity confirmed at `tests/test_chaisemartin_dhaultfoeuille_parity.py::TestDCDHDynRParityByPathPlacebo` on the new `multi_path_reversible_by_path_placebo` scenario (point estimates exact match; SE within Phase-2 envelope rtol ≤ 5%); positive analytical + bootstrap invariants at `tests/test_chaisemartin_dhaultfoeuille.py::TestByPathPlacebo` (and the gated `::TestBootstrap` subclass). See `docs/methodology/REGISTRY.md` §ChaisemartinDHaultfoeuille `Note (Phase 3 by_path ...)` → "Per-path placebos" for the full contract.
 
@@ -703,16 +703,25 @@ scenarios$multi_path_reversible_by_path_placebo <- list(
 # Wave 3 #5: by_path + DID^X residualization). Same deterministic DGP
 # and n_periods=10 as scenarios 14/15, with a confounding covariate X1
 # added via the same `add_covariate` helper used by scenario 10's
-# `joiners_only_controls`. Per-baseline OLS residualization runs once
-# globally before path enumeration on both Python and R sides
-# (verified against `chaisemartinPackages/did_multiplegt_dyn` source —
-# `did_multiplegt_by_path` calls `did_multiplegt_main()` once with the
-# global controls residualization, then disaggregates per-path through
-# aggregation). Per-path event-study point estimates and switcher
-# counts must match R exactly; per-path SE within the documented Phase
-# 2 envelope and inherits the cross-path cohort-sharing deviation from
-# R documented for `path_effects`. Single covariate keeps the scenario
-# tight; multi-covariate is exercised via internal regression tests.
+# `joiners_only_controls`. **R re-runs `did_multiplegt_main()` per path**
+# with a path-restricted subsample (path's switchers + same-baseline
+# not-yet-treated controls), so its per-baseline OLS residualization
+# coefficients can vary per path (verified against
+# `chaisemartinPackages/did_multiplegt_dyn` source —
+# `R/R/did_multiplegt_dyn.R` lines 393-411 dispatch the per-path loop;
+# `did_multiplegt_by_path` is a path-classifier preprocessor only).
+# Python residualizes once on the full panel before path enumeration,
+# then disaggregates per path. **The two strategies coincide on
+# single-baseline switcher panels** (every switcher shares D_{g,1}=0)
+# because R's per-path control pool then equals the global control pool
+# — `multi_path_reversible` is built precisely for this property, so
+# per-path event-study point estimates and switcher counts must match R
+# exactly. Per-path SE inherits the documented cross-path cohort-sharing
+# deviation from R for `path_effects`. On multi-baseline switcher panels
+# the residualization coefficients can diverge per path between Python
+# and R; the production fit emits a `UserWarning` in that configuration.
+# Single covariate keeps the scenario tight; multi-covariate is
+# exercised via internal regression tests.
 cat("  Scenario 16: multi_path_reversible_by_path_controls\n")
 d16 <- gen_reversible(n_groups = N_GOLDEN, n_periods = 10,
                       pattern = "multi_path_reversible", seed = 116,
 
@@ -419,9 +419,21 @@ class ChaisemartinDHaultfoeuille(ChaisemartinDHaultfoeuilleBootstrapMixin):
         bootstrap SE, per-path placebos, and per-path sup-t bands all
         consume the residualized ``Y_mat`` automatically (Frisch-
         Waugh-Lovell). Per-period effects remain unadjusted, consistent
-        with the existing ``controls`` + per-period DID contract. The
-        cross-path cohort-sharing SE deviation from R documented for
-        ``path_effects`` is inherited unchanged.
+        with the existing ``controls`` + per-period DID contract.
+
+        **Deviation from R on multi-baseline switcher panels:** R
+        ``did_multiplegt_dyn(..., by_path, controls)`` re-runs the
+        per-baseline residualization on each path's restricted
+        subsample (path's switchers + same-baseline not-yet-treated
+        controls), so its residualization coefficients vary per path
+        when switchers have different baseline values. Our global-
+        residualization architecture coincides with R on single-
+        baseline panels (every switcher shares the same ``D_{g,1}``)
+        and per-path point estimates match exactly. On multi-baseline
+        panels, point estimates can diverge — a ``UserWarning`` is
+        emitted at fit-time when this configuration is detected.
+        SE inherits the cross-path cohort-sharing deviation from R
+        documented for ``path_effects``.
 
         Compatible with ``n_bootstrap > 0`` -- the top-k paths are
         enumerated once on the observed data (paths held fixed across
@@ -1478,6 +1490,39 @@ def fit(
             )
             _switch_metadata_computed = True
 
+            # by_path + controls multi-baseline deviation from R: R re-runs
+            # the per-baseline OLS residualization on each path's restricted
+            # subsample (path's switchers + same-baseline not-yet-treated
+            # controls), so its residualization coefficients can differ per
+            # path. We residualize once on the full panel before path
+            # enumeration. On single-baseline switcher panels (every
+            # switcher has the same D_{g,1}) the two strategies coincide
+            # and per-path point estimates match R exactly. On multi-
+            # baseline switcher panels they can diverge — warn the user
+            # explicitly so they don't silently consume estimates that
+            # disagree with R. SE inheritance (cross-path cohort-sharing)
+            # is documented separately in REGISTRY.md.
+            if self.by_path is not None:
+                _switcher_mask = first_switch_idx_arr >= 0
+                if _switcher_mask.any():
+                    _switcher_baselines = baselines[_switcher_mask]
+                    if np.unique(_switcher_baselines).size > 1:
+                        warnings.warn(
+                            "by_path + controls: switcher baselines D_{g,1} "
+                            "take multiple values in this panel. Python "
+                            "residualizes once on the full panel before path "
+                            "enumeration; R `did_multiplegt_dyn(..., by_path, "
+                            "controls)` re-runs residualization per path on "
+                            "the path-restricted subsample, so per-path point "
+                            "estimates can diverge between Python and R on "
+                            "this panel. See `docs/methodology/REGISTRY.md` "
+                            "(`Note (Phase 3 by_path ...)` -> Per-path "
+                            "covariate residualization) for the full "
+                            "deviation contract.",
+                            UserWarning,
+                            stacklevel=2,
+                        )
+
             Y_mat_residualized, covariate_diagnostics, _failed_baselines = (
                 _compute_covariate_residualization(
                     Y_mat=Y_mat,