diff-diff 3.4.0__tar.gz → 3.4.2__tar.gz

{diff_diff-3.4.0 → diff_diff-3.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.4.0
+Version: 3.4.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -159,7 +159,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [SunAbraham](https://diff-diff.readthedocs.io/en/stable/api/staggered.html) - Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies
 - [ImputationDiD](https://diff-diff.readthedocs.io/en/stable/api/imputation.html) - Borusyak, Jaravel & Spiess (2024) imputation estimator, most efficient under homogeneous effects
 - [TwoStageDiD](https://diff-diff.readthedocs.io/en/stable/api/two_stage.html) - Gardner (2022) two-stage estimator with GMM sandwich variance
-- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing
+- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing; supports survey-design variance under `survey_design=` for HC1 / CR1 (Wave E.1 Binder TSL) and Conley (Wave E.2 panel-aware stratified-Conley sandwich on per-period PSU totals; extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC — `lag>0` requires an effective PSU via explicit `survey_design.psu` or injected `cluster=<col>`); `SurveyDesign.subpopulation()` preserves full-design `n_psu` / `df_survey` via zero-padded scores (Wave E.3, R `svyrecvar(subset())` form)
 - [SyntheticDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - Synthetic DiD combining standard DiD and synthetic control for few treated units
 - [TripleDifference](https://diff-diff.readthedocs.io/en/stable/api/triple_diff.html) - triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility
 - [ContinuousDiD](https://diff-diff.readthedocs.io/en/stable/api/continuous_did.html) - Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves

{diff_diff-3.4.0 → diff_diff-3.4.2}/README.md

@@ -106,7 +106,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [SunAbraham](https://diff-diff.readthedocs.io/en/stable/api/staggered.html) - Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies
 - [ImputationDiD](https://diff-diff.readthedocs.io/en/stable/api/imputation.html) - Borusyak, Jaravel & Spiess (2024) imputation estimator, most efficient under homogeneous effects
 - [TwoStageDiD](https://diff-diff.readthedocs.io/en/stable/api/two_stage.html) - Gardner (2022) two-stage estimator with GMM sandwich variance
-- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing
+- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing; supports survey-design variance under `survey_design=` for HC1 / CR1 (Wave E.1 Binder TSL) and Conley (Wave E.2 panel-aware stratified-Conley sandwich on per-period PSU totals; extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC — `lag>0` requires an effective PSU via explicit `survey_design.psu` or injected `cluster=<col>`); `SurveyDesign.subpopulation()` preserves full-design `n_psu` / `df_survey` via zero-padded scores (Wave E.3, R `svyrecvar(subset())` form)
 - [SyntheticDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - Synthetic DiD combining standard DiD and synthetic control for few treated units
 - [TripleDifference](https://diff-diff.readthedocs.io/en/stable/api/triple_diff.html) - triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility
 - [ContinuousDiD](https://diff-diff.readthedocs.io/en/stable/api/continuous_did.html) - Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/__init__.py

@@ -293,7 +293,7 @@ ETWFE = WooldridgeDiD
 DCDH = ChaisemartinDHaultfoeuille
 HAD = HeterogeneousAdoptionDiD
 
-__version__ = "3.4.0"
+__version__ = "3.4.2"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/chaisemartin_dhaultfoeuille.py

@@ -19,7 +19,7 @@ References
 - de Chaisemartin, C. & D'Haultfoeuille, X. (2020). Two-Way Fixed Effects
   Estimators with Heterogeneous Treatment Effects. *American Economic
   Review*, 110(9), 2964-2996.
-- de Chaisemartin, C. & D'Haultfoeuille, X. (2022, revised 2023).
+- de Chaisemartin, C. & D'Haultfoeuille, X. (2022, revised July 2023).
   Difference-in-Differences Estimators of Intertemporal Treatment Effects.
   NBER Working Paper 29873. Web Appendix Section 3.7.3 contains the
   cohort-recentered plug-in variance formula implemented here.
@@ -4506,11 +4506,15 @@ def _compute_per_period_dids(
         leaver_mask = (d_prev == 1) & (d_curr == 0) & present
         stable1_mask = (d_prev == 1) & (d_curr == 1) & present
 
-        # AER 2020 Theorem 3 N_{a,b,t} weights are CELL counts, not
-        # within-cell observation sums. Each (g, t) cell contributes once
+        # Library equal-cell weighting: N_{a,b,t} here counts (g, t)
+        # cells in each transition state. Each cell contributes once
         # regardless of how many original observations fed into the
-        # y_gt cell mean. See REGISTRY.md ChaisemartinDHaultfoeuille
-        # estimator equations.
+        # y_gt cell mean. This is a documented library deviation from
+        # AER 2020 Equation 3 (which defines N_{d,d',t} = sum N_{g,t},
+        # i.e., observation-sum weighting) and from R DIDmultiplegtDYN
+        # (individual-row weighting on unbalanced inputs). See
+        # REGISTRY.md ## ChaisemartinDHaultfoeuille L517 "Note (deviation
+        # from R DIDmultiplegtDYN ...)" for the full text.
         n_10 = int(joiner_mask.sum())
         n_00 = int(stable0_mask.sum())
         n_01 = int(leaver_mask.sum())
@@ -4635,7 +4639,8 @@ def _compute_placebo(
         leaver_mask = (d_pre_prev == 1) & (d_prev == 1) & (d_curr == 0) & present
         stable1_mask = (d_pre_prev == 1) & (d_prev == 1) & (d_curr == 1) & present
 
-        # Placebo weights are CELL counts (matching Theorem 3 convention)
+        # Placebo weights: library equal-cell counts (same documented
+        # deviation as the main DID_M path; see REGISTRY.md L517).
         n_10 = int(joiner_mask.sum())
         n_00 = int(stable0_mask.sum())
         n_01 = int(leaver_mask.sum())

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/chaisemartin_dhaultfoeuille_results.py

@@ -13,7 +13,7 @@ References
 - de Chaisemartin, C. & D'Haultfoeuille, X. (2020). Two-Way Fixed Effects
   Estimators with Heterogeneous Treatment Effects. *American Economic
   Review*, 110(9), 2964-2996.
-- de Chaisemartin, C. & D'Haultfoeuille, X. (2022, revised 2023).
+- de Chaisemartin, C. & D'Haultfoeuille, X. (2022, revised July 2023).
   Difference-in-Differences Estimators of Intertemporal Treatment Effects.
   NBER Working Paper 29873.
 """
@@ -335,8 +335,13 @@ class ChaisemartinDHaultfoeuilleResults:
         ``L_max >= 1`` it was repurposed to hold the per-group count
         that matches the ``DID_1`` estimand. Originally equals
         once regardless of how many original observations fed into it.
-        This is the ``N_S`` denominator of ``DID_M`` per AER 2020
-        Theorem 3 — cell counts, not within-cell observation counts.
+        This is the ``N_S`` denominator of ``DID_M`` under the library's
+        equal-cell weighting convention (cell counts, not within-cell
+        observation sums). The AER 2020 paper's Equation 3 defines
+        ``N_{d,d',t} = sum_g N_{g,t}`` (observation sums); the
+        library's choice is a documented deviation - see
+        ``docs/methodology/REGISTRY.md`` ``## ChaisemartinDHaultfoeuille``
+        L517 for the full Note.
     n_cohorts : int
         Distinct cohorts ``(D_{g,1}, F_g, S_g)`` after filtering.
     n_groups_dropped_crossers : int

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/conley.py

@@ -365,6 +365,61 @@ def _uniform_kernel(u: np.ndarray) -> np.ndarray:
     return (np.abs(u) <= 1.0).astype(np.float64)
 
 
+def _serial_bartlett_kernel_matrix(t_codes: np.ndarray, L: int) -> np.ndarray:
+    """Within-unit Newey-West (1987) Bartlett HAC kernel matrix for serial
+    correlation in panel data, indexed by panel-wide dense time codes.
+
+    Returns the K matrix with ``K[i, j] = 1 - |t_i - t_j| / (L + 1)`` for
+    ``0 < |t_i - t_j| <= L``, else 0. The lag-0 diagonal is excluded so
+    callers can add this to a spatial within-period meat without
+    double-counting the diagonal.
+
+    Uses the 1-D radial pairwise form (matches conleyreg::time_dist), NOT
+    Conley 1999 Eq 3.14's 2-D separable product window — see the methodology
+    lock at :func:`_compute_conley_meat` for context.
+    """
+    t = t_codes.astype(np.float64, copy=False)
+    lag_mat = np.abs(t[:, None] - t[None, :])
+    return ((lag_mat <= L) & (lag_mat != 0)).astype(np.float64) * (1.0 - lag_mat / (L + 1.0))
+
+
+def _validate_meat_psd(
+    M: np.ndarray,
+    *,
+    error_msg: str,
+    warning_template: str,
+    stacklevel: int = 3,
+) -> None:
+    """Finite + PSD guard for sandwich meat matrices. Raises ``ValueError``
+    on non-finite entries; warns ``UserWarning`` when ``min(eigvalsh(M)) <
+    -1e-12``.
+
+    Parameters
+    ----------
+    error_msg
+        Message passed to ``ValueError`` on non-finite entries.
+    warning_template
+        Format string for the negative-eigenvalue warning. May contain an
+        ``{eigval}`` placeholder; the caller embeds ``{eigval:.2e}`` directly
+        in the template so the helper formats the minimum eigenvalue with
+        scientific notation.
+    stacklevel
+        Frame count from inside ``_validate_meat_psd``: ``stacklevel=N``
+        attributes the warning to the Nth caller above the helper itself.
+        Default 3 covers a single intermediate frame (the helper's direct
+        caller's caller); pass an explicit value matching call-site depth.
+    """
+    if not np.all(np.isfinite(M)):
+        raise ValueError(error_msg)
+    eigvals = np.linalg.eigvalsh(M)
+    if eigvals.size and eigvals.min() < -1e-12:
+        warnings.warn(
+            warning_template.format(eigval=eigvals.min()),
+            UserWarning,
+            stacklevel=stacklevel,
+        )
+
+
 def _compute_spatial_bartlett_meat_sparse(
     S: np.ndarray,
     coords: np.ndarray,
@@ -957,37 +1012,33 @@ def _compute_conley_meat(
                     mask_u = unit_arr == u_val
                     scores_u = scores[mask_u]
                     # 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)
-                    )
+                    K_u = _serial_bartlett_kernel_matrix(time_codes[mask_u], L)
                     meat += scores_u.T @ K_u @ scores_u
-    if not np.all(np.isfinite(meat)):
-        raise ValueError(
-            "Conley meat contains non-finite values; check residuals and "
-            "score matrix for NaN/Inf."
-        )
-
     # PSD guard. Neither the uniform kernel (Conley 1999 fn 11) nor the
     # radial 1-D Bartlett specialization is formally PSD-guaranteed —
     # Conley's explicit PSD Bartlett formula (Eq 3.14) is the 2-D separable
     # product window, not the 1-D radial pairwise form that R `conleyreg`,
     # Stata `acreg`, and this implementation use. Check both kernels.
-    eigvals = np.linalg.eigvalsh(meat)
-    if eigvals.size and eigvals.min() < -1e-12:
-        warnings.warn(
+    # ``{eigval:.2e}`` is a literal placeholder for ``_validate_meat_psd``;
+    # only ``{kernel!r}`` is interpolated by the f-string here.
+    _validate_meat_psd(
+        meat,
+        error_msg=(
+            "Conley meat contains non-finite values; check residuals and "
+            "score matrix for NaN/Inf."
+        ),
+        warning_template=(
             f"Conley meat with conley_kernel={kernel!r} has a materially "
-            f"negative eigenvalue ({eigvals.min():.2e}); the variance "
+            "negative eigenvalue ({eigval:.2e}); the variance "
             "estimator is not guaranteed PSD on this design. Both "
             "supported kernels (radial bartlett and uniform) are "
             "practitioner specializations of Conley 1999 and are not "
             "formally PSD-guaranteed; consider varying conley_cutoff_km "
             "or reviewing the design for collinearity / degenerate "
-            "residual structure.",
-            UserWarning,
-            stacklevel=3,
-        )
+            "residual structure."
+        ),
+        stacklevel=4,
+    )
 
     return meat
 

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/estimators.py

@@ -1891,8 +1891,13 @@ class MultiPeriodDiD(DifferenceInDifferences):
                 else:
                     # Cluster-aware CR2 BM Satterthwaite DOF for per-coefficient
                     # AND post-period-average compound contrast (Gate 6 lift).
-                    # Weighted CR2-BM is a separate gate; survey paths never
-                    # reach this block (outer `not _use_survey_vcov` guard).
+                    # This branch is guarded above by `not _use_survey_vcov`,
+                    # so when reached, `survey_weights` is None (survey designs
+                    # always route through the TSL path). The clubSandwich
+                    # WLS-CR2 port lifted `_compute_cr2_bm_contrast_dof` to
+                    # accept `weights=`, but no MPD entry point currently
+                    # passes non-None weights here — `weights=None` is the
+                    # de facto contract on this code path today.
                     _dof_all = _compute_cr2_bm_contrast_dof(
                         X_kept,
                         effective_cluster_ids,

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/guides/llms-full.txt

@@ -2,7 +2,7 @@
 
 > A Python library for Difference-in-Differences causal inference analysis. Provides sklearn-like estimators with statsmodels-style output for econometric analysis.
 
-- Version: 3.4.0
+- Version: 3.4.2
 - Repository: https://github.com/igerber/diff-diff
 - License: MIT
 - Dependencies: numpy, pandas, scipy (no statsmodels dependency)
@@ -188,7 +188,7 @@ CallawaySantAnna(
     anticipation: int = 0,                       # Anticipation periods
     estimation_method: str = "dr",               # "dr", "ipw", or "reg"
     alpha: float = 0.05,
-    cluster: str | None = None,                  # Defaults to unit-level clustering
+    cluster: str | None = None,                  # Cluster col; activates CR1 on the IF via synthesized SurveyDesign(psu=col). None → per-unit IF.
     n_bootstrap: int = 0,                        # 0 = analytical SEs, 999+ recommended
     bootstrap_weights: str | None = None,        # "rademacher", "mammen", or "webb"
     seed: int | None = None,
@@ -196,6 +196,7 @@ CallawaySantAnna(
     base_period: str = "varying",                # "varying" or "universal"
     cband: bool = True,                          # Simultaneous confidence bands
     pscore_trim: float = 0.01,                   # Propensity score trimming bound
+    vcov_type: str = "hc1",                      # {"hc1"} only — IF-based variance per Callaway & Sant'Anna (2021). Analytical-sandwich {classical, hc2, hc2_bm} and conley REJECTED at __init__ (see REGISTRY.md IF-vs-sandwich subsection).
 )
 ```
 
@@ -335,10 +336,11 @@ SunAbraham(
     control_group: str = "never_treated",        # "never_treated" or "not_yet_treated"
     anticipation: int = 0,
     alpha: float = 0.05,
-    cluster: str | None = None,                  # Defaults to unit-level clustering
+    cluster: str | None = None,                  # Defaults to unit-level clustering (dropped on explicit vcov_type='hc2' / 'classical')
     n_bootstrap: int = 0,                        # 0 = analytical cluster-robust SEs
     seed: int | None = None,
     rank_deficient_action: str = "warn",
+    vcov_type: str = "hc1",                       # {"classical","hc1","hc2","hc2_bm"}; classical/hc2/hc2_bm route through full-dummy saturated design. survey_design=... is rejected for classical/hc2/hc2_bm (use hc1 default for surveys)
 )
 ```
 
@@ -377,12 +379,14 @@ ImputationDiD(
     anticipation: int = 0,
     alpha: float = 0.05,
     cluster: str | None = None,                  # Defaults to unit-level clustering
+    vcov_type: str = "hc1",                      # {"hc1"} only — IF-based variance per Borusyak et al. (2024) Theorem 3
     n_bootstrap: int = 0,                        # 0 = analytical (Theorem 3 variance)
     bootstrap_weights: str = "rademacher",       # "rademacher", "mammen", or "webb"
     seed: int | None = None,
     rank_deficient_action: str = "warn",
     horizon_max: int | None = None,              # Max event-study horizon
     aux_partition: str = "cohort_horizon",        # "cohort_horizon", "cohort", or "horizon"
+    pretrends: bool = False,                     # Include pre-treatment horizons in event study
 )
 ```
 
@@ -400,6 +404,7 @@ imp.fit(
     covariates: list[str] = None,
     aggregate: str = None,         # None, "simple", "event_study", "group", or "all"
     balance_e: int = None,
+    survey_design: SurveyDesign = None,  # Optional design-based inference (pweight + analytical strata/PSU/FPC or replicate BRR/Fay/JK1/JKn/SDR)
 ) -> ImputationDiDResults
 ```
 
@@ -575,6 +580,7 @@ TripleDifference(
     estimation_method: str = "dr",            # "dr", "reg", or "ipw"
     robust: bool = True,
     cluster: str | None = None,
+    vcov_type: str = "hc1",                   # {"hc1"} only — IF-based variance per Ortiz-Villavicencio & Sant'Anna (2025). Analytical-sandwich {classical, hc2, hc2_bm} and conley REJECTED at __init__ (see REGISTRY.md IF-vs-sandwich subsection).
     alpha: float = 0.05,
     pscore_trim: float = 0.01,
     rank_deficient_action: str = "warn",
@@ -742,6 +748,7 @@ StackedDiD(
     alpha: float = 0.05,
     anticipation: int = 0,
     rank_deficient_action: str = "warn",
+    vcov_type: str = "hc1",                   # {"hc1","hc2_bm"}; classical/hc2 rejected (intrinsically clustered), conley deferred. survey_design=... requires hc1
 )
 ```
 
@@ -965,6 +972,13 @@ WooldridgeDiD(
     bootstrap_weights: str = "rademacher",
     seed: int | None = None,
     rank_deficient_action: str = "warn",
+    vcov_type: str = "hc1",                 # {"classical","hc1","hc2","hc2_bm"}; OLS path only.
+                                            # hc1 (default) preserves prior bit-equal within-transform CR1.
+                                            # hc2_bm auto-routes to full-dummy + clubSandwich WLS-CR2 algebra.
+                                            # classical/hc2 auto-drop the unit auto-cluster (one-way only);
+                                            # explicit cluster="X" + one-way raises at the linalg validator.
+                                            # conley deferred. method != "ols" requires hc1 (QMLE CR2-BM TBD).
+                                            # survey_design= requires hc1 (survey TSL overrides analytical).
 )
 ```
 
@@ -1267,7 +1281,15 @@ ImputationDiDResults, TwoStageDiDResults, StackedDiDResults, and EfficientDiDRes
 
 Each event study effect dict contains: `effect`, `se`, `t_stat`, `p_value`, `conf_int`, `n_obs` (or `n_groups`).
 
-**Methods:** `summary()`, `print_summary()`, `to_dataframe()`
+**Variance metadata** (`ImputationDiDResults` carries these; other staggered Results may surface a subset):
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `vcov_type` | `str` | Variance estimator family (`"hc1"` for IF-based estimators; permanently narrow on `ImputationDiD` / `CallawaySantAnna` / `TripleDifference` per IF-vs-sandwich taxonomy) |
+| `cluster_name` | `str | None` | Effective cluster column name (e.g. `"unit"` for default `cluster=None`); `None` under survey designs (the survey block already names PSU/strata) |
+| `n_clusters` | `int | None` | Number of effective clusters; `None` under survey designs |
+
+**Methods:** `summary()`, `print_summary()`, `to_dataframe()`, `to_dict()` (flat dict of headline aliases + `vcov_type` + conditional `cluster_name`/`n_clusters`/`n_bootstrap`/`inference_method`)
 
 ### ContinuousDiDResults
 

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/guides/llms.txt

@@ -10,10 +10,6 @@ diff-diff offers 17 estimators covering basic 2x2 DiD, modern staggered adoption
 - Source: https://github.com/igerber/diff-diff
 - Docs: https://diff-diff.readthedocs.io/en/stable/
 
-## Agent Quickstart
-
-LLM agents: call `diff_diff.agent_workflow(df, unit=..., time=..., treatment=..., outcome=...)` first. It prints the recommended 5-step workflow (`profile_panel` → `get_llm_guide` → `<Estimator>().fit` → `practitioner_next_steps` → `BusinessReport`) with your column names wired in.
-
 ## Practitioner Workflow (based on Baker et al. 2025)
 
 IMPORTANT: For rigorous DiD analysis, follow these 8 steps. Skipping
@@ -62,7 +58,7 @@ Full practitioner guide: call `diff_diff.get_llm_guide("practitioner")`
 - [SunAbraham](https://diff-diff.readthedocs.io/en/stable/api/staggered.html): Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies
 - [ImputationDiD](https://diff-diff.readthedocs.io/en/stable/api/imputation.html): Borusyak, Jaravel & Spiess (2024) imputation estimator — most efficient under homogeneous effects
 - [TwoStageDiD](https://diff-diff.readthedocs.io/en/stable/api/two_stage.html): Gardner (2022) two-stage estimator with GMM sandwich variance
-- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html): Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover-on-control; reuses `conley_coords` for ring construction; handles non-staggered and staggered timing
+- [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html): Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover-on-control; reuses `conley_coords` for ring construction; handles non-staggered and staggered timing; supports `SurveyDesign(weights, strata, psu, fpc)` under `vcov_type="hc1"` with optional `cluster=<col>` for CR1 via Gerber (2026) Binder TSL (Wave E.1) and under `vcov_type="conley"` via a panel-aware stratified-Conley sandwich on per-period PSU totals (Wave E.2 cross-sectional `conley_lag_cutoff=0`) extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC (Newey-West 1987 separable form; `lag>0` requires an effective PSU via explicit `survey_design.psu` or injected `cluster=<col>`), both composed with the Wave D Gardner GMM correction; `SurveyDesign.subpopulation()` preserves full-design `n_psu` / `df_survey` via zero-padded scores at the meat-helper boundary (Wave E.3, R `svyrecvar(subset())` form) (replicate weights queued as follow-up)
 - [SyntheticDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html): Synthetic DiD combining standard DiD and synthetic control methods for few treated units
 - [TripleDifference](https://diff-diff.readthedocs.io/en/stable/api/triple_diff.html): Triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility
 - [ContinuousDiD](https://diff-diff.readthedocs.io/en/stable/api/continuous_did.html): Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/had.py

@@ -2595,6 +2595,50 @@ class HeterogeneousAdoptionDiD:
 
     Notes
     -----
+    **Non-testable assumptions (paper Section 3.1.2).** Point identification
+    of ``WAS_{d_lower}`` on the Design 1 family
+    (``continuous_near_d_lower`` and ``mass_point``) requires Assumption 6
+    in addition to parallel trends; sign identification requires
+    Assumption 5. Neither is testable via pre-trends:
+
+    - Assumption 5 (sign identification): the boundary slope-ratio
+      ``lim_{d down d_lower} E(TE_2 | D_2 <= d) / WAS < E(D_2) / d_lower``
+      relates the conditional expectation near the boundary to the
+      overall WAS; it cannot be inferred from pre-period outcome
+      trajectories alone.
+    - Assumption 6 (point identification): the counterfactual-mean
+      alignment ``lim_{d down d_lower} E[Y_2(d_lower) - Y_2(0) | D_2 <= d]
+      = E[Y_2(d_lower) - Y_2(0)]`` is a statement about an unobserved
+      counterfactual at the support infimum.
+
+    The fit() method emits a ``UserWarning`` whenever ``resolved_design``
+    is on the Design 1 family (``continuous_near_d_lower`` or
+    ``mass_point``) so users are not silently led to interpret point
+    estimates as full point identification. The available pre-tests
+    verify ADJACENT identifying conditions:
+
+    - :func:`diff_diff.qug_test`: Theorem 4 / Design 1' support-infimum
+      null ``d_lower = 0`` (adjacent evidence on the ``d_lower = 0``
+      clause of Assumption 4 only, NOT a test of the full Assumption 4
+      statement which also covers boundary-density positivity,
+      conditional-mean smoothness, conditional-variance regularity, and
+      bandwidth conditions).
+    - :func:`diff_diff.stute_test` / :func:`diff_diff.yatchew_hr_test`:
+      Assumption 8 linearity of ``E[ΔY | D_2]`` in ``D_2`` (residuals
+      from ``dy ~ 1 + d``).
+    - :func:`diff_diff.joint_pretrends_test`: Assumption 7
+      mean-independence pre-trends across multi-period placebos
+      (intercept-only residual form via ``null_form="mean_independence"``;
+      the raw ``stute_test`` / ``yatchew_hr_test`` helpers do NOT cover
+      Assumption 7 on their own).
+
+    None of these test Assumptions 5 or 6 directly. The Assumption 5/6
+    non-testability caveat is surfaced by the Design 1 fit-time
+    ``UserWarning`` and by T21 (HAD pretest workflow tutorial) prose,
+    NOT by the composite workflow verdict string (which only flags the
+    Assumption 7 step-2 gap on the two-period ``aggregate="overall"``
+    path).
+
     **Diagnostics coverage.** ``HeterogeneousAdoptionDiDResults.bandwidth_diagnostics``
     and ``.bias_corrected_fit`` are populated only on the continuous
     paths; both are ``None`` on the mass-point path (which is parametric
@@ -2831,13 +2875,22 @@ class HeterogeneousAdoptionDiD:
         first_treat_col : str or None
             Optional first-treatment column (the period at which each
             unit first receives treatment; ``0`` for never-treated).
-            Required on the event-study path when the panel has more
-            than two distinct first-treat values (staggered timing):
-            the estimator auto-filters to the last-treatment cohort
-            with a ``UserWarning`` per paper Appendix B.2 prescription.
             For common-adoption panels the column is optional; when
             omitted, the event-study path infers the first-treatment
-            period ``F`` from the dose invariant.
+            period ``F`` from the dose invariant. **Staggered-timing
+            contract (HAD Appendix B.2):**
+
+            - **`first_treat_col` supplied + multiple cohorts detected**:
+              auto-filter to the last-treatment cohort + never-treated
+              units with a ``UserWarning`` naming kept / dropped counts.
+            - **`first_treat_col` omitted + multiple distinct first-
+              positive-dose cohorts inferred from the dose path**: the
+              estimator FAIL-CLOSES with ``ValueError`` directing the
+              user to either pass ``first_treat_col`` (activates the
+              auto-filter) or use :class:`ChaisemartinDHaultfoeuille`
+              (``did_multiplegt_dyn``) for full staggered support. See
+              REGISTRY § "Library extension: Staggered-timing fail-
+              closed" for the rationale on raising vs. warning.
         aggregate : {"overall", "event_study"}
             ``"overall"`` (default): returns a single-period
             :class:`HeterogeneousAdoptionDiDResults` (Phase 2a). Requires
@@ -2847,8 +2900,11 @@ class HeterogeneousAdoptionDiD:
             event-time WAS estimates on the multi-period panel (paper
             Appendix B.2). Requires more than two time periods. Pointwise
             CIs per horizon; joint cross-horizon covariance is deferred
-            to a follow-up PR. Staggered-timing panels are auto-filtered
-            to the last-treatment cohort with a ``UserWarning``.
+            to a follow-up PR. Staggered-timing panels: see the
+            ``first_treat_col`` contract above (auto-filter to last
+            cohort + never-treated with ``UserWarning`` when supplied;
+            fail-closed ``ValueError`` when omitted on a staggered
+            panel).
         survey_design : SurveyDesign or None, keyword-only
             Survey design (sampling weights + optional strata / PSU / FPC)
             for design-based inference. Supported on ALL design × aggregate

{diff_diff-3.4.0 → diff_diff-3.4.2}/diff_diff/had_pretests.py

@@ -1349,6 +1349,22 @@ def qug_test(
 
     Notes
     -----
+    **Scope (what this test does NOT cover).** ``qug_test`` tests the
+    Theorem 4 / Design 1' support-infimum null ``H_0: d_lower = 0``. It
+    does not validate the full Assumption 4 (Assumption 4 also requires
+    positive boundary density, twice-differentiable conditional-mean,
+    bounded continuous conditional-variance, and bandwidth regularity —
+    QUG is adjacent evidence on the ``d_lower = 0`` clause only). It
+    does NOT and CANNOT test Assumptions 5 and 6 from the same paper
+    (Section 3.1.2), which are required for sign identification (A5) and
+    point identification (A6) of ``WAS_{d_lower}`` on the Design 1 family
+    (``d_lower > 0``). Assumptions 5 and 6 are statements about
+    conditional expectations near the support boundary and about
+    counterfactual-mean alignment respectively; they are non-testable via
+    pre-trends. See :class:`HeterogeneousAdoptionDiD` class docstring
+    Notes for the full statement and T21 (HAD pretest workflow tutorial)
+    for the verdict-language convention that surfaces this gap.
+
     Tie-break: when ``D_{(1)} == D_{(2)}`` the statistic is undefined.
     The test returns ``t_stat=NaN, p_value=NaN, reject=False`` with a
     ``UserWarning`` rather than raising.
@@ -1636,6 +1652,23 @@ def stute_test(
 
     Notes
     -----
+    **Scope (what this test does NOT cover).** ``stute_test`` targets
+    paper Assumption 8 (linearity of ``E[ΔY | D_2]`` in ``D_2``) — the
+    raw helper always fits ``dy ~ 1 + d`` and tests the linearity null;
+    it does NOT target Assumption 7 mean-independence pre-trends on its
+    own. For Assumption 7 mean-independence (residuals from intercept-
+    only ``dy ~ 1``), use :func:`joint_pretrends_test` (which routes
+    ``null_form="mean_independence"`` into the joint CvM core). It does
+    NOT and CANNOT test Assumptions 5 and 6 from de Chaisemartin et al.
+    (2026) Section 3.1.2, which are required for sign / point
+    identification of ``WAS_{d_lower}`` on the Design 1 family
+    (``d_lower > 0``). Assumptions 5/6 are non-testable via pre-trends
+    (boundary-conditional expectations and counterfactual-mean alignment
+    statements); they are surfaced by the Design 1 fit-time
+    ``UserWarning`` and by T21 tutorial prose, NOT by the workflow
+    verdict string. See :class:`HeterogeneousAdoptionDiD` class
+    docstring Notes for the full statement.
+
     Sample-size gate: below ``G = 10`` the CvM statistic is not
     well-calibrated. In that case the function emits ``UserWarning`` and
     returns all-NaN inference rather than raising.
@@ -2112,6 +2145,20 @@ def yatchew_hr_test(
 
     Notes
     -----
+    **Scope (what this test does NOT cover).** ``yatchew_hr_test`` targets
+    paper Assumption 8 (linearity of ``E[ΔY | D_2]`` in ``D_2``) under
+    ``null="linearity"`` (default); ``null="mean_independence"`` swaps
+    the residual definition to intercept-only ``dy ~ 1`` for R parity
+    with ``YatchewTest::yatchew_test(order=0)`` on pre-trend placebos.
+    It does NOT and CANNOT test Assumptions 5 and 6 from de
+    Chaisemartin et al. (2026) Section 3.1.2, which are required for
+    sign / point identification of ``WAS_{d_lower}`` on the Design 1
+    family (``d_lower > 0``). Assumptions 5/6 are non-testable via
+    pre-trends; they are surfaced by the Design 1 fit-time
+    ``UserWarning`` and by T21 tutorial prose, NOT by the workflow
+    verdict string. See :class:`HeterogeneousAdoptionDiD` class
+    docstring Notes for the full statement.
+
     Sample-size gate: below ``G = 3`` the difference-variance estimator
     is undefined; the function emits ``UserWarning`` and returns NaN
     rather than raising.
@@ -4548,6 +4595,27 @@ def did_had_pretest_workflow(
 
     Notes
     -----
+    **Scope (what this composite workflow does NOT cover).** The
+    component pretests target the Theorem 4 / Design 1' support-infimum
+    null (QUG: ``d_lower = 0``, adjacent evidence on the ``d_lower = 0``
+    clause of Assumption 4 only — does not validate boundary density,
+    conditional-mean smoothness, or variance regularity), Assumption 7
+    (joint Stute pre-trends: mean-independence of placebo first-
+    differences from dose), and Assumption 8 (Yatchew / joint
+    homogeneity: linearity of treatment effects in dose). The workflow
+    does NOT and CANNOT test Assumptions 5 and 6
+    from de Chaisemartin et al. (2026) Section 3.1.2, which are required
+    for sign / point identification of ``WAS_{d_lower}`` on the Design 1
+    family (``d_lower > 0``). Assumptions 5/6 are non-testable via
+    pre-trends. The composite verdict string does NOT mention
+    Assumptions 5 or 6 — it only flags the Assumption 7 step-2 gap on
+    the two-period ``aggregate="overall"`` path. The Assumption 5/6
+    caveat is surfaced separately by (a) the
+    ``HeterogeneousAdoptionDiD.fit()`` fit-time ``UserWarning`` (which
+    fires whenever the resolved design is Design 1 family —
+    ``continuous_near_d_lower`` or ``mass_point``) and (b) T21 (HAD
+    pretest workflow tutorial) tutorial prose.
+
     Survey/weighted data (Phase 4.5 C): under ``survey=`` or ``weights=``,
     the workflow: