Codex re-review: time-label normalization + Conley summary label

P1 (Methodology): `_compute_conley_vcov` previously used raw `time` values
in `abs(t_i - t_j)`, which meant `conley_lag_cutoff` semantics depended on
label encoding rather than panel-period order. On non-dense encodings
(YYYYMM like 202012/202101, datetime64, or binary `post`-style 0/1 panels)
the raw difference does not equal the count of panel periods, so valid
serial pairs could be silently dropped or misweighted.

The fix normalizes `time` to dense panel-period codes `0..T-1` via
`np.unique(return_inverse=True)` before the lag computation, so
`conley_lag_cutoff` always counts panel periods regardless of how `time`
is encoded (int year, YYYYMM, datetime64, pd.Period, strings). The
spatial within-period loop also uses the same dense codes for consistency.
On dense integer labels (the parity-test convention) this is a no-op and
R conleyreg parity holds at 1e-14; on non-dense encodings diff-diff is
the more robust default vs R's literal label-difference convention.

P3 (Maintainability): `_format_vcov_label` in results.py gains a "conley"
branch and surfaces "Conley spatial HAC (1999)" in DiD/MPD/TWFE result
summaries (was previously omitting the label because Conley used to be
unreachable on the panel surface).

Doc surfaces:
- REGISTRY § ConleySpatialHAC: new "Note (deviation from R conleyreg
  literal: time-label normalization)" documenting the dense-code
  convention and the R-divergence on non-dense encodings.
- llms-full.txt: fixed the misleading `time="post", conley_lag_cutoff=2`
  example (now uses `time="period"`), added a "Note on
  `conley_lag_cutoff` semantics" paragraph.

Regression tests:
- `TestConleyPanelHelper::test_time_label_normalization_non_unit_spaced_int`:
  year-like (2020, 2021, 2022) and YYYYMM (202011, 202012, 202101) labels
  produce the same vcov as dense codes (1, 2, 3).
- `TestConleyPanelHelper::test_time_label_normalization_datetime64`:
  irregularly-spaced datetime64 labels normalize correctly.
- `TestConleyTWFE::test_twfe_conley_binary_post_label_normalization`:
  TWFE with binary `post` (the exact example the codex reviewer flagged)
  produces finite SE.
- `TestConleyTWFE::test_twfe_conley_summary_emits_conley_label`:
  summary contains "Conley spatial HAC" for panel Conley fits.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

diff_diff/conley.py

@@ -342,12 +342,25 @@ def _kernel_fn(u: np.ndarray) -> np.ndarray:
         # Phase 2 panel block-decomposed path (matches R conleyreg).
         time_arr = np.asarray(time)
         unit_arr = np.asarray(unit)
+        # Normalize time labels to dense panel-period codes (0..T-1) so that
+        # `conley_lag_cutoff` always refers to a count of panel periods, not
+        # a raw-label difference. Works for any orderable encoding (year ints
+        # like 2020/2021, YYYYMM like 202012/202101, datetime64, pd.Period,
+        # strings). np.unique returns sorted unique values and `return_inverse`
+        # gives the position of each row in that sort.
+        # **Note (deviation from R-conleyreg literal):** R conleyreg uses raw
+        # `time` values for the lag computation directly, which silently
+        # mishandles non-dense encodings (e.g. lag 1 between 202012 and 202101
+        # is 89 in raw integer differences). diff-diff normalizes first so
+        # `conley_lag_cutoff` is meaningfully a "number of observed panel
+        # periods" regardless of label scale.
+        _, time_codes = np.unique(time_arr, return_inverse=True)
         k = X.shape[1]
         meat = np.zeros((k, k))
         # Spatial component: within-period sandwich, summed across periods.
         with np.errstate(divide="ignore", over="ignore", invalid="ignore"):
