diff-diff 3.4.0__tar.gz → 3.4.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.4.0
+Version: 3.4.1
 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>`)
 - [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.1}/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>`)
 - [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.1}/diff_diff/__init__.py

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

{diff_diff-3.4.0 → diff_diff-3.4.1}/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.1}/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.1
 - Repository: https://github.com/igerber/diff-diff
 - License: MIT
 - Dependencies: numpy, pandas, scipy (no statsmodels dependency)
@@ -335,10 +335,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)
 )
 ```
 

{diff_diff-3.4.0 → diff_diff-3.4.1}/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 (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.1}/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.1}/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: