fix(inference): fail closed to NaN on non-finite degrees of freedom

The CR2/Bell-McCaffrey guard added in the previous commit can surface a
non-finite (NaN) Satterthwaite DOF for a high-leverage / collinear
nuisance coefficient. Two inference paths did not treat that as
undefined:

- `safe_inference()` rejected `df <= 0` but let a NaN `df` through
  (`NaN <= 0` is False), computing a finite t-stat with a NaN p-value /
  CI - an inconsistent, partially-finite inference tuple. It now returns
  all-NaN for any non-finite `df`.
- `MultiPeriodDiD(vcov_type="hc2_bm")` fell back to the shared residual
  `df` for a period effect whose per-coefficient BM DOF was non-finite,
  reporting finite t/p/CI for a coefficient whose DOF was declared
  unreliable. It now passes the BM DOF through unconditionally on the
  hc2_bm path, so a non-finite DOF fails closed via `safe_inference`. The
  post-period-average and SunAbraham contrast paths already route their
  DOF through `safe_inference`, so the central guard covers them too.

Only coefficients whose BM DOF is non-finite are affected; well-
conditioned treatment / event-study / average contrasts are unchanged.

Also rewrites the REGISTRY `DID_M^pl` placebo formula to display the
backward-difference x switch-direction convention (`stable0_avg -
joiner_avg` / `leaver_avg - stable1_avg`) so it matches the code and the
adjacent sign note.

Regression tests: non-finite `df` in `safe_inference`; monkeypatched
NaN BM DOF failing closed on user-facing MPD period and average contrasts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0178r8ZK6VRiXbaBiknrWjQB

Author: igerber

CHANGELOG.md

@@ -40,6 +40,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `survey_design=SurveyDesign(psu=<cluster_col>)`. No behavior change for unclustered fits.
 
 ### Fixed
