Align public docstrings with Phase 1 Conley contract; drop redundant guards

igerber · claude · igerber · commit 5acef60cb541 · 2026-05-11T17:25:04.000-04:00
Address P2/P3 findings from CI Codex review of PR #411 R-rebased: P2 — Public docstrings for the cross-sectional supported APIs and the rejected panel surfaces were missing or stale: - `LinearRegression.__init__` and `solve_ols()` docstrings now document `conley_coords`, `conley_cutoff_km`, `conley_metric`, `conley_kernel` (the four newly added kwargs) plus the cluster/weights/survey rejection contract, mirroring the `compute_robust_vcov` docstring. - `SyntheticDiD` class docstring gains a `Notes (Conley spatial-HAC rejection)` block stating that `vcov_type` and `conley_*` kwargs raise `TypeError` at __init__ / set_params, with the bootstrap-variance rationale. - `TwoWayFixedEffects` class docstring gains a paragraph on the Phase 1 panel rejection (parallel to the existing HC2/Bell-McCaffrey paragraph), including the sklearn-style API-symmetry rationale for why constructor kwargs are inherited from DifferenceInDifferences. P3 — Two cleanups: - Removed the redundant `MultiPeriodDiD(absorb=..., vcov_type="conley")` pre-guard; the unconditional Conley reject immediately after covered the same path and the special-cased message was misleading (it told users to "drop absorb=" even though dropping absorb= would NOT make Conley available on MultiPeriodDiD). - Renamed `test_bartlett_psd_on_random_distances` to `test_bartlett_kernel_finite_and_in_unit_interval`. The original name encoded a stronger property than the methodology contract guarantees (radial 1-D Bartlett is a practitioner specialization, not PSD- guaranteed). The renamed test asserts finite / symmetric / [0, 1]- bounded instead; the both-kernel indefiniteness warning is locked separately by `test_indefinite_meat_warning_fires_for_bartlett`. Doc surfaces: - `docs/methodology/papers/colella-et-al-2019-review.md`: updated the Phase 1 parity target paragraph to state that Phase 1 ships only cross-sectional Conley with R `conleyreg` parity; Stata `acreg` TWFE parity is a Phase 2 target. - PR body summary rewritten to match the shipped contract: cross- sectional `LinearRegression` / `compute_robust_vcov` supported, DiD / MultiPeriodDiD / TWFE reject at fit-time. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/diff_diff/estimators.py b/diff_diff/estimators.py
@@ -1374,19 +1374,13 @@ def fit(  # type: ignore[override]
                 "switch to fixed_effects= dummies for a full-dummy design."
             )
 
-        # Reject Conley combinations early at the estimator level (see
-        # DifferenceInDifferences.fit for the matching block and rationale).
-        if absorb and self.vcov_type == "conley":
-            raise NotImplementedError(
-                "MultiPeriodDiD(absorb=..., vcov_type='conley') is deferred "
-                "to a follow-up. Use fixed_effects= dummies for an equivalent "
-                "FE design with the full projection, or drop absorb= for "
-                "cross-sectional Conley."
-            )
         # MultiPeriodDiD is intrinsically a multi-period panel estimator;
         # cross-sectional Conley does not apply (same rationale as
         # DifferenceInDifferences.fit's panel guard above). Phase 2 will
