diff-diff 3.6.1__tar.gz → 3.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.6.1
+Version: 3.7.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -32,6 +32,7 @@ Requires-Dist: pydata-sphinx-theme>=0.16.1 ; extra == 'docs'
 Requires-Dist: sphinxext-opengraph>=0.9 ; extra == 'docs'
 Requires-Dist: sphinx-sitemap>=2.5 ; extra == 'docs'
 Requires-Dist: nbsphinx>=0.9 ; extra == 'docs'
+Requires-Dist: myst-parser>=2.0 ; extra == 'docs'
 Requires-Dist: matplotlib>=3.5 ; extra == 'docs'
 Requires-Dist: ipython>=8.0 ; extra == 'docs'
 Requires-Dist: plotly>=5.0 ; extra == 'plotly'
@@ -190,6 +191,7 @@ Most estimators accept an optional `survey_design` parameter (or `survey=` / `we
 - **Variance methods**: Taylor Series Linearization (TSL via Binder 1983), replicate weights (BRR / Fay / JK1 / JKn / SDR), survey-aware bootstrap
 - **Diagnostics**: DEFF per coefficient, effective n, subpopulation analysis, weight trimming, CV on estimates
 - **Repeated cross-sections**: `CallawaySantAnna(panel=False)` for BRFSS, ACS, CPS
+- **Weight calibration / raking**: upstream by design - pair with Meta's [balance](https://import-balance.org/) package, whose `balance.interop.diff_diff` adapter hands raked samples straight to diff-diff; see the [composition-drift tutorial](https://diff-diff.readthedocs.io/en/stable/tutorials/26_composition_drift_calibration.html)
 
 No other Python or R DiD package offers design-based variance estimation for modern heterogeneity-robust estimators.
 

{diff_diff-3.6.1 → diff_diff-3.7.0}/README.md

@@ -137,6 +137,7 @@ Most estimators accept an optional `survey_design` parameter (or `survey=` / `we
 - **Variance methods**: Taylor Series Linearization (TSL via Binder 1983), replicate weights (BRR / Fay / JK1 / JKn / SDR), survey-aware bootstrap
 - **Diagnostics**: DEFF per coefficient, effective n, subpopulation analysis, weight trimming, CV on estimates
 - **Repeated cross-sections**: `CallawaySantAnna(panel=False)` for BRFSS, ACS, CPS
+- **Weight calibration / raking**: upstream by design - pair with Meta's [balance](https://import-balance.org/) package, whose `balance.interop.diff_diff` adapter hands raked samples straight to diff-diff; see the [composition-drift tutorial](https://diff-diff.readthedocs.io/en/stable/tutorials/26_composition_drift_calibration.html)
 
 No other Python or R DiD package offers design-based variance estimation for modern heterogeneity-robust estimators.
 

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

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

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

@@ -65,6 +65,34 @@ 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
+
+# Batched ridge-regularized SPD solve (EfficientDiD per-unit weights):
+# imported independently for the same mixed-version reason as demean_map.
+try:
+    from diff_diff._rust_backend import (
+        batched_ridge_chol_solve_ones as _rust_batched_ridge_chol_solve,
+    )
+except ImportError:
+    _rust_batched_ridge_chol_solve = None
+
+# HC2 (leverage-corrected) robust vcov: imported independently for the same
+# mixed-version reason as demean_map (a stale extension missing only this
+# newer symbol degrades HC2 to the NumPy path without disabling the older
+# Rust accelerations).
+try:
+    from diff_diff._rust_backend import (
+        compute_robust_vcov_hc2 as _rust_compute_robust_vcov_hc2,
+    )
+except ImportError:
+    _rust_compute_robust_vcov_hc2 = 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 +101,12 @@ 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
+    # Batched ridge-regularized SPD solve
+    _rust_batched_ridge_chol_solve = None
+    # HC2 robust vcov
+    _rust_compute_robust_vcov_hc2 = None
     # TROP estimator acceleration (local method)
     _rust_unit_distance_matrix = None
     _rust_loocv_grid_search = None
@@ -124,6 +158,10 @@ __all__ = [
     "_rust_project_simplex",
     "_rust_solve_ols",
     "_rust_compute_robust_vcov",
+    # FE-absorption MAP demeaning kernel
+    "_rust_demean_map",
+    # Batched ridge-regularized SPD solve (EfficientDiD per-unit weights)
+    "_rust_batched_ridge_chol_solve",
     # TROP estimator acceleration (local method)
     "_rust_unit_distance_matrix",
     "_rust_loocv_grid_search",

{diff_diff-3.6.1 → diff_diff-3.7.0}/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.7.0}/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.7.0}/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.7.0}/diff_diff/bootstrap_chunking.py

@@ -23,11 +23,27 @@ Bit-identity of the weight *generation* is preserved on **both** backends:
 - The **NumPy** fallback draws the matrix row-major from the ``Generator``
   stream, so consuming it in contiguous, in-order blocks from the same generator
   reproduces the identical sequence.
