diff-diff 3.6.1__tar.gz → 3.6.2__tar.gz

{diff_diff-3.6.1 → diff_diff-3.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.6.1
+Version: 3.6.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent

{diff_diff-3.6.1 → diff_diff-3.6.2}/diff_diff/__init__.py

@@ -301,7 +301,7 @@ ETWFE = WooldridgeDiD
 DCDH = ChaisemartinDHaultfoeuille
 HAD = HeterogeneousAdoptionDiD
 
-__version__ = "3.6.1"
+__version__ = "3.6.2"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",

{diff_diff-3.6.1 → diff_diff-3.6.2}/diff_diff/_backend.py

@@ -65,6 +65,14 @@ except ImportError:
     _rust_sc_weight_fw_weighted_with_convergence = None
     _rust_backend_info = None
 
+# FE-absorption MAP demeaning kernel: imported independently so a stale or
+# mixed-version extension missing only this newer symbol degrades to the
+# numpy demeaning engine WITHOUT disabling the older Rust accelerations.
+try:
+    from diff_diff._rust_backend import demean_map as _rust_demean_map
+except ImportError:
+    _rust_demean_map = None
+
 # Determine final backend based on environment variable and availability
 if _backend_env == "python":
     # Force pure Python mode - disable Rust even if available
@@ -73,6 +81,8 @@ if _backend_env == "python":
     _rust_project_simplex = None
     _rust_solve_ols = None
     _rust_compute_robust_vcov = None
+    # FE-absorption MAP demeaning kernel
+    _rust_demean_map = None
     # TROP estimator acceleration (local method)
     _rust_unit_distance_matrix = None
     _rust_loocv_grid_search = None
@@ -124,6 +134,8 @@ __all__ = [
     "_rust_project_simplex",
     "_rust_solve_ols",
     "_rust_compute_robust_vcov",
+    # FE-absorption MAP demeaning kernel
+    "_rust_demean_map",
     # TROP estimator acceleration (local method)
     "_rust_unit_distance_matrix",
     "_rust_loocv_grid_search",

{diff_diff-3.6.1 → diff_diff-3.6.2}/diff_diff/_nprobust_port.py

@@ -1361,6 +1361,19 @@ def lprobust(
     se_cl = float(np.sqrt((deriv_fact**2) * V_Y_cl[deriv, deriv]))
     se_rb = float(np.sqrt((deriv_fact**2) * V_Y_bc[deriv, deriv]))
 
+    # Cluster-robust variance is unidentified when fewer than two clusters
+    # contribute to the ACTIVE kernel window (``eC = cluster[ind]``): the
+    # between-cluster meat is degenerate, so a finite ``se`` here would report
+    # unidentified clustered inference as if identified. NaN both SEs so any
+    # downstream inference (the ``safe_inference`` gate in
+    # ``bias_corrected_local_linear``; HAD's beta-scale rescale) is NaN-coupled.
+    # Unclustered fits (``eC is None``) are unaffected, and a clustered window
+    # with >= 2 distinct clusters is bit-identical, so the DGP-4 golden parity
+    # is preserved.
+    if eC is not None and len(np.unique(eC)) < 2:
+        se_cl = float("nan")
+        se_rb = float("nan")
+
     # --- Per-observation influence function for the BIAS-CORRECTED point
     # estimate at ``deriv`` (Phase 4.5 survey composition).
     # Aligned with ``V_Y_bc`` (NOT ``V_Y_cl``) so survey-composed variance

{diff_diff-3.6.1 → diff_diff-3.6.2}/diff_diff/_reporting_helpers.py

@@ -635,6 +635,26 @@ def describe_target_parameter(results: Any) -> Dict[str, Any]:
             "reference": "REGISTRY.md Sec. SyntheticControl",
         }
 
+    if name == "SpilloverDiDResults":
+        return {
+            "name": "total effect on the treated (Butts spillover-aware ATT)",
+            "definition": (
+                "The total effect on the treated ``tau_total`` from Butts (2021) "
+                "ring-indicator spillover DiD, identified off FAR-AWAY control "
+                "observations (``d_it > d_bar``, Assumption 5) rather than any "
+                "not-yet-/never-treated pool. The estimator decomposes into the "
+                "DIRECT effect on treated units plus per-ring spillover-on-control "
+                "effects that relax SUTVA within the treated units' spatial "
+                "neighborhood; ``att`` is the headline total effect, while the "
+                "per-ring ``spillover_effects`` and (when ``event_study=True``) the "
+                "per-event-time direct dynamics are available on the result object "
+                "for disaggregated inference."
+            ),
+            "aggregation": "spillover",
+            "headline_attribute": "att",
+            "reference": "Butts (2021); REGISTRY.md Sec. SpilloverDiD",
+        }
+
     # 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.6.1 → diff_diff-3.6.2}/diff_diff/bacon.py

@@ -18,6 +18,7 @@ import numpy as np
 import pandas as pd
 
 from diff_diff.results import _format_survey_block
+from diff_diff.utils import pre_demean_norms, snap_absorbed_regressors
 from diff_diff.utils import within_transform as _within_transform_util
 
 
@@ -795,6 +796,7 @@ class BaconDecomposition:
     ) -> float:
         """Compute TWFE estimate using within-transformation."""
         # Apply two-way within transformation (weighted if survey weights provided)
+        _pre_norms = pre_demean_norms(df, [treat_col], weights=weights)
         df_dm = _within_transform_util(
             df,
             [outcome, treat_col],
@@ -803,6 +805,19 @@ class BaconDecomposition:
             suffix="_within",
             weights=weights,
         )
+        # Snap an FE-spanned treatment to exact zero: the d_var == 0 guard
+        # below then returns its deterministic 0.0 (with the cause warning)
+        # instead of an arbitrary junk/junk division.
+        snap_absorbed_regressors(
+            df_dm,
+            [treat_col],
+            _pre_norms,
+            absorbed_desc=f"unit '{unit}' and time '{time}' fixed effects",
+            group_vars=[unit, time],
+            suffix="_within",
+            display_names={treat_col: "treatment"},
+            weights=weights,
+        )
 
         # Extract within-transformed values
         y_within = df_dm[f"{outcome}_within"].values

{diff_diff-3.6.1 → diff_diff-3.6.2}/diff_diff/continuous_did.py

@@ -31,9 +31,9 @@ from diff_diff.continuous_did_results import (
 )
 from diff_diff.linalg import _rank_guarded_inv, solve_ols
 from diff_diff.survey import (
-    ResolvedSurveyDesign,
     _resolve_survey_for_fit,
     _validate_unit_constant_survey,
+    build_unit_first_row_index,
     compute_survey_vcov,
 )
 from diff_diff.utils import safe_inference
@@ -413,8 +413,7 @@ class ContinuousDiD:
 
         # Filter out NaN cells (e.g., from zero effective survey mass)
         gt_results = {
-            gt: r for gt, r in gt_results.items()
-            if np.isfinite(r.get("att_glob", np.nan))
+            gt: r for gt, r in gt_results.items() if np.isfinite(r.get("att_glob", np.nan))
         }
 
         if len(gt_results) == 0:
@@ -573,9 +572,12 @@ class ContinuousDiD:
                 # Survey df for t-distribution inference (unit-level, not panel-level)
                 _survey_df = analytic.get("df_survey")
                 # Guard: replicate design with undefined df → NaN inference
-                if (_survey_df is None and resolved_survey is not None
-                        and hasattr(resolved_survey, 'uses_replicate_variance')
-                        and resolved_survey.uses_replicate_variance):
+                if (
+                    _survey_df is None
+                    and resolved_survey is not None
+                    and hasattr(resolved_survey, "uses_replicate_variance")
+                    and resolved_survey.uses_replicate_variance
+                ):
                     _survey_df = 0
 
                 # Recompute survey_metadata from unit-level design so reported
@@ -589,8 +591,7 @@ class ContinuousDiD:
 
                 # Propagate replicate df override to survey_metadata for display
                 # (but not the df=0 sentinel — keep metadata as None for undefined df)
-                if (_survey_df is not None and _survey_df != 0
-                        and survey_metadata is not None):
+                if _survey_df is not None and _survey_df != 0 and survey_metadata is not None:
                     if survey_metadata.df_survey != _survey_df:
                         survey_metadata.df_survey = _survey_df
 
@@ -624,30 +625,8 @@ class ContinuousDiD:
                     unit_resolved_es = None
                     if resolved_survey is not None:
                         row_idx = precomp["unit_first_panel_row"]
-                        uw = (
-                            precomp.get("unit_survey_weights")
-                            if precomp.get("unit_survey_weights") is not None
-                            else np.ones(n_units)
-                        )
-                        us = (
-                            resolved_survey.strata[row_idx]
-                            if resolved_survey.strata is not None
-                            else None
-                        )
-                        up = (
-                            resolved_survey.psu[row_idx]
-                            if resolved_survey.psu is not None
-                            else None
-                        )
-                        uf = (
-                            resolved_survey.fpc[row_idx]
-                            if resolved_survey.fpc is not None
-                            else None
-                        )
-                        n_strata_u = len(np.unique(us)) if us is not None else 0
-                        n_psu_u = len(np.unique(up)) if up is not None else 0
-                        unit_resolved_es = resolved_survey.subset_to_units(
-                            row_idx, uw, us, up, uf, n_strata_u, n_psu_u,
+                        unit_resolved_es = resolved_survey.subset_to_units_by_row_idx(
+                            row_idx, unit_weights=precomp.get("unit_survey_weights")
                         )
 
                     for e_val, info_e in event_study_effects.items():
@@ -711,13 +690,21 @@ class ContinuousDiD:
 
                                 # Score-scale: psi = w * if_es (matches TSL bread)
                                 psi_es = unit_resolved_es.weights * if_es
-                                variance, _nv = compute_replicate_if_variance(psi_es, unit_resolved_es)
-                                es_se = float(np.sqrt(max(variance, 0.0))) if np.isfinite(variance) else np.nan
+                                variance, _nv = compute_replicate_if_variance(
+                                    psi_es, unit_resolved_es
+                                )
+                                es_se = (
+                                    float(np.sqrt(max(variance, 0.0)))
+                                    if np.isfinite(variance)
+                                    else np.nan
+                                )
                             else:
                                 X_ones_es = np.ones((n_units, 1))
                                 tsl_scale_es = float(unit_resolved_es.weights.sum())
                                 if_es_tsl = if_es * tsl_scale_es
-                                vcov_es = compute_survey_vcov(X_ones_es, if_es_tsl, unit_resolved_es)
+                                vcov_es = compute_survey_vcov(
+                                    X_ones_es, if_es_tsl, unit_resolved_es
+                                )
                                 es_se = float(np.sqrt(np.abs(vcov_es[0, 0])))
                         else:
                             es_se = float(np.sqrt(np.sum(if_es**2)))
@@ -831,15 +818,11 @@ class ContinuousDiD:
             unit_cohorts[i] = unit_first.loc[u, first_treat]
             dose_vector[i] = unit_first.loc[u, dose]
 
-        # Build unit-to-first-panel-row mapping (for subsetting panel-level arrays)
-        # This maps each unit index to the positional index of its first row in df.
-        unit_first_panel_row = np.zeros(n_units, dtype=int)
-        seen_units: set = set()
-        for pos_idx, (_, row) in enumerate(df.iterrows()):
-            u = row[unit]
-            if u not in seen_units:
-                seen_units.add(u)
-                unit_first_panel_row[unit_to_idx[u]] = pos_idx
+        # Build unit-to-first-panel-row mapping (for subsetting panel-level
+        # arrays): the positional index of each unit's first row in df, aligned
+        # to ``all_units`` (== ``unit_to_idx`` order since
+        # ``unit_to_idx = {u: i for i, u in enumerate(all_units)}``).
+        unit_first_panel_row = build_unit_first_row_index(df[unit].values, all_units)
 
         # Per-unit survey weights (take first obs per unit from panel data)
         unit_survey_weights = None
@@ -949,8 +932,10 @@ class ContinuousDiD:
             # Guard against zero effective mass (e.g., after subpopulation)
             if np.sum(w_treated) <= 0 or np.sum(w_control) <= 0:
                 return {
-                    "att_glob": np.nan, "acrt_glob": np.nan,
-                    "n_treated": 0, "n_control": 0,
+                    "att_glob": np.nan,
+                    "acrt_glob": np.nan,
+                    "n_treated": 0,
+                    "n_control": 0,
                     "att_d": np.full(len(dvals), np.nan),
                     "acrt_d": np.full(len(dvals), np.nan),
                 }
@@ -1293,23 +1278,8 @@ class ContinuousDiD:
             # but influence functions are unit-level (n_units). Build a unit-level
             # ResolvedSurveyDesign by subsetting to one obs per unit.
             row_idx = precomp["unit_first_panel_row"]
-            unit_weights = precomp.get("unit_survey_weights")
-            if unit_weights is None:
-                unit_weights = np.ones(n_units)
-
-            unit_strata = (
-                resolved_survey.strata[row_idx] if resolved_survey.strata is not None else None
-            )
-            unit_psu = resolved_survey.psu[row_idx] if resolved_survey.psu is not None else None
-            unit_fpc = resolved_survey.fpc[row_idx] if resolved_survey.fpc is not None else None
-
-            # Count unique strata/PSU in the unit-level subset
-            n_strata_unit = len(np.unique(unit_strata)) if unit_strata is not None else 0
-            n_psu_unit = len(np.unique(unit_psu)) if unit_psu is not None else 0
-
-            unit_resolved = resolved_survey.subset_to_units(
-                row_idx, unit_weights, unit_strata, unit_psu, unit_fpc,
-                n_strata_unit, n_psu_unit,
+            unit_resolved = resolved_survey.subset_to_units_by_row_idx(
+                row_idx, unit_weights=precomp.get("unit_survey_weights")
             )
 
             X_ones = np.ones((n_units, 1))
@@ -1370,7 +1340,11 @@ class ContinuousDiD:
 
         # Return unit-level survey df and resolved design for metadata recomputation
         # Only override with n_valid-based df when replicates were actually dropped
-        if resolved_survey is not None and hasattr(resolved_survey, 'uses_replicate_variance') and resolved_survey.uses_replicate_variance:
+        if (
+            resolved_survey is not None
+            and hasattr(resolved_survey, "uses_replicate_variance")
+            and resolved_survey.uses_replicate_variance
+        ):
             if _rep_n_valid < unit_resolved.n_replicates:
                 unit_df_survey = _rep_n_valid - 1 if _rep_n_valid > 1 else None
             else:
@@ -1415,7 +1389,11 @@ class ContinuousDiD:
 
         # Reject replicate-weight designs for bootstrap — replicate variance
         # is an analytical alternative to bootstrap, not compatible with it
-        if resolved_survey is not None and hasattr(resolved_survey, "uses_replicate_variance") and resolved_survey.uses_replicate_variance:
+        if (
+            resolved_survey is not None
+            and hasattr(resolved_survey, "uses_replicate_variance")
+            and resolved_survey.uses_replicate_variance
+        ):
             raise NotImplementedError(
                 "ContinuousDiD bootstrap (n_bootstrap > 0) is not supported "
                 "with replicate-weight survey designs. Replicate weights provide "
@@ -1429,22 +1407,9 @@ class ContinuousDiD:
         # Build unit-level ResolvedSurveyDesign for survey-aware bootstrap
         unit_resolved = None
         if resolved_survey is not None:
-            from diff_diff.survey import ResolvedSurveyDesign
-
             row_idx = precomp["unit_first_panel_row"]
-            unit_weights = precomp.get("unit_survey_weights")
-            if unit_weights is None:
-                unit_weights = np.ones(n_units)
-            unit_strata = (
-                resolved_survey.strata[row_idx] if resolved_survey.strata is not None else None
-            )
-            unit_psu = resolved_survey.psu[row_idx] if resolved_survey.psu is not None else None
-            unit_fpc = resolved_survey.fpc[row_idx] if resolved_survey.fpc is not None else None
-            n_strata_u = len(np.unique(unit_strata)) if unit_strata is not None else 0
-            n_psu_u = len(np.unique(unit_psu)) if unit_psu is not None else 0
-            unit_resolved = resolved_survey.subset_to_units(
-                row_idx, unit_weights, unit_strata, unit_psu, unit_fpc,
-                n_strata_u, n_psu_u,
+            unit_resolved = resolved_survey.subset_to_units_by_row_idx(
+                row_idx, unit_weights=precomp.get("unit_survey_weights")
             )
 
         # Generate bootstrap weights — PSU-level when survey design is present
@@ -1682,7 +1647,7 @@ class ContinuousDiD:
                     boot_es[e],
                     alpha=self.alpha,
                     context=f"event study e={e}",
-                    )
+                )
                 es_se[e] = se_e
                 es_ci[e] = ci_e
                 es_p[e] = p_e

{diff_diff-3.6.1 → diff_diff-3.6.2}/diff_diff/diagnostic_report.py

@@ -65,8 +65,8 @@ _CHECK_NAMES: Tuple[str, ...] = (
     "placebo",
 )
 
-# Type-level applicability: which checks are *ever* applicable for each of the
-# 16 result types. Instance-level applicability further filters by whether
+# Type-level applicability: which checks are *ever* applicable for each
+# registered result type. Instance-level applicability further filters by whether
 # required attributes are present (e.g. ``survey_metadata`` for DEFF) and by
 # whether the user disabled a check via ``run_*=False``.
 # See ``docs/methodology/REPORTING.md`` for the full matrix and rationale.
@@ -74,7 +74,7 @@ _CHECK_NAMES: Tuple[str, ...] = (
 # Implementation note: The keys are result-class names looked up via
 # ``type(results).__name__``. This string-based dispatch mirrors the
 # ``_HANDLERS`` pattern in ``diff_diff/practitioner.py`` and avoids circular
-# imports across the 16 result modules. Renaming or aliasing any result class
+# imports across the result modules. Renaming or aliasing any result class
 # requires updating both this table and ``_PT_METHOD`` below; the
 # applicability-matrix test parametrized over all result types serves as the
 # regression guard.
@@ -131,6 +131,27 @@ _APPLICABILITY: Dict[str, FrozenSet[str]] = {
             "heterogeneity",
         }
     ),
+    "SpilloverDiDResults": frozenset(
+        # Butts (2021) ring-indicator spillover DiD is a two-stage-GMM
+        # estimator, so it inherits TwoStage's diagnostic set MINUS
+        # ``bacon``. ``bacon`` is excluded because SpilloverDiD identifies
+        # the direct effect off FAR-AWAY units (Butts Assumption 5), not
+        # off the TWFE 2x2 comparisons a Goodman-Bacon decomposition
+        # enumerates: ``bacon_decompose`` on the raw binary treatment
+        # ignores the ring/distance structure and would pool spillover-
+        # contaminated in-ring units into the control group — the exact
+        # SUTVA violation the estimator exists to handle (same rationale
+        # that excludes bacon for SyntheticControl / TROP / Continuous).
+        # ``parallel_trends`` routes to ``event_study`` on the per-event-
+        # time DIRECT-effect dynamics (populated when ``event_study=True``);
+        # ``design_effect`` is instance-gated on ``survey_metadata`` (Wave
+        # E.1); ``heterogeneity`` reads ``event_study_effects``.
+        {
+            "parallel_trends",
+            "design_effect",
+            "heterogeneity",
+        }
+    ),
     "StackedDiDResults": frozenset(
         {
             "parallel_trends",
@@ -218,6 +239,7 @@ _PT_METHOD: Dict[str, str] = {
     "SunAbrahamResults": "event_study",
     "ImputationDiDResults": "event_study",
     "TwoStageDiDResults": "event_study",
+    "SpilloverDiDResults": "event_study",
     "StackedDiDResults": "event_study",
     "EfficientDiDResults": "hausman",
     "ContinuousDiDResults": "event_study",
@@ -263,7 +285,7 @@ class DiagnosticReport:
     ----------
     results : Any
         A fitted diff-diff results object (e.g. ``CallawaySantAnnaResults``,
-        ``DiDResults``, ``SyntheticDiDResults``). Any of the 16 result types
+        ``DiDResults``, ``SyntheticDiDResults``). Any registered result type
         in the library is accepted.
     data : pandas.DataFrame, optional
         The underlying panel. Required for checks that need raw data
@@ -703,6 +725,19 @@ class DiagnosticReport:
                 # summary emits the "inconclusive" identifying-
                 # assumption warning rather than silently dropping PT.
                 if not pre_coefs and n_dropped_undefined == 0:
+                    # SpilloverDiD's event-study switch is the
+                    # ``SpilloverDiD(..., event_study=True)`` constructor
+                    # kwarg, not the ``aggregate='event_study'`` argument
+                    # the generic staggered-estimator message points at
+                    # (SpilloverDiD has no ``aggregate`` kwarg). Emit an
+                    # estimator-accurate remediation for this family.
+                    if name == "SpilloverDiDResults":
+                        return (
+                            "No pre-period event-study coefficients are exposed "
+                            "on this fit. Re-fit with "
+                            "SpilloverDiD(..., event_study=True) to populate the "
+                            "per-event-time direct-effect output."
+                        )
                     return (
                         "No pre-period event-study coefficients are exposed on "
                         "this fit. For staggered estimators, re-fit with "
@@ -2287,6 +2322,7 @@ class DiagnosticReport:
                 "rmspe_ratio": _to_python_float(getattr(r, "rmspe_ratio", None)),
                 "n_placebos": _to_python_scalar(n_placebos),
                 "n_failed": _to_python_scalar(getattr(r, "n_failed", None)),
+                "n_infeasible": _to_python_scalar(getattr(r, "n_infeasible", None)),
             }
             # Distinguish a valid run from an attempted-but-infeasible one so BR/DR
             # consumers see an explicit status/reason rather than a bare NaN p-value.
@@ -2312,15 +2348,35 @@ class DiagnosticReport:
                     "all_placebos_failed": (
                         "in_space_placebo() was run but every donor refit failed to "
                         "converge, so no placebo entered the reference set; "
-                        "placebo_p_value is NaN."
+                        "placebo_p_value is NaN. Raise n_starts or loosen the "
+                        "optimizer tolerances."
+                    ),
+                    "all_placebos_infeasible": (
+                        "in_space_placebo() was run but every donor refit was "
+                        "structurally infeasible under v_method='cv' (the "
+                        "pseudo-treated donor pool is indistinguishable in a "
+                        "re-aggregated CV window), so no placebo entered the reference "
+                        "set; placebo_p_value is NaN. Adjust the predictors, v_cv_t0, "
+                        "or the donor pool."
+                    ),
+                    "all_placebos_unusable": (
+                        "in_space_placebo() was run but no donor refit was usable: "
+                        "some failed to converge AND some were structurally infeasible "
+                        "(see n_failed / n_infeasible); placebo_p_value is NaN."
                     ),
                 }
                 block["status"] = "infeasible"
+                # Machine-readable code distinguishing a solver convergence failure
+                # ("all_placebos_failed") from structural infeasibility
+                # ("all_placebos_infeasible" / "too_few_donors") or a mix
+                # ("all_placebos_unusable"), without parsing `reason`.
+                block["reason_code"] = placebo_status
                 block["reason"] = _reasons.get(
                     placebo_status,
                     "in_space_placebo() was run but produced no valid reference set "
                     "(fewer than 2 donors, a non-converged treated fit, or all donor "
-                    "refits failed); placebo_p_value is NaN.",
+                    "refits failed / were structurally infeasible); placebo_p_value is "
+                    "NaN.",
                 )
             out["in_space_placebo"] = block
         else:
@@ -2353,6 +2409,7 @@ class DiagnosticReport:
                         else None
                     ),
                     "n_failed": _to_python_scalar(getattr(r, "_loo_n_failed", None)),
+                    "n_infeasible": _to_python_scalar(getattr(r, "_loo_n_infeasible", None)),
                 }
             else:
                 _loo_reasons = {
@@ -2371,13 +2428,29 @@ class DiagnosticReport:
                         "(see the status='failed' rows); raise n_starts or loosen the "
                         "optimizer tolerances."
                     ),
+                    "all_refits_infeasible": (
+                        "leave_one_out() was run but every donor-drop refit was "
+                        "structurally infeasible under v_method='cv' (the reduced donor "
+                        "pool is indistinguishable in a re-aggregated CV window; see the "
+                        "status='infeasible' rows); adjust the predictors, v_cv_t0, or "
+                        "the donor pool."
+                    ),
+                    "all_refits_unusable": (
+                        "leave_one_out() was run but no donor-drop refit was usable: "
+                        "some failed to converge AND some were structurally infeasible "
+                        "(see n_failed / n_infeasible)."
+                    ),
                 }
                 out["leave_one_out"] = {
                     "status": "infeasible",
                     # Machine-readable code so consumers can distinguish a numerical
                     # convergence failure ("all_refits_failed") from structural
-                    # infeasibility ("too_few_donors") without parsing `reason`.
+                    # infeasibility ("all_refits_infeasible" / "too_few_donors") or a
+                    # mix ("all_refits_unusable") without parsing `reason`. The n_failed
+                    # / n_infeasible counts give the exact breakdown.
                     "reason_code": loo_status,
+                    "n_failed": _to_python_scalar(getattr(r, "_loo_n_failed", None)),
+                    "n_infeasible": _to_python_scalar(getattr(r, "_loo_n_infeasible", None)),
                     "reason": _loo_reasons.get(
                         loo_status, "leave_one_out() produced no valid refits."
                     ),
@@ -2459,6 +2532,107 @@ class DiagnosticReport:
                 ),
             }
 