+- **Non-finite degrees of freedom now fail closed to all-NaN inference.**
+  `safe_inference()` previously rejected `df <= 0` but let a non-finite `df` (NaN) through,
+  producing an inconsistent tuple (finite t-stat, NaN p-value/CI). It now returns all-NaN for
+  any non-finite `df`. `MultiPeriodDiD(vcov_type="hc2_bm")` likewise no longer falls back to
+  the shared residual `df` when a coefficient's Bell-McCaffrey Satterthwaite DOF is non-finite
+  (guard-suppressed) — such a coefficient's inference is now NaN rather than silently computed
+  from a different `df`, preserving the joint-NaN inference contract. Only affects coefficients
+  whose BM DOF was declared unreliable (high-leverage / collinear); well-conditioned
+  treatment / event-study / average contrasts are unchanged.
 - **Unweighted clustered CR2 / Bell-McCaffrey per-coefficient Satterthwaite DOF no
   longer returns non-physical values** for high-leverage FE-dummy / collinear nuisance
   columns. The simple `(tr B)²/tr(B²)` form could produce a garbage DOF there (float64

diff_diff/estimators.py

@@ -2132,11 +2132,16 @@ def _refit_mp_absorb(w_r):
             idx = interaction_indices[period]
             effect = coefficients[idx]
             se = np.sqrt(vcov[idx, idx])
-            # Prefer per-coefficient BM DOF when available (hc2_bm path);
-            # otherwise fall back to the shared analytical df.
-            period_df = df
-            if _bm_dof_per_coef is not None and np.isfinite(_bm_dof_per_coef[idx]):
+            # Use the per-coefficient BM DOF when available (hc2_bm path);
+            # otherwise fall back to the shared analytical df. On the hc2_bm path
+            # the coefficient's OWN Bell-McCaffrey DOF governs its inference: a
+            # non-finite (guard-suppressed, unreliable) BM DOF makes t/p/CI
+            # undefined, so pass it through to `safe_inference` (which returns
+            # all-NaN) rather than silently falling back to the residual df.
+            if _bm_dof_per_coef is not None:
                 period_df = float(_bm_dof_per_coef[idx])
+            else:
+                period_df = df
             t_stat, p_value, conf_int = safe_inference(effect, se, alpha=self.alpha, df=period_df)
 
             period_effects[period] = PeriodEffect(

diff_diff/utils.py

@@ -352,8 +352,13 @@ def safe_inference(effect, se, alpha=0.05, df=None):
     """
     if not (np.isfinite(se) and se > 0):
         return np.nan, np.nan, (np.nan, np.nan)
-    if df is not None and df <= 0:
-        # Undefined degrees of freedom (e.g., rank-deficient replicate design)
+    if df is not None and not (np.isfinite(df) and df > 0):
+        # Undefined degrees of freedom: df <= 0 (e.g., rank-deficient replicate
+        # design) OR non-finite (a guard-suppressed / non-physical Bell-McCaffrey
+        # Satterthwaite DOF, which `_cr2_bm_dof_inner` returns as NaN for
+        # high-leverage nuisance contrasts). All inference fields are NaN so a
+        # coefficient whose DOF was declared unreliable never reports finite
+        # t/p/CI - preserving the joint-NaN inference contract.
         return np.nan, np.nan, (np.nan, np.nan)
     t_stat = effect / se
     p_value = compute_p_value(t_stat, df=df)

docs/methodology/REGISTRY.md

@@ -744,15 +744,17 @@ DID_+ = sum_{t>=2} (N_{1,0,t} / sum_{t} N_{1,0,t}) * DID_{+,t}
 DID_- = sum_{t>=2} (N_{0,1,t} / sum_{t} N_{0,1,t}) * DID_{-,t}
 ```
 
-Single-lag placebo (AER 2020 placebo specification, same section as Theorem 3) — applies the same Theorem 3 logic to `Y_{g,t-1} - Y_{g,t-2}` on cells with 3-period histories:
+Single-lag placebo (AER 2020 placebo specification, same section as Theorem 3) — applies the same Theorem 3 logic to the pre-period first difference on cells with 3-period histories. Writing `d_a(cells) = mean over `cells` of (Y_{g,t-1} - Y_{g,t-2})` for the pre-period forward first difference:
 
 ```
 DID_M^pl = (1/N_S^pl) * sum_{t>=3} (
-              N_{1,0,t} * [(Y_{g,t-1} - Y_{g,t-2})_{joiners} - ...] +
-              N_{0,1,t} * [(Y_{g,t-1} - Y_{g,t-2})_{stable_1} - ...]
+              N_{1,0,t} * [ d_a(stable_0(t)) - d_a(joiners(t)) ]      # joiners side, S=+1
+            + N_{0,1,t} * [ d_a(leavers(t))  - d_a(stable_1(t)) ]     # leavers side, S=-1
           )
 ```
 
+The per-side terms are the code's `placebo_plus_t = stable0_avg - joiner_avg` and `placebo_minus_t = leaver_avg - stable1_avg` — the backward-difference × switch-direction convention of the sign Note below (equivalently, `S_g · (Y_{g,t-2} - Y_{g,t-1})_switcher` minus the same for its stable controls, matching `_compute_multi_horizon_placebos` and R).
+
 **Note (sign convention):** the reported `placebo_effect` uses the **backward-difference × switch-direction** convention of the multi-horizon placebo path (`_compute_multi_horizon_placebos`: `switcher_change - ctrl_avg` with `Y_bwd - Y_ref`, times `S_g = +1` joiners / `-1` leavers) and R `did_multiplegt_dyn`. In the phase-1 (`L_max=None`) code this is `placebo_plus_t = stable0_avg - joiner_avg` (joiners) and `placebo_minus_t = leaver_avg - stable1_avg` (leavers). Prior to this the phase-1 path used the opposite (forward-difference) order, so `placebo_effect` was **sign-flipped vs R** on pure-direction panels (magnitude bit-identical); the multi-horizon path was always correct. Pinned by `tests/test_chaisemartin_dhaultfoeuille_parity.py::TestDCDHDynRParity::test_parity_{joiners,leavers}_only`. On **mixed-direction** panels the placebo magnitude additionally carries the documented period-vs-cohort stable-control-set / equal-cell-weighting deviation (see the `**Note (deviation from R DIDmultiplegtDYN):**` above), so it is not gate-asserted against R there.
 
 *Phase 2: Multi-horizon event study (Equation 3 and 5 of the dynamic companion paper):*

tests/test_estimators_vcov_type.py

@@ -544,6 +544,52 @@ def test_multi_period_cluster_plus_hc2_bm_produces_finite_inference(self):
         assert np.isfinite(post_pe.se)
         assert np.isfinite(post_pe.p_value)
 
+    def test_multi_period_hc2_bm_nonfinite_bm_dof_fails_closed(self, monkeypatch):
+        """A non-finite (guard-suppressed) Bell-McCaffrey DOF must fail closed to
+        NaN inference on user-facing MPD contrasts, not fall back to the shared
+        residual df. The `_cr2_bm_dof_inner` guard can NaN a per-coefficient DOF
+        (high-leverage / collinear column); reporting finite t/p/CI for such a
+        coefficient via the residual df would violate the joint-NaN inference
+        contract. Monkeypatches every BM DOF to NaN and asserts SEs stay finite
+        (vcov is unaffected) while all t/p/CI fields are NaN.
+        """
+        import numpy as np
+
+        import diff_diff.linalg as _linalg
+
+        rng = np.random.default_rng(2)
+        rows = []
+        for i in range(20):
+            treated = int(i >= 10)
+            for t in range(3):
+                y = rng.normal(0.0, 1.0) + 0.5 * treated * (t >= 1)
+                rows.append({"unit": i, "time": t, "treated": treated, "y": y})
+        data = pd.DataFrame(rows)
+
+        _orig = _linalg._compute_cr2_bm_vcov_and_dof
+
+        def _nan_dof(*args, **kwargs):
+            vcov, dof = _orig(*args, **kwargs)
+            return vcov, np.full(np.asarray(dof).shape, np.nan)
+
+        # MPD's hc2_bm+cluster path imports this from linalg inside fit(), so the
+        # local import binds to the patched attribute at call time.
+        monkeypatch.setattr(_linalg, "_compute_cr2_bm_vcov_and_dof", _nan_dof)
+
+        res = MultiPeriodDiD(vcov_type="hc2_bm", cluster="unit").fit(
+            data, outcome="y", treatment="treated", time="time"
+        )
+        for p, pe in res.period_effects.items():
+            assert np.isfinite(pe.se), f"period {p}: SE should remain finite"
+            assert np.isnan(pe.t_stat), f"period {p}: t_stat should be NaN"
+            assert np.isnan(pe.p_value), f"period {p}: p_value should be NaN"
+            assert np.isnan(pe.conf_int[0]) and np.isnan(pe.conf_int[1])
+        # The post-period-average contrast fails closed too.
+        assert np.isfinite(res.avg_se), "avg SE should remain finite"
+        assert np.isnan(res.avg_t_stat)
+        assert np.isnan(res.avg_p_value)
+        assert np.isnan(res.avg_conf_int[0]) and np.isnan(res.avg_conf_int[1])
+
     def test_multi_period_cluster_hc2_bm_avg_att_uses_clubsandwich_dof(self):
         """MPD(cluster=..., hc2_bm) `avg_att` inference uses the new
         cluster-aware contrast Satterthwaite DOF, not the shared n-k fallback.

tests/test_utils.py

@@ -586,6 +586,21 @@ def test_neg_inf_se_returns_all_nan(self):
         assert np.isnan(ci_lower)
         assert np.isnan(ci_upper)
 
+    def test_nonfinite_df_returns_all_nan(self):
+        """Non-finite df (NaN/inf) produces all-NaN inference even with a valid SE.
+
+        A guard-suppressed / non-physical Bell-McCaffrey Satterthwaite DOF is
+        surfaced as NaN by `_cr2_bm_dof_inner`; a coefficient whose DOF was
+        declared unreliable must not report finite (or partially-finite) t/p/CI.
+        `df <= 0` is already rejected; this covers the non-finite case where
+        `df <= 0` is False for NaN.
+        """
+        for bad_df in (np.nan, np.inf, -np.inf):
+            t_stat, p_value, (ci_lower, ci_upper) = safe_inference(5.0, 2.0, df=bad_df)
+            assert np.isnan(t_stat), f"df={bad_df}: t_stat should be NaN"
+            assert np.isnan(p_value), f"df={bad_df}: p_value should be NaN"
+            assert np.isnan(ci_lower) and np.isnan(ci_upper), f"df={bad_df}: CI should be NaN"
+
     def test_valid_se_normal_distribution(self):
         """Test valid SE with normal distribution (df=None)."""
         effect = 5.0