+
+The *influence* side can be tiled too. When a fit needs many perturbation
+columns (per-cell IFs, the overall combined IF, per-event-time combined IFs),
+computing them one column at a time degenerates into per-column slicing/GEMV
+over the weight blocks -- memory-bandwidth-bound, not FLOP-bound. Instead,
+:func:`tiled_if_matmul` scatters the columns into an ``(n_units, tile_cols)``
+buffer and runs one BLAS GEMM per (weight block, column tile). The column axis
+is tiled under a byte cap, and each column tile makes its own full pass over
+the weight stream via :class:`ReplayableWeightStream`, which snapshots the
+generator state at construction and restores it per pass -- so every pass sees
+the bit-identical weight stream on both backends (Rust re-draws the same
+``base_seed`` from the restored state; the NumPy fallback replays the stream
+itself; the survey stratified branch regenerates its full PSU matrix from the
+restored state). GEMM results match the per-column GEMV path to within BLAS
+reassociation, same as the draw-axis chunking above.
 """
 
 from __future__ import annotations
 
-from typing import Iterator, Optional, Tuple
+from collections import abc
+from typing import Callable, Iterable, Iterator, List, Optional, Sequence, Tuple, Union
 
 import numpy as np
 
@@ -183,3 +199,134 @@ def iter_survey_multiplier_weight_blocks(
             yield chunk_start, block
 
     return psu_ids, _generated()
+
+
+# Byte ceiling for the ``(n_units, tile_cols)`` float64 scatter buffer used by
+# ``tiled_if_matmul``. Sibling of ``_TARGET_BLOCK_BYTES``; together they bound
+# the kernel's live intermediates at ~384 MB regardless of n_units or the
+# number of perturbation columns. Read at CALL time inside ``tiled_if_matmul``
+# (never bound as a def-time default) so tests can monkeypatch it.
+_TARGET_TILE_BYTES = 128 * 1024 * 1024
+
+# One perturbation column of ``tiled_if_matmul``'s influence matrix: a list of
+# (index, values) contributions. ``index=None`` assigns the full-width dense
+# ``values``; otherwise ``values`` is scattered at ``index``. A column may also
+# be a zero-argument callable returning such a list, materialized only when its
+# tile is filled (keeps peak memory at one O(n_units) temporary for callers
+# whose columns are computed on the fly).
+IFColumn = List[Tuple[Optional[np.ndarray], np.ndarray]]
+IFColumnSpec = Union[IFColumn, Callable[[], IFColumn]]
+
+
+class ReplayableWeightStream:
+    """Multiplier-weight block stream that can be re-iterated bit-identically.
+
+    Wraps a weight-block iterator factory together with the ``Generator`` that
+    feeds it, snapshotting the generator state at construction. Every
+    ``__iter__`` restores the snapshot before invoking the factory, so each
+    pass yields the exact same ``(chunk_start, block)`` sequence:
+
+    - **Rust backend**: ``iter_weight_blocks`` draws its per-run ``base_seed``
+      from the rng lazily at the first ``next()``; the restored state
+      reproduces the same base seed, and rows are seeded absolutely from it.
+    - **NumPy fallback**: generation consumes the rng stream directly; the
+      restored state replays the identical stream.
+    - **Survey stratified branch**: ``iter_survey_multiplier_weight_blocks``
+      generates its full PSU matrix eagerly at factory-call time -- from the
+      restored state, so per-pass recreation is also bit-identical.
+
+    The snapshot MUST precede any rng-consuming call: construct this object
+    before probing generators that draw at call time (the survey stratified
+    branch draws eagerly; resolve ``psu_ids`` from the design's ``psu`` array
+    directly instead of via a probe call). After the final pass the rng ends
+    exactly where a single pass would leave it, so downstream consumers of the
+    same generator are unaffected by the number of passes.
+    """
+
+    def __init__(
+        self,
+        make_iter: Callable[[np.random.Generator], Iterator[Tuple[int, np.ndarray]]],
+        rng: np.random.Generator,
+    ) -> None:
+        self._make_iter = make_iter
+        self._rng = rng
+        self._state = rng.bit_generator.state
+
+    def __iter__(self) -> Iterator[Tuple[int, np.ndarray]]:
+        self._rng.bit_generator.state = self._state
+        return self._make_iter(self._rng)
+
+
+def tiled_if_matmul(
+    weight_stream: Iterable[Tuple[int, np.ndarray]],
+    n_bootstrap: int,
+    n_units: int,
+    columns: Sequence[IFColumnSpec],
+    *,
+    tile_bytes: Optional[int] = None,
+) -> np.ndarray:
+    """Compute ``W @ M`` for the multiplier bootstrap without materializing
+    ``W`` (streamed in row blocks) or ``M`` (scattered in column tiles).
+
+    ``W`` is the ``(n_bootstrap, n_units)`` weight matrix yielded by
+    ``weight_stream`` as ``(chunk_start, block)`` row blocks; ``M`` is the
+    ``(n_units, len(columns))`` influence matrix described by ``columns``
+    (see :data:`IFColumnSpec`). Returns the dense ``(n_bootstrap, n_cols)``
+    product. Columns are tiled under ``tile_bytes`` (default: module attribute
+    ``_TARGET_TILE_BYTES``, resolved at call time); each tile is scattered
+    once into an F-order buffer and then consumed by one BLAS GEMM per weight
+    block. With more than one tile, ``weight_stream`` is iterated once per
+    tile and therefore must be re-iterable with an identical stream --
+    :class:`ReplayableWeightStream` provides exactly that.
+
+    Scatter contract: contributions are written by plain assignment, so index
+    arrays must be unique within each contribution and the contributions of a
+    single column must be mutually disjoint (duplicate or overlapping indices
+    keep the last write instead of summing like ``W[:, idx] @ values`` would).
+    All in-repo callers satisfy this by construction (treated/control unit
+    sets are disjoint; dense columns are single-contribution).
+
+    A non-finite influence value poisons only its own output column (every
+    output element is an independent dot product), matching the per-column
+    GEMV behavior this kernel replaces. Results match the per-column GEMV
+    path to within BLAS reassociation (~1 ULP), not bit-for-bit.
+    """
+    n_cols = len(columns)
+    out = np.empty((n_bootstrap, n_cols))
+    if n_cols == 0 or n_bootstrap == 0:
+        return out
+    if tile_bytes is None:
+        tile_bytes = _TARGET_TILE_BYTES
+    tile_cols = int(max(1, min(n_cols, tile_bytes // (max(1, n_units) * 8))))
+
+    # A single-pass iterator silently exhausts after the first tile, leaving
+    # uninitialized rows in `out` -- fail loudly instead. isinstance (not an
+    # iter() probe) so re-iterable streams see no extra pass.
+    if tile_cols < n_cols and isinstance(weight_stream, abc.Iterator):
+        raise ValueError(
+            "tiled_if_matmul needs more than one column tile but weight_stream "
+            "is a single-pass iterator; pass a re-iterable stream "
+            "(ReplayableWeightStream) so each tile can replay the weights."
+        )
+
+    buf = np.zeros((n_units, tile_cols), order="F")
+    for lo in range(0, n_cols, tile_cols):
+        hi = min(lo + tile_cols, n_cols)
+        width = hi - lo
+        if lo > 0:
+            buf[:, :width] = 0.0
+        for c in range(lo, hi):
+            spec = columns[c]
+            if callable(spec):
+                spec = spec()
+            col = buf[:, c - lo]
+            for idx, values in spec:
+                if idx is None:
+                    np.copyto(col, values)
+                else:
+                    col[idx] = values
+        tile = buf[:, :width]
+        with np.errstate(divide="ignore", invalid="ignore", over="ignore"):
+            for chunk_start, w_block in weight_stream:
+                out[chunk_start : chunk_start + w_block.shape[0], lo:hi] = w_block @ tile
+    return out

{diff_diff-3.6.1 → diff_diff-3.7.0}/diff_diff/chaisemartin_dhaultfoeuille.py

@@ -4665,7 +4665,12 @@ def _compute_placebo(
         else:
             joiner_avg = float((y_prev[joiner_mask] - y_pre_prev[joiner_mask]).mean())
             stable0_avg = float((y_prev[stable0_mask] - y_pre_prev[stable0_mask]).mean())
-            placebo_plus_t = joiner_avg - stable0_avg
+            # Backward-difference convention (pre-period minus reference,
+            # Y_{t-2} - Y_{t-1}), matching the multi-horizon placebo path
+            # `_compute_multi_horizon_placebos` (`switcher_change - ctrl_avg`
+            # with `Y_bwd - Y_ref`, times switch_direction=+1 for joiners) and
+            # R `did_multiplegt_dyn`. Equivalently `stable0_avg - joiner_avg`.
+            placebo_plus_t = stable0_avg - joiner_avg
 
         # Leavers side: symmetric A11 distinction
         if n_01 == 0:
@@ -4678,7 +4683,10 @@ def _compute_placebo(
         else:
             stable1_avg = float((y_prev[stable1_mask] - y_pre_prev[stable1_mask]).mean())
             leaver_avg = float((y_prev[leaver_mask] - y_pre_prev[leaver_mask]).mean())
-            placebo_minus_t = stable1_avg - leaver_avg
+            # Backward-difference convention times switch_direction=-1 for
+            # leavers (see the joiners-side note above): the multi-horizon path
+            # contributes `leaver_avg - stable1_avg` here.
+            placebo_minus_t = leaver_avg - stable1_avg
 
         placebo_plus_per_t.append(placebo_plus_t)
         placebo_minus_per_t.append(placebo_minus_t)