-            for t_val in np.unique(time_arr):
-                mask_t = time_arr == t_val
+            for t_code in np.unique(time_codes):
+                mask_t = time_codes == t_code
                 S_t = S[mask_t]
                 D_t = _pairwise_distance_matrix(coords_arr[mask_t], metric)
                 K_t = _kernel_fn(D_t / cutoff)
@@ -362,7 +375,8 @@ def _kernel_fn(u: np.ndarray) -> np.ndarray:
                 for u_val in np.unique(unit_arr):
                     mask_u = unit_arr == u_val
                     S_u = S[mask_u]
-                    t_u = np.asarray(time_arr[mask_u], dtype=np.float64)
+                    # Use dense panel-period codes (NOT raw labels) for lag math.
+                    t_u = time_codes[mask_u].astype(np.float64)
                     lag_mat = np.abs(t_u[:, None] - t_u[None, :])
                     K_u = ((lag_mat <= L) & (lag_mat != 0)).astype(np.float64) * (
                         1.0 - lag_mat / (L + 1.0)

diff_diff/guides/llms-full.txt

@@ -1924,24 +1924,40 @@ reg = LinearRegression(
 ).fit(X, y)
 se = np.sqrt(np.diag(reg.vcov_))
 
-# Panel design: TWFE with within-unit Bartlett serial HAC (lag = 2 periods)
+# Panel design: TWFE with within-unit Bartlett serial HAC (lag = 2 periods).
+# `time` must be a panel-period index column with one row per (unit, period).
+# diff-diff internally normalizes the time labels to dense panel-period codes
+# 0..T-1, so any orderable encoding works — int years (2020, 2021, ...),
+# YYYYMM (202012, 202101, ...), datetime64, pd.Period, strings.
 res = TwoWayFixedEffects(
     vcov_type="conley",
     conley_coords=("lat", "lon"),        # column names on `data`
     conley_cutoff_km=500.0,
-    conley_lag_cutoff=2,                 # within-unit Bartlett up to 2 lags
-).fit(data, outcome="y", treatment="treated", time="post", unit="unit_id")
+    conley_lag_cutoff=2,                 # within-unit Bartlett up to 2 panel periods
+).fit(data, outcome="y", treatment="treated", time="period", unit="unit_id")
 
 # Panel design: MultiPeriodDiD with cross-sectional within-period only (lag=0)
 mp_res = MultiPeriodDiD(
     vcov_type="conley",
     conley_coords=("lat", "lon"),
     conley_cutoff_km=200.0,
     conley_lag_cutoff=0,                 # spatial-within-period only
-).fit(data, outcome="y", treatment="treated", time="t",
+).fit(data, outcome="y", treatment="treated", time="period",
       post_periods=[2, 3], unit="unit_id")
 ```
 
+**Note on `conley_lag_cutoff` semantics:** the lag is counted in **panel
+periods** (number of distinct sorted values in the `time` column), NOT in
+raw-label differences. Internally, time labels are normalized to dense codes
+`0..T-1` via `np.unique(return_inverse=True)`. For example, `time` values
+`(2020, 2021, 2022)` and `(202012, 202101, 202102)` both produce the same
+codes `(0, 1, 2)` and the same lag matrix. **Deviation from R `conleyreg`:**
+R uses raw `time` values directly in the lag computation, which silently
+mishandles non-dense encodings (`time = 202012, 202101` and `lag_cutoff=1`
+under R produces 0 weight because the raw difference is 89). diff-diff is
+the more robust default; for bit-exact R parity, pass `time` as a dense
+integer index.
+
 **Variance estimator — cross-sectional:**
 
     Var̂(β) = (X'X)^{-1} · ( Σ_{i,j} K(d_ij / h) · X_i ε_i ε_j X_j' ) · (X'X)^{-1}

diff_diff/results.py

@@ -56,11 +56,7 @@ def _format_vcov_label(
     """Compose a human-readable variance-family label for summary output.
 
     Returns None when vcov_type is not recognized so the caller can skip the
-    line silently (backward-compat). vcov_type='conley' is intentionally
-    not labeled here: DifferenceInDifferences / MultiPeriodDiD / TwoWayFixedEffects
-    all reject vcov_type='conley' at fit-time (Phase 1 supports cross-sectional
-    Conley only via direct compute_robust_vcov / LinearRegression), so a
-    Conley label cannot be reached on these result classes.
+    line silently (backward-compat).
     """
     if vcov_type == "classical":
         return "Classical OLS SEs (non-robust)"
@@ -77,6 +73,11 @@ def _format_vcov_label(
             return f"CR2 Bell-McCaffrey cluster-robust at {cluster_name}{suffix}"
         suffix = f", n={n_obs}" if n_obs else ""
         return f"HC2 + Bell-McCaffrey DOF (one-way{suffix})"
+    if vcov_type == "conley":
+        # Cross-sectional Conley on direct LinearRegression / compute_robust_vcov,
+        # or panel block-decomposed Conley (within-period spatial + within-unit
+        # Bartlett serial) on MultiPeriodDiD / TwoWayFixedEffects.
+        return "Conley spatial HAC (1999)"
     return None
 
 

docs/methodology/REGISTRY.md

@@ -2988,6 +2988,19 @@ through). diff-diff matches this asymmetry exactly for R parity. Independent
 temporal kernel choice would be a follow-up API extension if user demand
 emerges.
 
+**Note (deviation from R conleyreg literal: time-label normalization):**
+R `conleyreg` uses raw `time` values directly in the lag computation
+(`time_dist.cpp`'s `t_diff = abs(times - times[i])`). On non-dense time
+encodings (e.g., `time = 202012, 202101` for monthly panels), the raw
+difference is 89, so a `lag_cutoff=1` request silently drops valid lag-1
+serial pairs in R. diff-diff normalizes `time` to dense panel-period codes
+`0..T-1` via `np.unique(return_inverse=True)` before the lag computation,
+so `conley_lag_cutoff` always counts panel periods regardless of label
+encoding (int year, YYYYMM, datetime64, `pd.Period`, strings). On dense
+integer labels (the parity-test convention), the two paths produce
+bit-identical results. For non-dense encodings, diff-diff is the more
+robust default; pass `time` as a dense integer index for bit-exact R parity.
+
 **Kernel functions:**
 - `conley_kernel="bartlett"` (default): `K(u) = max(0, 1 - |u|)` evaluated on the pairwise distance `d_ij/h`. The radial 1-D form on pairwise distance, matching R `conleyreg`, Stata `acreg` (Colella et al. 2019), and Hsiang (2010).
 - `conley_kernel="uniform"`: `K(u) = 1{|u| ≤ 1}`. Conley 1999 page 11; spectral window negative in regions (footnote 11).

tests/test_conley_vcov.py

@@ -1316,6 +1316,40 @@ def test_twfe_conley_missing_lag_cutoff_raises(self, panel):
                 conley_cutoff_km=2000.0,
             ).fit(panel, outcome="y", treatment="treated", time="time", unit="unit")
 
+    def test_twfe_conley_binary_post_label_normalization(self, panel):
+        """TWFE with binary `post` (values {0,1}) + `conley_lag_cutoff=1`
+        produces the same finite vcov as the equivalent dense-period-index
+        fit. Closes the Codex P1 example — the time-label normalization
+        means lag is counted in panel periods regardless of how `time` is
+        encoded (binary post indicator vs. dense period index).
+        """
+        from diff_diff import TwoWayFixedEffects
+
+        # `panel` fixture uses `time` in {0, 1}, identical to a binary post.
+        # Rename to `post` to make the test scenario explicit.
+        df_post = panel.rename(columns={"time": "post"})
+        res = TwoWayFixedEffects(
+            vcov_type="conley",
+            conley_coords=("lat", "lon"),
+            conley_cutoff_km=2000.0,
+            conley_lag_cutoff=1,
+        ).fit(df_post, outcome="y", treatment="treated", time="post", unit="unit")
+        assert np.isfinite(res.se) and res.se > 0
+
+    def test_twfe_conley_summary_emits_conley_label(self, panel):
+        """Panel result summary must label the variance family as Conley
+        spatial HAC when vcov_type='conley'. Closes Codex P3."""
+        from diff_diff import TwoWayFixedEffects
+
+        res = TwoWayFixedEffects(
+            vcov_type="conley",
+            conley_coords=("lat", "lon"),
+            conley_cutoff_km=2000.0,
+            conley_lag_cutoff=1,
+        ).fit(panel, outcome="y", treatment="treated", time="time", unit="unit")
+        summary = res.summary()
+        assert "Conley spatial HAC" in summary
+
     def test_twfe_conley_within_vs_dummy_expansion_equivalence(self, panel):
         """FWL composability: TWFE (within-transform) + Conley should produce
         the SAME ATT SE as a dummy-expansion design with the same Conley
@@ -1830,6 +1864,76 @@ def test_panel_matches_block_decomposed_reference(self):
             )
             np.testing.assert_allclose(V_helper, V_ref, atol=1e-12)
 
+    def test_time_label_normalization_non_unit_spaced_int(self):
+        """Year-like int labels (2020, 2021, 2022) and YYYYMM labels
+        (202011, 202012, 202101) produce the same vcov as the equivalent
+        dense codes (0, 1, 2). Closes Codex P1: `conley_lag_cutoff` is a
+        count of panel periods, not raw label difference."""
+        X, residuals, coords, _, unit, bread, cutoff = self._panel_fixture(n_units=8, T=3, k=2)
+        time_dense = np.tile([1, 2, 3], 8)
+        time_years = np.tile([2020, 2021, 2022], 8)
+        time_yyyymm = np.tile([202011, 202012, 202101], 8)
+        V_dense = _compute_conley_vcov(
+            X,
+            residuals,
+            coords,
+            cutoff,
+            "haversine",
+            "bartlett",
+            bread,
+            time=time_dense,
+            unit=unit,
+            lag_cutoff=1,
+        )
+        for time_alt in (time_years, time_yyyymm):
+            V_alt = _compute_conley_vcov(
+                X,
+                residuals,
+                coords,
+                cutoff,
+                "haversine",
+                "bartlett",
+                bread,
+                time=time_alt,
+                unit=unit,
+                lag_cutoff=1,
+            )
+            np.testing.assert_allclose(V_alt, V_dense, atol=1e-12)
+
+    def test_time_label_normalization_datetime64(self):
+        """datetime64 time labels normalize to dense codes via np.unique."""
+        X, residuals, coords, _, unit, bread, cutoff = self._panel_fixture(n_units=6, T=3, k=2)
+        time_dense = np.tile([0, 1, 2], 6)
+        time_dt = np.tile(
+            np.array(["2024-01-01", "2024-04-01", "2024-08-01"], dtype="datetime64[D]"),
+            6,
+        )
+        V_dense = _compute_conley_vcov(
+            X,
+            residuals,
+            coords,
+            cutoff,
+            "haversine",
+            "bartlett",
+            bread,
+            time=time_dense,
+            unit=unit,
+            lag_cutoff=1,
+        )
+        V_dt = _compute_conley_vcov(
+            X,
+            residuals,
+            coords,
+            cutoff,
+            "haversine",
+            "bartlett",
+            bread,
+            time=time_dt,
+            unit=unit,
+            lag_cutoff=1,
+        )
+        np.testing.assert_allclose(V_dt, V_dense, atol=1e-12)
+
     def test_serial_kernel_bartlett_hardcoded_even_when_kernel_uniform(self):
         """conleyreg::time_dist hardcodes Bartlett-style temporal kernel
         regardless of the user's `kernel` choice. We mirror that asymmetry."""