+        # Regression-weight extrapolation diagnostic (ADH 2015 §4): opt-in, surfaced once
+        # the user has run results.regression_weights() (pure linear algebra — no refits).
+        if getattr(r, "_regw_df", None) is not None:
+            regw_status = getattr(r, "_regw_status", None)
+            if regw_status == "ran":
+                out["regression_weights"] = {
+                    "status": "ran",
+                    # Headline: how many donors an OLS/regression counterfactual would push
+                    # outside [0,1] (extrapolate). The SC simplex never does.
+                    "n_extrapolating": _to_python_scalar(getattr(r, "_regw_n_extrapolating", None)),
+                    # True if W^reg is a non-unique min-norm solution (not full row rank);
+                    # weight_sum then need not equal 1.
+                    "rank_deficient": bool(getattr(r, "_regw_rank_deficient", False)),
+                    "weight_sum": _to_python_float(getattr(r, "_regw_weight_sum", None)),
+                }
+            else:
+                _regw_reasons = {
+                    "treated_fit_nonconverged": (
+                        "regression_weights() was run but the treated unit's own SCM fit "
+                        "did not converge at fit time, so the synthetic control it is "
+                        "compared against is not a valid optimum."
+                    ),
+                    "too_few_donors": (
+                        "regression_weights() was run but fewer than 2 donors are available "
+                        "(W^reg is trivially [1] with a single donor)."
+                    ),
+                }
+                out["regression_weights"] = {
+                    "status": "infeasible",
+                    "reason_code": regw_status,
+                    "reason": _regw_reasons.get(
+                        regw_status, "regression_weights() produced no table."
+                    ),
+                }
+        else:
+            out["regression_weights"] = {
+                "status": "not_run",
+                "reason": (
+                    "Call results.regression_weights() to flag donors an OLS/regression "
+                    "counterfactual would weight outside [0,1] (ADH 2015 §4 extrapolation "
+                    "diagnostic; opt-in, no refit)."
+                ),
+            }
+
+        # Sparse-SC subset search (ADH 2015 §4): opt-in, surfaced once the user has run
+        # results.sparse_synthetic_control() (exhaustive subset search, V held fixed).
+        if getattr(r, "_sparse_df", None) is not None:
+            sparse_status = getattr(r, "_sparse_status", None)
+            if sparse_status == "ran":
+                # Compact per-size summary: how far the ATT / fit move as the synthetic is
+                # forced sparse (the baseline row is dropped — it is the full-fit reference).
+                records = r._sparse_df.to_dict("records")
+                per_size = [
+                    {
+                        "size": _to_python_scalar(rec["size"]),
+                        "att": _to_python_float(rec["att"]),
+                        "delta_att": _to_python_float(rec["delta_att"]),
+                        "pre_rmspe": _to_python_float(rec["pre_rmspe"]),
+                        "n_failed": _to_python_scalar(rec["n_failed"]),
+                        "status": rec["status"],
+                    }
+                    for rec in records
+                    if rec["status"] != "baseline"
+                ]
+                out["sparse_synthetic_control"] = {
+                    "status": "ran",
+                    # Headline: the largest baseline-relative ATT swing across searched sizes.
+                    "max_abs_delta_att": _to_python_float(
+                        getattr(r, "_sparse_max_abs_delta_att", None)
+                    ),
+                    "sizes": per_size,
+                }
+            else:
+                _sparse_reasons = {
+                    "treated_fit_nonconverged": (
+                        "sparse_synthetic_control() was run but the treated unit's own SCM "
+                        "fit did not converge at fit time, so the baseline ATT is not a "
+                        "valid reference for the sparse deltas."
+                    ),
+                    "too_few_donors": (
+                        "sparse_synthetic_control() was run but fewer than 2 donors are "
+                        "available (a sparse subset must be smaller than the pool)."
+                    ),
+                }
+                out["sparse_synthetic_control"] = {
+                    "status": "infeasible",
+                    "reason_code": sparse_status,
+                    "reason": _sparse_reasons.get(
+                        sparse_status, "sparse_synthetic_control() produced no valid subsets."
+                    ),
+                }
+        else:
+            out["sparse_synthetic_control"] = {
+                "status": "not_run",
+                "reason": (
+                    "Call results.sparse_synthetic_control() to test how the fit / ATT "
+                    "degrade when the synthetic is forced to a few donors (ADH 2015 §4 "
+                    "sparse subset search; opt-in, V held fixed)."
+                ),
+            }
+
         # Test-inversion confidence set (Firpo & Possebom 2018 §4): opt-in, surfaced once
         # the user has run results.confidence_set() (it reuses the in-space placebo
         # reference set — no refits). The analytical conf_int stays NaN; this is a SEPARATE