panelkit 0.2.5__tar.gz → 0.2.6__tar.gz

{panelkit-0.2.5 → panelkit-0.2.6}/Cargo.lock

@@ -462,7 +462,7 @@ checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
 
 [[package]]
 name = "panelkit-estimators"
-version = "0.2.5"
+version = "0.2.6"
 dependencies = [
  "criterion",
  "panelkit-linalg",
@@ -471,7 +471,7 @@ dependencies = [
 
 [[package]]
 name = "panelkit-geo"
-version = "0.2.5"
+version = "0.2.6"
 dependencies = [
  "panelkit-estimators",
  "panelkit-inference",
@@ -482,7 +482,7 @@ dependencies = [
 
 [[package]]
 name = "panelkit-inference"
-version = "0.2.5"
+version = "0.2.6"
 dependencies = [
  "panelkit-estimators",
  "panelkit-linalg",
@@ -491,7 +491,7 @@ dependencies = [
 
 [[package]]
 name = "panelkit-linalg"
-version = "0.2.5"
+version = "0.2.6"
 dependencies = [
  "proptest",
  "rayon",
@@ -623,7 +623,7 @@ dependencies = [
 
 [[package]]
 name = "pypanelkit"
-version = "0.2.5"
+version = "0.2.6"
 dependencies = [
  "numpy",
  "panelkit-estimators",

{panelkit-0.2.5 → panelkit-0.2.6}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/linalg", "crates/estimators", "crates/inference", "crates/geo", "crates/pypanelkit"]
 
 [workspace.package]
-version = "0.2.5"
+version = "0.2.6"
 edition = "2021"
 rust-version = "1.74"
 license = "MIT OR Apache-2.0"

{panelkit-0.2.5 → panelkit-0.2.6}/GUIDE.md

@@ -300,10 +300,14 @@ ev.plot_effect_over_time("effect.png")  # pointwise + cumulative over time, w/ C
 ev.lift, ev.cumulative, ev.significant
 ```
 
-Inference is **in-space placebo** (Abadie): every donor market is refit as if it
-were the treated one, and the spread of *their* post-period effects is the null
-reference — capturing out-of-sample extrapolation error, the real source of
-uncertainty. (A bootstrap of the treated unit's own post-period only sees
+Inference defaults to **in-space placebo** (Abadie, `inference="placebo"`): every
+donor market is refit as if it were the treated one, and the spread of *their*
+post-period effects is the null reference — capturing out-of-sample extrapolation
+error, the real source of uncertainty. A second engine, `inference="bootstrap"`,
+uses a moving-block bootstrap of the pre-period residuals; it's serial-correlation
+aware and works as a **fallback when the donor pool is too small for placebo**, but
+it only sees in-sample noise, so it is *optimistic* (the report is flagged
+`optimistic` and you shouldn't lean on it for significance). (A bootstrap of the treated unit's own post-period only sees
 in-sample noise and is wildly anti-conservative — on null data its 90% interval
 falsely flags an effect ~50% of the time; the placebo version sits at/below the
 nominal 10%.) Poorly-fit placebos (pre-period RMSPE > 2× the treated unit's) are

{panelkit-0.2.5 → panelkit-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panelkit
-Version: 0.2.5
+Version: 0.2.6
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering

{panelkit-0.2.5 → panelkit-0.2.6}/crates/linalg/src/factor/qr.rs

@@ -92,8 +92,18 @@ impl Qr {
     }
 
     /// Back-substitute `R x = rhs[0..n]`, returning `x` (length `n`).
+    ///
+    /// Householder QR does not rank-reveal, so a rank-deficient design can leave a
+    /// (near-)zero pivot on the diagonal. Rather than emit `inf`/`NaN` (which would
+    /// silently poison downstream OLS coefficients), we zero that component — a
+    /// minimum-norm-style choice — using a relative pivot threshold.
     fn back_solve(&self, rhs: &[f64]) -> Vec<f64> {
         let n = self.n;
+        let mut max_diag = 0.0_f64;
+        for i in 0..n {
+            max_diag = max_diag.max(self.packed.get(i, i).abs());
+        }
+        let eps = 1e-12 * max_diag.max(1.0);
         let mut x = vec![0.0; n];
         for i in (0..n).rev() {
             let mut s = rhs[i];
@@ -101,7 +111,7 @@ impl Qr {
                 s -= self.packed.get(i, k) * x[k];
             }
             let rii = self.packed.get(i, i);
-            x[i] = s / rii;
+            x[i] = if rii.abs() > eps { s / rii } else { 0.0 };
         }
         x
     }

{panelkit-0.2.5 → panelkit-0.2.6}/crates/linalg/src/opt/simplex.rs

@@ -145,8 +145,13 @@ pub fn solve_fw(gram: &Mat, b: &[f64], eta: f64, max_iter: usize, tol: f64) -> S
         let dgd = dot(&d, &gd_vec);
         let gamma = if dgd > 0.0 {
             (-gd / dgd).clamp(0.0, gamma_max)
-        } else {
+        } else if gd < 0.0 {
+            // Non-positive curvature along a descent direction → go to the
+            // feasible cap (bounded so the step never leaves the simplex).
             gamma_max.min(1.0)
+        } else {
+            // Not a descent direction → don't move.
+            0.0
         };
         for i in 0..j {
             w[i] += gamma * d[i];

{panelkit-0.2.5 → panelkit-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "panelkit"
-version = "0.2.5"
+version = "0.2.6"
 description = "Fast, from-scratch causal-inference estimators for panel/geo experiments (SC, ASC, SDID, DiD, MC-NNM)."
 readme = "README.md"
 requires-python = ">=3.9"

{panelkit-0.2.5 → panelkit-0.2.6}/python/panelkit/design.py

@@ -53,6 +53,24 @@ def _ensemble_weight_arg(spec):
     return w
 
 
+def _block_bootstrap_paths(pre_gaps, length, block_len, n_reps, seed):
+    """Moving-block bootstrap of the (centered) pre-period residuals into placebo
+    paths of ``length`` periods. Resampling whole blocks preserves the residual
+    autocorrelation. Returns an ``(n_reps, length)`` array (empty if no pre-period
+    or zero length)."""
+    g = np.asarray(pre_gaps, dtype=float)
+    m = len(g)
+    if m == 0 or length <= 0 or n_reps <= 0:
+        return np.empty((0, max(length, 0)))
+    g = g - g.mean()                       # null is "no effect" → center residuals
+    rng = np.random.default_rng(int(seed))
+    bl = max(1, min(int(block_len), m))
+    n_blocks = int(np.ceil(length / bl))
+    starts = rng.integers(0, m, size=(n_reps, n_blocks))
+    idx = (starts[:, :, None] + np.arange(bl)[None, None, :]) % m  # circular blocks
+    return g[idx].reshape(n_reps, n_blocks * bl)[:, :length]
+
+
 class _PowerReport:
     """Result of a power analysis across methods, with a report and plots."""
 
@@ -682,7 +700,10 @@ class GeoDesign:
         methods: Sequence[str] = _METHODS,
         weights="auto",
         level: float = 0.90,
+        inference: str = "placebo",
         max_placebo: int = 200,
+        n_boot: int = 2000,
+        block_len: int = 4,
         seed: int = 0,
         exclude=None,
     ) -> "_EvalReport":
@@ -693,13 +714,20 @@ class GeoDesign:
         post-period column), it fits SC / ASC / SDID, reports each one's effect,
         and combines them into a weighted-average **ensemble** estimate.
 
-        Inference is **in-space placebo** (Abadie): every donor market is refit as
-        if it were the treated one, and the spread of *their* post-period effects
-        is the null reference. This captures out-of-sample extrapolation error —
-        the dominant source of uncertainty — so the intervals are calibrated
-        (unlike a bootstrap of the treated unit's own post-period, which only sees
-        in-sample noise and is far too narrow). Poorly-fit placebos (pre-period
-        RMSPE > 2× the treated unit's) are dropped, per Abadie.
+        Two inference engines (``inference=``):
+
+        - ``"placebo"`` (default) — **in-space placebo** (Abadie): every donor
+          market is refit as if it were treated, and the spread of *their*
+          post-period effects is the null. This captures out-of-sample
+          extrapolation error (the dominant uncertainty), so it is calibrated.
+          Poorly-fit placebos (pre-period RMSPE > 2× the treated unit's) are
+          dropped. Needs a reasonable donor pool to have power.
+        - ``"bootstrap"`` — a **moving-block bootstrap of the pre-period
+          residuals** (serial-correlation-aware). Useful as a within-sample noise
+          band and as a fallback when the donor pool is too small for placebo
+          inference, **but it is optimistic**: it only sees in-sample noise, not
+          extrapolation error, so do not rely on it for significance. The report
+          is flagged ``optimistic`` in this mode.
 
         Parameters
         ----------
@@ -733,7 +761,8 @@ class GeoDesign:
             if bad:
                 raise ValueError(f"treated markets were also excluded: {bad}")
             return sub.evaluate(tnames, treat_start, methods=methods, weights=weights,
-                                level=level, max_placebo=max_placebo, seed=seed)
+                                level=level, inference=inference, max_placebo=max_placebo,
+                                n_boot=n_boot, block_len=block_len, seed=seed)
         idx = list(dict.fromkeys(self._resolve(treated)))  # dedup, preserve order
         names = [self.names[i] for i in idx]
         t0 = int(treat_start)
@@ -782,29 +811,55 @@ class GeoDesign:
                 "pre_rmspe": float(fit.pre_rmspe),
             }
 
-        # --- in-space placebo: refit each donor as if it were treated ---
-        treated_set = set(idx)
-        donors = [u for u in range(self.n) if u not in treated_set]
-        if len(donors) > int(max_placebo):
-            rng = np.random.default_rng(int(seed))
-            donors = sorted(int(j) for j in rng.choice(donors, int(max_placebo), replace=False))
-        pb = {m: [] for m in methods}        # per method: list of (att_path, pre_rmspe)
-        for j in donors:
-            for m in methods:
-                fj = _fit(m, [j])
-                pb[m].append((np.asarray(fj.att_path, dtype=float), float(fj.pre_rmspe)))
-
-        # --- ensemble weights ---
-        def _placebo_att_sd(m):
-            if not pb[m]:
-                return 1.0
-            vals = np.array([p.mean() for (p, _) in pb[m]])
-            return float(np.std(vals)) if len(vals) > 1 else 1.0
+        inference = str(inference).lower()
+        if inference not in ("placebo", "bootstrap"):
+            raise ValueError("inference must be 'placebo' or 'bootstrap'")
+        a = (1.0 - float(level)) / 2.0
+
+        def _ci(point, null_samples):
+            """Pivot CI: point estimate ± the null spread (null ≈ 0). Returns NaN
+            when there are too few null samples — never a fake zero-width CI."""
+            if len(null_samples) >= 2:
+                return point + float(np.quantile(null_samples, a)), \
+                    point + float(np.quantile(null_samples, 1.0 - a))
+            return float("nan"), float("nan")
+
+        # --- engine: per-method null att-samples (+ donor placebo paths if used) ---
+        if inference == "placebo":
+            treated_set = set(idx)
+            donors = [u for u in range(self.n) if u not in treated_set]
+            if len(donors) > int(max_placebo):
+                rng = np.random.default_rng(int(seed))
+                donors = sorted(int(j) for j in
+                                rng.choice(donors, int(max_placebo), replace=False))
+            pb = {m: [] for m in methods}    # per method: list of (att_path, pre_rmspe)
+            for j in donors:
+                for m in methods:
+                    fj = _fit(m, [j])
+                    pb[m].append((np.asarray(fj.att_path, dtype=float), float(fj.pre_rmspe)))
+
+            def _kept_att(samples, treated_pre_m):
+                keep = [p.mean() for (p, pre) in samples
+                        if treated_pre_m <= 0 or pre <= 2.0 * treated_pre_m]
+                if len(keep) < 5 and samples:
+                    keep = [p.mean() for (p, _) in samples]
+                return np.array(keep)
+            null_att = {m: _kept_att(pb[m], per[m]["pre_rmspe"]) for m in order}
+        else:  # bootstrap of pre-period residuals
+            null_att = {}
+            for m in order:
+                pre_resid = treated_series[:t0] - per[m]["full_cf"][:t0]
+                Bm = _block_bootstrap_paths(pre_resid, post_len, block_len, n_boot, seed)
+                null_att[m] = Bm.mean(axis=1) if Bm.size else np.array([])
+
+        # --- ensemble weights (auto = inverse null-att variance per method) ---
+        def _null_sd(m):
+            v = null_att[m]
+            return float(np.std(v)) if len(v) > 1 else 1.0
         if isinstance(weights, str) and weights.lower() == "equal":
             wv = [1.0 / len(order)] * len(order)
         elif isinstance(weights, str) and weights.lower() == "auto":
-            # inverse-variance from each method's placebo-null spread (precision)
-            prec = [1.0 / max(_placebo_att_sd(m) ** 2, 1e-300) for m in order]
+            prec = [1.0 / max(_null_sd(m) ** 2, 1e-300) for m in order]
             s = sum(prec)
             wv = [p / s for p in prec] if s > 0 else [1.0 / len(order)] * len(order)
         elif isinstance(weights, dict):
@@ -821,54 +876,41 @@ class GeoDesign:
             s = sum(raw)
             wv = [r / s for r in raw]
         wmap = dict(zip(order, wv))
-        a = (1.0 - float(level)) / 2.0
 
-        def _ci(point, null_samples):
-            """Pivot CI: point estimate ± the placebo null spread (null ≈ 0).
-            Returns NaN when there are too few placebos to form an interval —
-            never a fake zero-width CI."""
-            if len(null_samples) >= 2:
-                return point + float(np.quantile(null_samples, a)), \
-                    point + float(np.quantile(null_samples, 1.0 - a))
-            return float("nan"), float("nan")
-
-        def _kept_att(samples, treated_pre_m):
-            """Placebo att-means after the Abadie 2x pre-fit filter (fallback to
-            all placebos if too few comparable ones survive)."""
-            keep = [p.mean() for (p, pre) in samples
-                    if treated_pre_m <= 0 or pre <= 2.0 * treated_pre_m]
-            if len(keep) < 5 and samples:
-                keep = [p.mean() for (p, _) in samples]
-            return np.array(keep)
-
-        # --- per-method point CIs from each method's placebo att spread (same
-        #     2x pre-fit filter as the ensemble, for internal consistency) ---
+        # --- per-method point CIs from each method's null att spread ---
         for m in order:
-            mp = _kept_att(pb[m], per[m]["pre_rmspe"])
-            lo, hi = _ci(per[m]["att"], mp)
+            lo, hi = _ci(per[m]["att"], null_att[m])
             cfm = per[m]["cf_mean"]
             per[m]["att_lo"], per[m]["att_hi"] = lo, hi
             per[m]["lift_lo"] = lo / cfm if cfm else float("nan")
             per[m]["lift_hi"] = hi / cfm if cfm else float("nan")
 
-        # --- ensemble estimate + ensemble placebo paths (Abadie pre-fit filter) ---
+        # --- ensemble estimate ---
         ens_path = sum(wmap[m] * per[m]["att_path"] for m in order)
         ens_cf_mean = float(sum(wmap[m] * per[m]["cf_mean"] for m in order))
         ens_att = float(ens_path.mean())
-        treated_pre = sum(wmap[m] * per[m]["pre_rmspe"] for m in order)
-
-        ens_pb = []  # (path, pre_rmspe)
-        for di in range(len(donors)):
-            path = sum(wmap[m] * pb[m][di][0] for m in order)
-            pre = sum(wmap[m] * pb[m][di][1] for m in order)
-            ens_pb.append((path, pre))
-        kept = [p for (p, pre) in ens_pb if treated_pre <= 0 or pre <= 2.0 * treated_pre]
-        if len(kept) < 5:                      # too few comparable placebos → use all
-            kept = [p for (p, _) in ens_pb]
-        pb_mat = np.array(kept) if kept else np.zeros((0, post_len))
+        ens_full_cf = sum(wmap[m] * per[m]["full_cf"] for m in order)
+
+        # --- ensemble null-path matrix (engine-specific) ---
+        if inference == "placebo":
+            treated_pre = sum(wmap[m] * per[m]["pre_rmspe"] for m in order)
+            ens_pb = []
+            for di in range(len(donors)):
+                path = sum(wmap[m] * pb[m][di][0] for m in order)
+                pre = sum(wmap[m] * pb[m][di][1] for m in order)
+                ens_pb.append((path, pre))
+            kept = [p for (p, pre) in ens_pb if treated_pre <= 0 or pre <= 2.0 * treated_pre]
+            if len(kept) < 5:                  # too few comparable placebos → use all
+                kept = [p for (p, _) in ens_pb]
+            pb_mat = np.array(kept) if kept else np.zeros((0, post_len))
+            label = "in-space placebo"
+        else:
+            ens_pre = treated_series[:t0] - ens_full_cf[:t0]
+            pb_mat = _block_bootstrap_paths(ens_pre, post_len, block_len, n_boot, seed)
+            label = "block bootstrap"
         n_pb = pb_mat.shape[0]
 
-        # pointwise + cumulative + mean CIs, all from the placebo null
+        # --- shared: pointwise / cumulative / mean CIs + p-value from the null ---
         if n_pb >= 2:
             point_lo = ens_path + np.quantile(pb_mat, a, axis=0)
             point_hi = ens_path + np.quantile(pb_mat, 1.0 - a, axis=0)
@@ -898,12 +940,14 @@ class GeoDesign:
             "lift_lo": att_lo / ens_cf_mean if ens_cf_mean else float("nan"),
             "lift_hi": att_hi / ens_cf_mean if ens_cf_mean else float("nan"),
             "cumulative": float(ens_path.sum()) * n_treated,
-            "weights": wmap, "n_placebo": n_pb,
-            "low_power": n_pb < 8,   # too few placebos for reliable inference
+            "weights": wmap, "n_placebo": n_pb, "inference": label,
+            # placebo with too few donors is undefined/low-power; bootstrap is
+            # serial-correlation-aware but optimistic (in-sample noise only).
+            "low_power": (inference == "placebo" and n_pb < 8),
+            "optimistic": (inference == "bootstrap"),
         }
 
         # full-timeline counterfactual + gap path (pre shows fit; post = effect)
-        ens_full_cf = sum(wmap[m] * per[m]["full_cf"] for m in order)
         full_gap = treated_series - ens_full_cf
         full_gap[t0:] = ens_path
         counterfactual = treated_series - full_gap
@@ -1114,12 +1158,17 @@ class _EvalReport:
         wstr = ", ".join(f"{m} {100*w:.0f}%" for m, w in e["weights"].items())
         lines.append(f"   ensemble weights: {wstr}")
         lines.append("")
+        engine = e.get("inference", "in-space placebo")
+        unit = "draws" if engine == "block bootstrap" else "donors"
         if self.p_value is not None:
-            lines.append(f"In-space placebo p-value    : {self.p_value:.3f}  "
-                         f"(ensemble, {e.get('n_placebo', 0)} donors)")
+            lines.append(f"Placebo/bootstrap p-value   : {self.p_value:.3f}  "
+                         f"({engine}, {e.get('n_placebo', 0)} {unit})")
         if e.get("low_power"):
             lines.append("⚠ Few comparable donors — inference is low-powered; treat "
                          "intervals/p-value with caution.")
+        if e.get("optimistic"):
+            lines.append("⚠ Bootstrap CIs see in-sample noise only (optimistic) — use "
+                         "inference='placebo' for significance when donors allow.")
         if self.significant:
             verdict = "✓ Significant lift — the ensemble interval excludes zero."
         elif not (np.isfinite(e["att_lo"]) and np.isfinite(e["att_hi"])):
@@ -1132,8 +1181,7 @@ class _EvalReport:
                      f"{e['cumulative']:,.0f} cumulative incremental")
         if "cum_lo" in e:
             lines.append(f"Cumulative {cl}% CI          : "
-                         f"[{e['cum_lo']:,.0f}, {e['cum_hi']:,.0f}]  "
-                         f"(in-space placebo, {e.get('n_placebo', 0)} donors)")
+                         f"[{e['cum_lo']:,.0f}, {e['cum_hi']:,.0f}]  ({engine})")
         lines.append(verdict)
         lines.append("=" * 66)
         return "\n".join(lines)
@@ -1682,7 +1730,7 @@ def _plot_eval_timeline(rep: "_EvalReport", path):
     cum = e["cum_curve"]
     axc.axvspan(-0.5, t0 - 0.5, color="#f3f4f6", alpha=0.8)
     axc.fill_between(seg, e["cum_lo_curve"], e["cum_hi_curve"], color=_PK_GREEN,
-                     alpha=0.15, label=f"{cl}% band (in-space placebo)")
+                     alpha=0.15, label=f"{cl}% band ({e.get('inference', 'in-space placebo')})")
     axc.plot(seg, cum, color=_PK_GREEN, lw=2.4, label="cumulative incremental")
     axc.axhline(0, color="#111827", lw=1.0)
     axc.axvline(t0 - 0.5, color="#374151", lw=1.2, ls=":")