diff-diff 3.4.2__tar.gz → 3.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.4.2
+Version: 3.5.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -161,6 +161,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [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; 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
+- [SyntheticControl](https://diff-diff.readthedocs.io/en/stable/api/synthetic_control.html) - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/custom V; in-space placebo permutation inference via `in_space_placebo()`)
 - [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
 - [HeterogeneousAdoptionDiD](https://diff-diff.readthedocs.io/en/stable/api/had.html) - de Chaisemartin, Ciccia, D'Haultfœuille & Knau (2026) for designs where **no unit remains untreated**; local-linear estimator at the dose support boundary returning Weighted Average Slope (WAS) on Design 1' (`d̲ = 0` / QUG) or `WAS_{d̲}` on Design 1 (`d̲ > 0`, continuous-near-d̲ or mass-point), with a multi-period event-study extension (last-treatment cohort, pointwise CIs). **Panel-only** in this release - repeated cross-sections rejected by the validator. Alias `HAD`.

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

@@ -108,6 +108,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [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; 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
+- [SyntheticControl](https://diff-diff.readthedocs.io/en/stable/api/synthetic_control.html) - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/custom V; in-space placebo permutation inference via `in_space_placebo()`)
 - [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
 - [HeterogeneousAdoptionDiD](https://diff-diff.readthedocs.io/en/stable/api/had.html) - de Chaisemartin, Ciccia, D'Haultfœuille & Knau (2026) for designs where **no unit remains untreated**; local-linear estimator at the dose support boundary returning Weighted Average Slope (WAS) on Design 1' (`d̲ = 0` / QUG) or `WAS_{d̲}` on Design 1 (`d̲ > 0`, continuous-near-d̲ or mass-point), with a multi-period event-study extension (last-treatment cohort, pointwise CIs). **Panel-only** in this release - repeated cross-sections rejected by the validator. Alias `HAD`.

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

@@ -222,6 +222,11 @@ from diff_diff.trop import (
     TROPResults,
     trop,
 )
+from diff_diff.synthetic_control import (
+    SyntheticControl,
+    synthetic_control,
+)
+from diff_diff.synthetic_control_results import SyntheticControlResults
 from diff_diff.wooldridge import WooldridgeDiD
 from diff_diff.wooldridge_results import WooldridgeDiDResults
 from diff_diff.utils import (
@@ -293,7 +298,7 @@ ETWFE = WooldridgeDiD
 DCDH = ChaisemartinDHaultfoeuille
 HAD = HeterogeneousAdoptionDiD
 
-__version__ = "3.4.2"
+__version__ = "3.5.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -309,6 +314,7 @@ __all__ = [
     "SpilloverDiD",
     "TripleDifference",
     "TROP",
+    "SyntheticControl",
     "StackedDiD",
     # Estimator aliases (short names)
     "DiD",
@@ -355,6 +361,8 @@ __all__ = [
     "StaggeredTripleDiffResults",
     "TROPResults",
     "trop",
+    "SyntheticControlResults",
+    "synthetic_control",
     "StackedDiDResults",
     "stacked_did",
     # EfficientDiD

{diff_diff-3.4.2 → diff_diff-3.5.0}/diff_diff/_reporting_helpers.py

@@ -618,6 +618,23 @@ def describe_target_parameter(results: Any) -> Dict[str, Any]:
             "reference": "REGISTRY.md Sec. TROP",
         }
 
+    if name == "SyntheticControlResults":
+        return {
+            "name": "SCM ATT (mean post-treatment gap for the single treated unit)",
+            "definition": (
+                "The average over the post-treatment periods of the gap "
+                "``alpha_hat_{1t} = Y_{1t} - sum_j w_j Y_{jt}`` between the single "
+                "treated unit and its donor-weighted synthetic control (Abadie, "
+                "Diamond & Hainmueller 2010). There is no population-averaging or "
+                "sampling estimand — it is the effect on the one treated unit; "
+                "significance is assessed by in-space placebo permutation inference "
+                "(no analytical standard error)."
+            ),
+            "aggregation": "single_unit_gap",
+            "headline_attribute": "att",
+            "reference": "REGISTRY.md Sec. SyntheticControl",
+        }
+
     # Default: unrecognized result class. Fall through with a neutral
     # block — agents / downstream consumers can still dispatch on
     # ``aggregation="unknown"`` and fall back to generic ATT narration.

{diff_diff-3.4.2 → diff_diff-3.5.0}/diff_diff/business_report.py

@@ -203,6 +203,7 @@ class BusinessReport:
         if honest_did_results is not None and type(results).__name__ in {
             "SyntheticDiDResults",
             "TROPResults",
+            "SyntheticControlResults",
         }:
             raise ValueError(
                 f"{type(results).__name__} routes robustness to "
@@ -213,8 +214,9 @@ class BusinessReport:
                 "object's native diagnostics "
                 "(SDiD: ``in_time_placebo()``, ``sensitivity_to_zeta_omega()``, "
                 "``pre_treatment_fit``; TROP: ``effective_rank``, "
-                "``loocv_score``) — BusinessReport surfaces these "
-                "automatically under ``estimator_native_diagnostics``."
+                "``loocv_score``; SyntheticControl: ``in_space_placebo()``, "
+                "``pre_rmspe``, ``get_placebo_df()``) — BusinessReport surfaces "
+                "these automatically under ``estimator_native_diagnostics``."
             )
 
         # Round-44 P1 CI review on PR #318: mirror the SDiD/TROP
@@ -646,10 +648,13 @@ class BusinessReport:
         if att is None or not np.isfinite(att):
             sign = "undefined"
         ci_level = int(round((1.0 - display_alpha) * 100))
-        is_significant = (
+        # bool(...) coerces away numpy bool_ — when ``p`` is a numpy NaN (e.g.
+        # SyntheticControl, whose analytical p_value is always NaN), ``np.isfinite``
+        # yields a numpy bool that is NOT JSON-serializable in the schema.
+        is_significant = bool(
             p is not None and np.isfinite(p) and p < phrasing_alpha if p is not None else False
         )
-        near_threshold = (
+        near_threshold = bool(
             p is not None
             and np.isfinite(p)
             and (phrasing_alpha - 0.01) < p < (phrasing_alpha + 0.001)
@@ -1002,16 +1007,25 @@ def _lift_robustness(dr: Optional[Dict[str, Any]]) -> Dict[str, Any]:
         return {"status": "skipped", "reason": "auto_diagnostics=False"}
     bacon = dr.get("bacon") or {}
     native = dr.get("estimator_native_diagnostics") or {}
+    native_block = {
+        "status": native.get("status"),
+        "estimator": native.get("estimator"),
+        "pre_treatment_fit": native.get("pre_treatment_fit"),
+    }
+    # Classic SCM exposes pre_rmspe + donor-weight concentration + the (opt-in)
+    # in-space placebo rather than SDiD's pre_treatment_fit; surface those so the
+    # top-level robustness block is not empty for SyntheticControl.
+    if native.get("estimator") == "SyntheticControl":
+        native_block["pre_rmspe"] = native.get("pre_rmspe")
+        native_block["weight_concentration"] = native.get("weight_concentration")
+        native_block["in_space_placebo"] = native.get("in_space_placebo")
     return {
         "bacon": {
             "status": bacon.get("status"),
             "forbidden_weight": bacon.get("forbidden_weight"),
             "verdict": bacon.get("verdict"),
         },
-        "estimator_native": {
-            "status": native.get("status"),
-            "pre_treatment_fit": native.get("pre_treatment_fit"),
-        },
+        "estimator_native": native_block,
     }
 
 
@@ -1153,6 +1167,20 @@ def _describe_assumption(estimator_name: str, results: Any = None) -> Dict[str,
                 "captured through latent factor loadings."
             ),
         }
+    if estimator_name in {"SyntheticControlResults"}:
+        return {
+            # Distinct from SDiD's "synthetic_fit" weighted-PT analogue: classic
+            # SCM is a donor-weighted level match (matches the DR "scm_fit" method).
+            "parallel_trends_variant": "scm_fit",
+            "no_anticipation": True,
+            "description": (
+                "Classic synthetic control identifies the single treated unit's "
+                "counterfactual via a donor-weighted match to its pre-treatment "
+                "trajectory (a design-enforced fit, not a parallel-trends test); "
+                "significance comes from in-space placebo permutation inference "
+                "rather than an analytical standard error."
+            ),
+        }
     if estimator_name == "ContinuousDiDResults":
         # Callaway, Goodman-Bacon & Sant'Anna (2024), two-level PT:
         # REGISTRY.md §ContinuousDiD > Identification.
@@ -1780,6 +1808,8 @@ def _pt_method_subject(method: Optional[str]) -> str:
         return "Pre-treatment event-study coefficients"
     if method == "synthetic_fit":
         return "The synthetic-control pre-treatment fit"
+    if method == "scm_fit":
+        return "The synthetic-control donor-weighted pre-treatment fit"
     if method == "factor":
         return "The factor-model pre-treatment fit"
     return "Pre-treatment data"
@@ -1806,7 +1836,9 @@ def _pt_method_stat_label(method: Optional[str]) -> Optional[str]:
         return "joint p"
     if method in {"slope_difference", "hausman"}:
         return "p"
-    if method in {"synthetic_fit", "factor"}:
+    if method in {"synthetic_fit", "scm_fit", "factor"}:
+        # Design-enforced fit-based paths have no p-value label (SCM's significance
+        # is the in-space placebo, not a PT joint test).
         return None
     return "joint p"
 
@@ -1846,6 +1878,13 @@ def _references_for(estimator_name: str) -> List[Dict[str, str]]:
                 "& Wager, S. (2021). Synthetic Difference in Differences."
             ),
         },
+        "SyntheticControlResults": {
+            "role": "estimator",
+            "citation": (
+                "Abadie, A., Diamond, A., & Hainmueller, J. (2010). Synthetic "
+                "Control Methods for Comparative Case Studies. JASA, 105(490)."
+            ),
+        },
         "SunAbrahamResults": {
             "role": "estimator",
             "citation": (
@@ -2181,11 +2220,20 @@ def _render_summary(schema: Dict[str, Any]) -> str:
                     "assumption." + sens_tail_see_reliable
                 )
         elif verdict == "design_enforced_pt":
-            sentences.append(
-                "The synthetic control is designed to match the treated "
-                "group's pre-period trajectory (SDiD's weighted-parallel-"
-                "trends analogue)."
-            )
+            if method == "scm_fit":
+                sentences.append(
+                    "The synthetic control is designed to reproduce the treated "
+                    "unit's pre-period trajectory via donor weights (classic SCM's "
+                    "design-enforced analogue of parallel trends); significance "
+                    "comes from in-space placebo permutation inference, not a "
+                    "parallel-trends test."
+                )
+            else:
+                sentences.append(
+                    "The synthetic control is designed to match the treated "
+                    "group's pre-period trajectory (SDiD's weighted-parallel-"
+                    "trends analogue)."
+                )
         elif verdict == "inconclusive":
             # Round-35 P1 CI review on PR #318: a ``verdict=="inconclusive"``
             # state means one or more pre-period coefficients had

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

@@ -212,7 +212,7 @@ def _validate_conley_estimator_inputs(
 ) -> None:
     """Shared front-door validation for ``vcov_type='conley'`` on the
     estimator entry points (``DifferenceInDifferences``, ``MultiPeriodDiD``,
-    ``TwoWayFixedEffects``).
+    ``TwoWayFixedEffects``, ``SunAbraham``, and ``WooldridgeDiD``-OLS).
 
     Each estimator's ``fit()`` calls this BEFORE building Conley arrays or
     threading them into the variance computation. The eight checks below
@@ -296,10 +296,14 @@ def _validate_conley_estimator_inputs(
         raise ValueError(f"Cluster column '{cluster}' not found in data")
     if survey_design is not None:
         raise NotImplementedError(
-            f"{estimator_name}(vcov_type='conley') + survey_design is a "
-            "follow-up (Bertanha-Imbens 2014 weighted-Conley). Drop "
-            "survey_design for cross-sectional Conley, or use vcov_type='hc1' "
-            "for survey-aware cluster-robust without spatial HAC."
+            f"{estimator_name}(vcov_type='conley') + survey_design is "
+            "deferred — weighted spatial-HAC under probability sampling "
+            "is an open methodological question; no canonical extension "
+            "of Conley (1999) exists for the combination. Drop "
+            "survey_design for unweighted Conley (cross-sectional or panel "
+            "block-decomposed via conley_lag_cutoff > 0), or use "
+            "vcov_type='hc1' for survey-aware cluster-robust without "
+            "spatial HAC."
         )
     if inference == "wild_bootstrap":
         raise NotImplementedError(