-        # add a documented space-time HAC.
+        # add a documented space-time HAC. The rejection is unconditional
+        # — `absorb` and other Conley-adjacent kwargs cannot make
+        # MultiPeriodDiD Conley-compatible because the panel structure is
+        # the load-bearing reason Phase 1 cannot apply Conley here.
         if self.vcov_type == "conley":
             raise NotImplementedError(
                 "MultiPeriodDiD(vcov_type='conley') is deferred to Phase 2 "
diff --git a/diff_diff/linalg.py b/diff_diff/linalg.py
@@ -520,6 +520,30 @@ def solve_ols(
           raises ``NotImplementedError`` because the BM DOF helper is
           inconsistent with ``solve_ols``'s WLS transform. Tracked in
           ``TODO.md``.
+        - ``"conley"``: Conley (1999) spatial-HAC sandwich. Requires
+          ``conley_coords`` (n × 2 array) and ``conley_cutoff_km`` (positive
+          bandwidth, no default per Conley 1999 Section 5's sensitivity-grid
+          recommendation). Combining with ``cluster_ids`` or ``weights``
+          raises ``NotImplementedError`` (combined product kernel + Bertanha-
+          Imbens 2014 weighted-Conley deferred to Phase 2+). Cross-sectional
+          one-way only.
+    conley_coords : ndarray of shape (n, 2), optional
+        Required when ``vcov_type="conley"``. Two-column array of
+        ``[lat, lon]`` (degrees, for ``conley_metric="haversine"``) or
+        projected coordinates (for ``conley_metric="euclidean"`` / callable
+        metric).
+    conley_cutoff_km : float, optional
+        Required when ``vcov_type="conley"``. Positive finite bandwidth in
+        km (haversine) or coord units (euclidean / callable).
+    conley_metric : {"haversine", "euclidean", callable}, default "haversine"
+        Distance metric. Haversine uses Earth's mean radius 6371.01 km
+        (matching R ``conleyreg``). Euclidean treats coords as already
+        projected. Callable signature ``(coords1, coords2) -> n×n``.
+    conley_kernel : {"bartlett", "uniform"}, default "bartlett"
+        Kernel evaluated on pairwise distance ``d_ij/h``. Both kernels emit
+        a ``UserWarning`` if the resulting meat is materially indefinite;
+        the radial 1-D Bartlett (matching R ``conleyreg``) is not formally
+        PSD-guaranteed — see :func:`compute_robust_vcov`.
 
     Returns
     -------
@@ -2363,6 +2387,37 @@ class LinearRegression:
         sandwich, the class stores per-coefficient BM Satterthwaite DOF
         (``self._bm_dof``) and threads it into ``get_inference``.
 
+        For ``"conley"`` (Conley 1999 spatial-HAC) the supported Phase 1
+        path is the cross-sectional `LinearRegression` / `compute_robust_vcov`
+        surface; requires ``conley_coords`` (n × 2 array) and a positive
+        ``conley_cutoff_km``. Combining ``vcov_type="conley"`` with
+        ``cluster_ids``, ``weights``, or ``survey_design`` raises
+        ``NotImplementedError`` (combined product kernel + Bertanha-Imbens
+        2014 weighted-Conley deferred to Phase 2+). The panel DiD /
+        MultiPeriodDiD / TwoWayFixedEffects estimators reject
+        ``vcov_type="conley"`` at fit-time entirely in Phase 1.
+    conley_coords : ndarray of shape (n, 2), optional
+        Required when ``vcov_type="conley"``. Two-column array of
+        ``[lat, lon]`` (degrees, for ``conley_metric="haversine"``) or
+        projected coordinates (for ``conley_metric="euclidean"`` / callable
+        metric). Raises ``ValueError`` when missing under Conley.
+    conley_cutoff_km : float, optional
+        Required when ``vcov_type="conley"``. Positive finite bandwidth in
+        km (haversine) or coord units (euclidean / callable). No default
+        per Conley 1999 Section 5's sensitivity-grid recommendation.
+    conley_metric : {"haversine", "euclidean", callable}, default "haversine"
+        Distance metric. Haversine uses Earth's mean radius 6371.01 km
+        matching R ``conleyreg``. Euclidean treats the coords as already
+        projected. Callable signature ``(coords1, coords2) -> n×n``.
+    conley_kernel : {"bartlett", "uniform"}, default "bartlett"
+        Kernel evaluated on pairwise distance ``d_ij/h``. ``"bartlett"`` is
+        the radial 1-D specialization (matching R ``conleyreg``);
+        ``"uniform"`` is the truncated indicator. Both kernels emit a
+        ``UserWarning`` if the resulting meat is materially indefinite —
+        neither is formally PSD-guaranteed in the radial pairwise form
+        (Conley 1999's explicit PSD Bartlett formula is the 2-D separable
+        product window, Eq 3.14, not the 1-D radial pairwise form).
+
     Attributes
     ----------
     coefficients_ : ndarray
diff --git a/diff_diff/synthetic_did.py b/diff_diff/synthetic_did.py
@@ -86,6 +86,19 @@ class SyntheticDiD(DifferenceInDifferences):
         Random seed for reproducibility. If None (default), results
         will vary between runs.
 
+    Notes (Conley spatial-HAC rejection)
+    ------------------------------------
+    SyntheticDiD does not support the Conley (1999) spatial-HAC analytical
+    sandwich. Passing ``vcov_type="conley"`` or any non-``None`` Conley
+    keyword (``conley_coords``, ``conley_cutoff_km``, ``conley_metric``,
+    ``conley_kernel``) to ``__init__`` or ``set_params`` raises
+    ``TypeError``. Rationale: SyntheticDiD's variance is derived from
+    bootstrap / jackknife / placebo resampling (Arkhangelsky et al. 2021
+    Algorithms 2–4), not the sandwich identity Conley plugs into. Adding
+    Conley support would require either an analytical SDID sandwich path
+    or a spatial-block bootstrap (Politis-Romano 1994 territory). Tracked
+    as a follow-up in ``TODO.md``.
+
     Attributes
     ----------
     results_ : SyntheticDiDResults
diff --git a/diff_diff/twfe.py b/diff_diff/twfe.py
@@ -67,6 +67,20 @@ class TwoWayFixedEffects(DifferenceInDifferences):
     ``TODO.md`` under Methodology/Correctness; also documented in
     ``docs/methodology/REGISTRY.md``.
 
+    **Conley spatial-HAC (``vcov_type="conley"``) is rejected at fit-time
+    in Phase 1.** TwoWayFixedEffects is intrinsically a multi-period panel
+    estimator and Phase 1's cross-sectional Conley does not handle the
+    time dimension — applying it over (unit, time) rows would treat same-
+    unit cross-time pairs as ``d_ij = 0 → K = 1``, mishandling the space-
+    time HAC. The supported Phase 1 path for Conley is direct
+    ``compute_robust_vcov`` / ``LinearRegression`` on a single-period
+    regression. The ``conley_*`` kwargs are inherited from
+    ``DifferenceInDifferences.__init__`` for sklearn-style API symmetry
+    (``get_params`` / ``set_params`` round-trip), but
+    ``TwoWayFixedEffects(vcov_type="conley").fit(...)`` raises
+    ``NotImplementedError``. Phase 2 will add the space-time product kernel
+    (Driscoll-Kraay) and lift the rejection.
+
     Warning: TWFE can be biased with staggered treatment timing
     and heterogeneous treatment effects. Consider using
     more robust estimators (e.g., Callaway-Sant'Anna) for
diff --git a/docs/methodology/papers/colella-et-al-2019-review.md b/docs/methodology/papers/colella-et-al-2019-review.md
@@ -190,7 +190,7 @@ This is a parity gap relative to acreg - implementers must consult acreg source.
 
 ### Relation to Existing diff-diff Estimators
 
-- **Phase 1 parity target:** `vcov_method="conley"` on TWFE must match acreg to <=1e-6 on at least 2-3 fixtures. The `coords=("lat","lon")` and `cutoff_km=<float>` parameters map directly onto acreg's lat/lon + cutoff inputs.
+- **Phase 1 parity target (UPDATED):** Phase 1 ships `vcov_type="conley"` on **cross-sectional** `compute_robust_vcov` / `LinearRegression` only, with parity verified against R `conleyreg` (Düsterhöft 2021) to ≤1e-6 on three benchmark fixtures. Panel estimators (`DifferenceInDifferences`, `MultiPeriodDiD`, `TwoWayFixedEffects`) reject `vcov_type="conley"` at fit-time because the radial 1-D pairwise Conley does not handle the time dimension — applying it over (unit, time) rows would treat same-unit cross-time pairs as `d_ij = 0 → K = 1`, mishandling the space-time HAC. **Stata `acreg` parity for TWFE / panel space-time Conley is a Phase 2 target**, alongside the Driscoll-Kraay product-kernel implementation. The `coords` and `cutoff_km` parameter mapping below is still accurate for the cross-sectional path.
 - **Reduces to HC0** when the cutoff is small enough that `S = I` (no neighbour pairs). The paper does not state this explicitly, but the meat formula collapses to `X' diag(e^2) X` in that case, which is HC0 (White 1980, equation referenced page 4).
 - **Reduces to one-way clustering** when `S = block-diagonal indicator(same cluster)` (see Section 2, p. 6: Cameron et al. 2011 "can be embedded in this framework"). For multiway clustering, the paper says (page 6): "Multiway clustering assumes a particular *regularity condition* in the clustering structure ... However, in many real-life settings, this particular clustering structure may not hold." The acreg estimator is more flexible and the reduction to multiway clustering is approximate (binary `S` with the union-of-clusters structure).
 - **Cluster + spatial joint mode:** The paper does NOT formally combine cluster-robust with spatial-HAC. However, since `S` is arbitrary, one can construct `S` as the elementwise OR of the cluster-indicator matrix and the spatial-cutoff matrix; this gives a joint estimator. acreg likely exposes both options - verify.
diff --git a/tests/test_conley_vcov.py b/tests/test_conley_vcov.py
@@ -83,16 +83,27 @@ def test_uniform_kernel_above_one_zero(self):
     def test_uniform_kernel_at_zero_one(self):
         np.testing.assert_allclose(_uniform_kernel(np.array([0.0])), 1.0)
 
-    def test_bartlett_psd_on_random_distances(self):
-        """Bartlett-weighted Gram matrix has all eigenvalues >= -tol."""
+    def test_bartlett_kernel_finite_and_in_unit_interval(self):
+        """Bartlett-weighted kernel matrix on random pairwise distances is
+        finite, symmetric, and bounded in [0, 1]. We do NOT assert PSD here:
+        the radial 1-D Bartlett on pairwise distance is a practitioner
+        specialization of Conley 1999 (matching R conleyreg) and is NOT
+        formally PSD-guaranteed — see REGISTRY ConleySpatialHAC. The
+        runtime path emits a UserWarning if the resulting Conley meat is
+        materially indefinite; that contract is locked separately in
+        ``test_indefinite_meat_warning_fires_for_bartlett``.
+        """
         rng = np.random.default_rng(seed=11)
         n = 25
         coords = rng.uniform(0, 1, size=(n, 2))
         diff = coords[:, None, :] - coords[None, :, :]
         D = np.sqrt((diff * diff).sum(axis=-1))
         K = _bartlett_kernel(D / 0.3)
-        eigvals = np.linalg.eigvalsh(0.5 * (K + K.T))  # ensure symmetric
-        assert eigvals.min() > -1e-12
+        assert K.shape == (n, n)
+        assert np.all(np.isfinite(K))
+        assert np.all(K >= 0.0)
+        assert np.all(K <= 1.0)
+        np.testing.assert_allclose(K, K.T, atol=1e-15)
 
 
 # ---------------------------------------------------------------------------
