diff-diff 3.9.0__tar.gz → 3.9.1__tar.gz

{diff_diff-3.9.0 → diff_diff-3.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.9.0
+Version: 3.9.1
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -21,7 +21,7 @@ Requires-Dist: pytest>=7.0 ; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.0 ; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
 Requires-Dist: black==26.5.1 ; extra == 'dev'
-Requires-Dist: ruff==0.16.0 ; extra == 'dev'
+Requires-Dist: ruff==0.16.2 ; extra == 'dev'
 Requires-Dist: mypy==2.3.0 ; extra == 'dev'
 Requires-Dist: maturin>=1.4,<2.0 ; extra == 'dev'
 Requires-Dist: matplotlib>=3.5 ; extra == 'dev'
@@ -180,6 +180,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 ## Diagnostics & Sensitivity
 
 - [RD Plots](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Calonico, Cattaneo & Titiunik (2015) optimal data-driven RD plots (`RDPlot`): all 8 rdrobust `binselect` bin selectors, implied-scale/WIMSE-weight reporting, optional matplotlib rendering
+- [Manipulation Testing](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Cattaneo, Jansson & Ma (2020) density-discontinuity test (`RDDensityTest`): rddensity 3.0 parity, robust bias-corrected inference, unrestricted/restricted models, mass-point adjustment
 - [Parallel Trends Testing](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html) - simple and Wasserstein-robust parallel trends tests, equivalence testing (TOST)
 - [Placebo Tests](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html) - placebo timing, group, permutation, leave-one-out
 - [Honest DiD](https://diff-diff.readthedocs.io/en/stable/api/honest_did.html) - Rambachan & Roth (2023) sensitivity analysis: robust CI under PT violations, breakdown values

{diff_diff-3.9.0 → diff_diff-3.9.1}/README.md

@@ -125,6 +125,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 ## Diagnostics & Sensitivity
 
 - [RD Plots](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Calonico, Cattaneo & Titiunik (2015) optimal data-driven RD plots (`RDPlot`): all 8 rdrobust `binselect` bin selectors, implied-scale/WIMSE-weight reporting, optional matplotlib rendering
+- [Manipulation Testing](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Cattaneo, Jansson & Ma (2020) density-discontinuity test (`RDDensityTest`): rddensity 3.0 parity, robust bias-corrected inference, unrestricted/restricted models, mass-point adjustment
 - [Parallel Trends Testing](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html) - simple and Wasserstein-robust parallel trends tests, equivalence testing (TOST)
 - [Placebo Tests](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html) - placebo timing, group, permutation, leave-one-out
 - [Honest DiD](https://diff-diff.readthedocs.io/en/stable/api/honest_did.html) - Rambachan & Roth (2023) sensitivity analysis: robust CI under PT violations, breakdown values

{diff_diff-3.9.0 → diff_diff-3.9.1}/diff_diff/__init__.py

@@ -162,6 +162,7 @@ from diff_diff.lpdid import LPDiD
 from diff_diff.lpdid_results import LPDiDResults
 from diff_diff.mmm import (
     MeridianROIPrior,
+    meridian_calibration_mask,
     to_meridian_roi_prior,
     to_pymc_marketing_lift_test,
 )
@@ -223,6 +224,10 @@ from diff_diff.rdd import (
     RegressionDiscontinuity,
     RegressionDiscontinuityResults,
 )
+from diff_diff.rddensity import (
+    RDDensityTest,
+    RDDensityTestResult,
+)
 from diff_diff.rdplot import (
     RDPlot,
     RDPlotResult,
@@ -361,7 +366,7 @@ def __getattr__(name: str) -> _Any:
     raise AttributeError(f"module 'diff_diff' has no attribute {name!r}")
 
 
-__version__ = "3.9.0"
+__version__ = "3.9.1"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -570,6 +575,9 @@ __all__ = [
     # RDPlot (data-driven RD plots, rdplot parity)
     "RDPlot",
     "RDPlotResult",
+    # RDDensityTest (manipulation testing, rddensity parity)
+    "RDDensityTest",
+    "RDDensityTestResult",
     # HeterogeneousAdoptionDiD pre-test diagnostics (Phase 3)
     "qug_test",
     "stute_test",
@@ -613,6 +621,7 @@ __all__ = [
     # MMM calibration export (interop)
     "to_pymc_marketing_lift_test",
     "to_meridian_roi_prior",
+    "meridian_calibration_mask",
     "MeridianROIPrior",
     # LLM guide accessor
     "get_llm_guide",

{diff_diff-3.9.0 → diff_diff-3.9.1}/diff_diff/_reporting_helpers.py

@@ -57,9 +57,10 @@ def describe_target_parameter(results: Any) -> Dict[str, Any]:
       the horizon / group target.
     - ``CallawaySantAnna``: ``overall_att`` is cohort-size-weighted
       across post-treatment ``ATT(g, t)`` cells regardless of the
-      fit-time ``aggregate`` kwarg. The event-study / group
-      aggregations live on dedicated fields
-      (``event_study_effects`` / ``group_effects``).
+      fit-time ``aggregate`` kwarg. The event-study / group tables are
+      produced post-fit via ``results.aggregate('event_study'/'group')``
+      (the deprecated fit-time ``aggregate=`` kwarg populates the legacy
+      ``event_study_effects`` / ``group_effects`` fields until 4.0).
     - ``ContinuousDiD``: the regime (PT vs. SPT) is a user-level
       assumption, not a library setting. The ``definition`` names
       both regime readings (``ATT^loc`` under PT,
@@ -137,9 +138,11 @@ def describe_target_parameter(results: Any) -> Dict[str, Any]:
                 "A cohort-size-weighted average of group-time ATTs "
                 "``ATT(g, t)`` across post-treatment cells (``t >= g``). "
                 "``overall_att`` is the simple-aggregation headline regardless "
-                "of the fit-time ``aggregate`` kwarg; event-study and group "
-                "aggregations populate ``event_study_effects`` / "
-                "``group_effects`` fields when requested."
+                "of aggregation choices; event-study and group tables are "
+                "produced post-fit via "
+                "``results.aggregate('event_study'/'group')`` (the deprecated "
+                "fit-time ``aggregate=`` kwarg populates the legacy "
+                "``event_study_effects`` / ``group_effects`` fields until 4.0)."
             ),
             "aggregation": "simple",
             "headline_attribute": "overall_att",

{diff_diff-3.9.0 → diff_diff-3.9.1}/diff_diff/_staggered_triple_diff_engine.py

@@ -64,10 +64,13 @@ class _StaggeredTripleDiffEngineMixin:
     supply the constructor attributes and the CS aggregation/bootstrap mixins
     this core calls. The annotations below exist because mypy type-checks this
     class independently of its hosts (`attr-defined` is not disabled) - they are
-    declarations, never assignments.
+    declarations, never assignments — with ONE exception: `anticipation` is
+    re-assigned by the core's fit-time re-validation (the mutation-defense
+    re-check normalizes it to a Python int; see `_fit_staggered_core`).
     """
 
-    # Constructor attributes read from the host class.
+    # Constructor attributes read from the host class. (`anticipation` is
+    # additionally RE-ASSIGNED at fit — the validate-and-normalize re-check.)
     estimation_method: str
     control_group: str
     alpha: float
@@ -178,8 +181,10 @@ class _StaggeredTripleDiffEngineMixin:
             # the deprecated StaggeredTripleDifference (whose 3.x API SHAPE is
             # frozen through removal - that freeze was never a licence to emit
             # silently-biased numbers) and direct attribute mutation on either
-            # class, which bypasses __init__ and set_params alike.
-            validate_anticipation(self.anticipation)
+            # class, which bypasses __init__ and set_params alike. The
+            # assignment form also normalizes a numpy scalar to a Python int
+            # before any `g - 1 - anticipation` arithmetic can overflow.
+            self.anticipation = validate_anticipation(self.anticipation)
             from diff_diff.survey import (
                 _resolve_survey_for_fit,
                 _validate_unit_constant_survey,

{diff_diff-3.9.0 → diff_diff-3.9.1}/diff_diff/aggregation.py

@@ -45,6 +45,13 @@ AGGREGATION_VOCABULARY: Tuple[str, ...] = (
     "event_study",
     "group",
     "calendar",
+    # "total": the estimator-owned total incremental outcome - an exact relay
+    # C x overall (C = the estimator's finite-masked complete-case aggregation
+    # support), CONDITIONAL on the realized aggregation mass. Shared meaning
+    # across adopters (CallawaySantAnna / ImputationDiD / TwoStageDiD /
+    # EfficientDiD); per-estimator support remains a subset, so non-adopters
+    # raise the same vocabulary-suffixed error as "calendar".
+    "total",
 )
 
 #: Pinned column schema of ``AggregationResult.to_dataframe()`` - identical for
@@ -97,6 +104,77 @@ def resolve_inference_df(results: Any) -> Optional[float]:
     return None
 
 
+def build_total_relay_row(
+    *,
+    mass: float,
+    att: Optional[float],
+    se: Optional[float],
+    t_stat: Optional[float],
+    p_value: Optional[float],
+    conf_int: Tuple[float, float],
+    df: Optional[float],
+    alpha: float,
+    estimator: str,
+) -> "AggregationResult":
+    """One ``level='total'`` row: the exact relay ``mass x overall``.
+
+    The estimand is the total incremental outcome CONDITIONAL ON THE REALIZED
+    AGGREGATION MASS: ``att = mass x overall_att``, ``se = mass x overall_se``,
+    CI scaled by ``mass``, ``t_stat``/``p_value``/``df`` inherited unchanged
+    (every SE branch is homogeneous of degree 1, so the relay is exact under
+    analytical AND percentile-bootstrap inference). Inherited NaNs PASS
+    THROUGH - a degenerate fit whose CI is (nan, nan) beside a finite att
+    keeps its finite ``att``/``n``, mirroring what ``aggregate('simple')``
+    publishes on the same fit (the repo's non-estimable-row convention:
+    att/n are inputs, never blanked by NaN inference fields).
+
+    Two cases blank the WHOLE row (att/se/t/p/CI/n/df all NaN):
+    - ``mass`` is not finite (no aggregable support exists), or
+    - a FINITE overall value became non-finite BY the scaling (true float
+      overflow; surfaced per this code family's finiteness convention rather
+      than an ``errstate`` wrap).
+    """
+
+    def _f(v: Optional[float]) -> float:
+        return float(v) if v is not None else np.nan
+
+    a, s = _f(att), _f(se)
+    t, p = _f(t_stat), _f(p_value)
+    lo, hi = _f(conf_int[0]), _f(conf_int[1])
+    d = _f(df)
+
+    s_att, s_se = mass * a, mass * s
+    s_lo, s_hi = mass * lo, mass * hi
+    n_val = float(mass)
+    overflowed = np.isfinite(mass) and (
+        (np.isfinite(a) and not np.isfinite(s_att))
+        or (np.isfinite(s) and not np.isfinite(s_se))
+        or (np.isfinite(lo) and not np.isfinite(s_lo))
+        or (np.isfinite(hi) and not np.isfinite(s_hi))
+    )
+    if not np.isfinite(mass) or overflowed:
+        s_att = s_se = s_lo = s_hi = t = p = d = np.nan
+        n_val = np.nan
+
+    return AggregationResult(
+        level="total",
+        label=np.array(["total"], dtype=object),
+        target=np.array(["total"], dtype=object),
+        att=np.array([s_att], dtype=float),
+        se=np.array([s_se], dtype=float),
+        t_stat=np.array([t], dtype=float),
+        p_value=np.array([p], dtype=float),
+        conf_int_lower=np.array([s_lo], dtype=float),
+        conf_int_upper=np.array([s_hi], dtype=float),
+        n=np.array([n_val], dtype=float),
+        df=d,
+        alpha=alpha,
+        n_kind="obs",
+        weight=np.array([1.0], dtype=float),
+        estimator=estimator,
+    )
+
+
 def _sortable(labels: np.ndarray) -> bool:
     """Can ``labels`` be ordered without raising?
 
@@ -128,11 +206,14 @@ class AggregationResult(BaseResults):
     label : np.ndarray
         Per-row aggregation key: the cohort for ``"group"``, the calendar
         period for ``"calendar"``, the dose for ``"dose"``. A single
-        ``"overall"`` entry for ``"simple"``.
+        ``"overall"`` entry for ``"simple"``; a single ``"total"`` entry for
+        ``"total"``.
     target : np.ndarray
         Per-row estimand discriminator, so one container can carry two
         aligned estimands over the same labels (ContinuousDiD's ATT(d) and
-        ACRT(d) become 2N rows). ``"att"`` where an estimator has one.
+        ACRT(d) become 2N rows). ``"att"`` where an estimator has one;
+        ``"total"`` on a ``"total"`` row - a total incremental outcome over
+        the estimator's aggregation mass, not an ATT.
     att, se, t_stat, p_value : np.ndarray
         The canonical quintet, per row, carrying WHATEVER inference the fit
         stored - never recomputed. On a bootstrapped fit that usually means
@@ -157,7 +238,8 @@ class AggregationResult(BaseResults):
         ``(level, target)`` group. ``None`` where no per-row mass exists -
         CallawaySantAnna's ``"group"`` aggregation weights ``(g, t)`` cells
         equally WITHIN each cohort and has no cross-cohort mass, so inventing
-        one would be a fabricated number.
+        one would be a fabricated number. Single-row containers
+        (``"simple"``, ``"total"``) carry ``weight=[1.0]``.
     df : np.ndarray
         Per-row inference degrees of freedom, NaN where none governed the
         stored p-value. NaN on percentile-bootstrap rows (no df governs
@@ -454,9 +536,12 @@ class AggregationKit:
     ----------
     bookkeeping : dict
         The aggregation-relevant subset of the estimator's ``precomputed``
-        mapping. O(n_units) on panel fits; several entries are
-        observation-length on repeated cross-sections, where
-        ``all_units = np.arange(n_obs)`` by construction.
+        mapping, plus fit-time DERIVED keys stashed by the kit builder
+        (CallawaySantAnna's ``agg_gt_cells``/``is_survey_fit``,
+        ImputationDiD's ``total_support`` - see each builder). O(n_units) on
+        panel fits, except ``agg_gt_cells`` which is O(n_gt) 4-tuples;
+        several entries are observation-length on repeated cross-sections,
+        where ``all_units = np.arange(n_obs)`` by construction.
     influence : dict
         Per-``(g, t)`` influence-function payload. The DOMINANT retained
         object, roughly O(n_units x n_gt).

{diff_diff-3.9.0 → diff_diff-3.9.1}/diff_diff/business_report.py

@@ -13,9 +13,13 @@ Design principles:
 
 - Plain English, not academic jargon. The library ships this in addition to, not
   in place of, the estimator's existing ``results.summary()`` academic output.
-- No estimator fitting and no variance re-derivation. Every effect, SE, p-value,
-  CI, and sensitivity bound is either read from ``results`` or produced by an
-  existing diff-diff utility. The report layer does compose a few cross-period
+- No estimator fitting. Every effect, SE, p-value, CI, and sensitivity bound
+  is either read from ``results``, derived by the auto-constructed
+  ``DiagnosticReport`` from the result's own post-fit
+  ``aggregate('event_study')`` surface (a view or retained-kit recompute,
+  used only when the raw ``event_study_effects`` field is absent; see the
+  ``DiagnosticReport`` module docstring), or produced by an existing
+  diff-diff utility. The report layer does compose a few cross-period
   summaries from per-period inputs already on the result (joint-Wald / Bonferroni
   pre-trends p-value, MDV-to-ATT ratio, heterogeneity dispersion over
   post-treatment effects); see ``docs/methodology/REPORTING.md`` for the full
@@ -351,8 +355,10 @@ class BusinessReport:
                 "precomputed= contains keys that are not implemented: "
                 f"{sorted(_br_unsupported)}. Supported keys: "
                 f"{sorted(_br_supported_precomputed)}. ``design_effect``, "
-                "``heterogeneity``, and ``epv`` are read directly from the "
-                "fitted result and do not accept precomputed overrides."
+                "``heterogeneity``, and ``epv`` are read from the fitted "
+                "result (heterogeneity may also derive the post-fit "
+                "aggregate('event_study') surface) and do not accept "
+                "precomputed overrides."
             )
 
         resolved_alpha = alpha if alpha is not None else getattr(results, "alpha", 0.05)
@@ -941,6 +947,10 @@ def _lift_pre_trends(dr: Optional[Dict[str, Any]]) -> Dict[str, Any]:
         return {
             "status": pt.get("status", "not_run"),
             "reason": pt.get("reason"),
+            # DR attaches derived-surface provenance to gate-skipped
+            # sections too (a successful-but-empty derivation) — the skip
+            # path must not drop it (None on raw routes, same as below).
+            "pre_period_source": pt.get("pre_period_source"),
         }
     return {
         "status": "computed",
@@ -956,6 +966,14 @@ def _lift_pre_trends(dr: Optional[Dict[str, Any]]) -> Dict[str, Any]:
         # ``verdict == "inconclusive"`` per ``_pt_event_study``'s
         # inconclusive branch (``diagnostic_report.py:999``).
         "n_dropped_undefined": pt.get("n_dropped_undefined"),
+        # Provenance of the pre-period surface: "aggregate_event_study"
+        # when DR derived it from the post-fit
+        # ``results.aggregate('event_study')`` container. BR always emits
+        # the key — ``None`` on raw-field routes (DR itself omits the key
+        # there; ``dict.get`` maps that to None). Lifted explicitly for
+        # the same reason as ``n_dropped_undefined`` — this function is a
+        # field whitelist.
+        "pre_period_source": pt.get("pre_period_source"),
         "reason": pt.get("reason"),
         # Carry the denominator df through when the survey F-reference
         # branch was used so BR consumers can flag the finite-sample

{diff_diff-3.9.0 → diff_diff-3.9.1}/diff_diff/continuous_did.py

@@ -45,7 +45,7 @@ from diff_diff.survey import (
     build_unit_first_row_index,
     compute_survey_vcov,
 )
-from diff_diff.utils import safe_inference, validate_n_bootstrap
+from diff_diff.utils import safe_inference, validate_anticipation, validate_n_bootstrap
 
 if TYPE_CHECKING:
     from diff_diff.survey import ResolvedSurveyDesign, SurveyDesign
@@ -182,7 +182,8 @@ class ContinuousDiD(_ContinuousDiDAggregationMixin, BaseEstimator):
         ``P(D=d_L) > 0``) and no never-treated units present. Single-cohort only
         (multi-cohort and ``covariates=`` raise ``NotImplementedError``).
     anticipation : int, default=0
-        Number of periods of treatment anticipation.
+        Number of periods of treatment anticipation. Must be a
+        non-negative integer; ``bool`` is rejected.
     base_period : str, default="varying"
         ``"varying"`` or ``"universal"``.
     alpha : float, default=0.05
@@ -310,12 +311,18 @@ class ContinuousDiD(_ContinuousDiDAggregationMixin, BaseEstimator):
         self._validate_constrained_params()
 
     def _validate_constrained_params(self) -> None:
-        """Validate control_group, base_period, and estimation_method values."""
+        """Validate control_group, base_period, and estimation_method values.
+
+        Also validates ``anticipation`` and re-assigns it as a normalized
+        Python ``int`` — idempotent on an already-normalized value, so a
+        re-run never changes fitted config.
+        """
         if self.control_group not in self._VALID_CONTROL_GROUPS:
             raise ValueError(
                 f"Invalid control_group: '{self.control_group}'. "
                 f"Must be one of {self._VALID_CONTROL_GROUPS}."
             )
+        self.anticipation = validate_anticipation(self.anticipation)
         if self.base_period not in self._VALID_BASE_PERIODS:
             raise ValueError(
                 f"Invalid base_period: '{self.base_period}'. "
@@ -442,6 +449,14 @@ class ContinuousDiD(_ContinuousDiDAggregationMixin, BaseEstimator):
         else:
             aggregate = None
 
+        # Fit-time re-check: __init__ and set_params validate eagerly, so
+        # this only catches DIRECT attribute mutation (est.anticipation = ...)
+        # — an out-of-domain value silently changes the ESTIMAND. The
+        # assignment also re-normalizes a mutated numpy scalar to int. Placed
+        # AFTER the deprecation shim so a caller who both mutated and passed
+        # a deprecated argument still sees the FutureWarning before the raise.
+        self.anticipation = validate_anticipation(self.anticipation)
+
         # 1. Validate & prepare
         _VALID_AGGREGATES = (None, "dose", "eventstudy")
         if aggregate not in _VALID_AGGREGATES: