Add Proposition 5 detection for unidentified long-run horizons

Distinguish Prop 5 horizons (treated obs exist, counterfactual unidentified)
from zero-observation horizons. Prop 5 horizons get n_obs > 0 with NaN
inference and a warning, matching ImputationDiD behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: igerber

diff_diff/two_stage.py

@@ -1206,8 +1206,39 @@ def _stage2_event_study(
         else:
             balance_mask = np.ones(n, dtype=bool)
 
-        # Remove reference period from estimation horizons
-        est_horizons = [h for h in all_horizons if h != ref_period]
+        # Check Proposition 5: no never-treated units
+        has_never_treated = df["_never_treated"].any()
+        h_bar = np.inf
+        if not has_never_treated and len(treatment_groups) > 1:
+            h_bar = max(treatment_groups) - min(treatment_groups)
+
+        # Identify Prop 5 horizons and compute their actual treated obs counts.
+        # Treated obs have NaN y_tilde at these horizons (counterfactual
+        # unidentified), but actual_n counts them to distinguish from truly
+        # empty horizons. rel_times is NaN for untreated/never-treated obs
+        # (line ~653), so (rel_times == h) is False for them.
+        prop5_horizons = []
+        prop5_effects: Dict[int, Dict[str, Any]] = {}
+        if h_bar < np.inf:
+            for h in all_horizons:
+                if h == ref_period:
+                    continue
+                if h >= h_bar:
+                    actual_n = int(np.sum((rel_times == h) & omega_1_mask.values & balance_mask))
+                    if actual_n > 0:
+                        prop5_horizons.append(h)
+                        prop5_effects[h] = {
+                            "effect": np.nan,
+                            "se": np.nan,
+                            "t_stat": np.nan,
+                            "p_value": np.nan,
+                            "conf_int": (np.nan, np.nan),
+                            "n_obs": actual_n,
+                        }
+
+        # Remove reference period AND Prop 5 horizons from estimation
+        prop5_set = set(prop5_horizons)
+        est_horizons = [h for h in all_horizons if h != ref_period and h not in prop5_set]
 
         if len(est_horizons) == 0:
             # No horizons to estimate — return just reference period
@@ -1308,6 +1339,17 @@ def _stage2_event_study(
                 "n_obs": n_obs,
             }
 
+        # Add Proposition 5 entries (unidentified horizons with n_obs > 0)
+        event_study_effects.update(prop5_effects)
+
+        if prop5_horizons:
+            warnings.warn(
+                f"Horizons {prop5_horizons} are not identified without "
+                f"never-treated units (Proposition 5). Set to NaN.",
+                UserWarning,
+                stacklevel=2,
+            )
+
         return event_study_effects
 
     def _stage2_group(
@@ -1869,6 +1911,15 @@ def _run_bootstrap(
                 balance_mask = np.ones(n, dtype=bool)
 
             est_horizons = [h for h in all_horizons if h != ref_period]
+
+            # Filter out Prop 5 horizons (same logic as _stage2_event_study)
+            has_never_treated = df["_never_treated"].any()
+            h_bar_boot = np.inf
+            if not has_never_treated and len(treatment_groups) > 1:
+                h_bar_boot = max(treatment_groups) - min(treatment_groups)
+            if h_bar_boot < np.inf:
+                est_horizons = [h for h in est_horizons if h < h_bar_boot]
+
             if est_horizons:
                 horizon_to_col = {h: j for j, h in enumerate(est_horizons)}
                 k_es = len(est_horizons)
@@ -1911,6 +1962,8 @@ def _run_bootstrap(
                 for h in original_event_study:
                     if original_event_study[h].get("n_obs", 0) == 0:
                         continue
+                    if np.isnan(original_event_study[h]["effect"]):
+                        continue  # Skip Prop 5 and other NaN-effect horizons
                     if h not in horizon_to_col:
                         continue
                     j = horizon_to_col[h]

docs/methodology/REGISTRY.md

@@ -619,8 +619,8 @@ Our implementation uses multiplier bootstrap on the GMM influence function: clus
 - **NaN inference for undefined statistics:** t_stat uses NaN when SE is non-finite or zero; p_value and CI also NaN. Matches CallawaySantAnna/ImputationDiD NaN convention.
 - **Event study aggregation:** Horizon-specific effects use the same two-stage procedure with horizon indicator dummies in Stage 2. Unidentified horizons (e.g., long-run effects without never-treated units, per Proposition 5 of Borusyak et al. 2024) produce NaN.
 - **balance_e with no qualifying cohorts:** If no cohorts have sufficient pre/post coverage for the requested `balance_e`, a warning is emitted and event study results contain only the reference period.
-- **No never-treated units:** Long-run effects may be unidentified (same limitation as ImputationDiD). Warning emitted for affected horizons.
-- **Zero-observation horizons after filtering:** When `balance_e` or NaN `y_tilde` filtering results in zero observations for some event study horizons, those horizons produce NaN for all inference fields (effect, SE, t-stat, p-value, CI) with n_obs=0. This differs from the Proposition 5 case (unidentified long-run effects) which has observations but unidentified counterfactual.
+- **No never-treated units (Proposition 5):** When there are no never-treated units and multiple treatment cohorts, horizons h >= h_bar (where h_bar = max(groups) - min(groups)) are unidentified per Proposition 5 of Borusyak et al. (2024). These produce NaN inference with n_obs > 0 (treated observations exist but counterfactual is unidentified) and a warning listing affected horizons. Matches ImputationDiD behavior. Proposition 5 applies to event study horizons only, not cohort aggregation — a cohort whose treated obs all fall at Prop 5 horizons naturally gets n_obs=0 in group effects because all its y_tilde values are NaN.
+- **Zero-observation horizons after filtering:** When `balance_e` or NaN `y_tilde` filtering results in zero observations for some non-Prop-5 event study horizons, those horizons produce NaN for all inference fields (effect, SE, t-stat, p-value, CI) with n_obs=0.
 - **Zero-observation cohorts in group effects:** If all treated observations for a cohort have NaN `y_tilde` (excluded from estimation), that cohort's group effect is NaN with n_obs=0.
 
 **Reference implementation(s):**

tests/test_two_stage.py

@@ -794,35 +794,42 @@ def test_balance_e_empty_cohorts_warns(self):
         ref_key = list(results.event_study_effects.keys())[0]
         assert results.event_study_effects[ref_key]["n_obs"] == 0
 
-    def test_event_study_nan_for_zero_obs_horizons(self):
-        """Zero-observation horizons from NaN y_tilde produce NaN inference."""
+    def test_proposition_5_nan_for_long_run_horizons(self):
+        """Prop 5 horizons have n_obs > 0 but NaN inference (unidentified)."""
         # No never-treated: cohorts 3, 5, 7; periods 0-9.
-        # Periods 7-9 have zero untreated obs → NaN y_tilde.
-        # Horizon 4 = cohort 3 at period 7 (NaN) + cohort 5 at period 9 (NaN) → 0 obs.
-        # Horizons 5, 6 = cohort 3 at periods 8, 9 (NaN) → 0 obs.
-        # Horizons 0-3 have valid observations from multiple cohorts.
+        # h_bar = max(groups) - min(groups) = 7 - 3 = 4.
+        # Horizons 0-3: identified, valid effects.
+        # Horizons 4, 5, 6: Prop 5 unidentified — treated obs exist but
+        # counterfactual is unidentified without never-treated units.
         data = generate_test_data(never_treated_frac=0.0)
-        results = TwoStageDiD().fit(
-            data,
-            outcome="outcome",
-            unit="unit",
-            time="time",
-            first_treat="first_treat",
-            aggregate="event_study",
-        )
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            results = TwoStageDiD().fit(
+                data,
+                outcome="outcome",
+                unit="unit",
+                time="time",
+                first_treat="first_treat",
+                aggregate="event_study",
+            )
 
         assert results.event_study_effects is not None
 
+        # Check Prop 5 warning was emitted
+        prop5_warnings = [x for x in w if "not identified without never-treated" in str(x.message)]
+        assert len(prop5_warnings) > 0, "Proposition 5 warning should be emitted"
+
         # Horizons 0-3 should have observations and finite effects
         for h in range(0, 4):
             eff = results.event_study_effects[h]
             assert eff["n_obs"] > 0, f"Horizon {h} should have observations"
             assert np.isfinite(eff["effect"]), f"Horizon {h} effect should be finite"
 
-        # Horizons 4, 5, 6 should have zero obs and NaN inference
+        # Horizons 4, 5, 6: Prop 5 — n_obs > 0 but NaN inference
         for h in [4, 5, 6]:
             eff = results.event_study_effects[h]
-            assert eff["n_obs"] == 0, f"Horizon {h} should have 0 observations"
+            assert eff["n_obs"] > 0, f"Horizon {h} should have n_obs > 0 (Prop 5)"
             assert np.isnan(eff["effect"]), f"Horizon {h} effect should be NaN"
             assert np.isnan(eff["se"]), f"Horizon {h} SE should be NaN"
             assert np.isnan(eff["t_stat"]), f"Horizon {h} t_stat should be NaN"