panelkit 0.2.4__tar.gz → 0.2.5__tar.gz

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

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

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panelkit
-Version: 0.2.4
+Version: 0.2.5
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering
@@ -274,7 +274,7 @@ per-cell MDE/confidence/holdout report and a combined figure:
 the power analysis: fit SC / ASC / SDID on a test that already happened, blend
 them into a weighted-average **ensemble** estimate, and report each one's lift,
 confidence interval (in-space placebo), and cumulative incremental —
-with an SC in-space placebo p-value:
+with an in-space placebo p-value:
 
 ![test evaluation](assets/geo_evaluate.png)
 
@@ -316,7 +316,7 @@ What you get out of the box:
 - **A weighted-average ensemble** of SC + ASC + SDID (combined per placebo window,
   with auto inverse-variance weights) for a steadier estimate than any one method.
 - **Post-test evaluation** — `evaluate()` measures a test that already ran:
-  per-method + ensemble lift, bootstrap CIs, cumulative incremental, and a p-value.
+  per-method + ensemble lift, in-space placebo CIs, cumulative incremental, and a p-value.
 
 See [`examples/geo_demo.py`](examples/geo_demo.py).
 

{panelkit-0.2.4 → panelkit-0.2.5}/README.md

@@ -244,7 +244,7 @@ per-cell MDE/confidence/holdout report and a combined figure:
 the power analysis: fit SC / ASC / SDID on a test that already happened, blend
 them into a weighted-average **ensemble** estimate, and report each one's lift,
 confidence interval (in-space placebo), and cumulative incremental —
-with an SC in-space placebo p-value:
+with an in-space placebo p-value:
 
 ![test evaluation](assets/geo_evaluate.png)
 
@@ -286,7 +286,7 @@ What you get out of the box:
 - **A weighted-average ensemble** of SC + ASC + SDID (combined per placebo window,
   with auto inverse-variance weights) for a steadier estimate than any one method.
 - **Post-test evaluation** — `evaluate()` measures a test that already ran:
-  per-method + ensemble lift, bootstrap CIs, cumulative incremental, and a p-value.
+  per-method + ensemble lift, in-space placebo CIs, cumulative incremental, and a p-value.
 
 See [`examples/geo_demo.py`](examples/geo_demo.py).
 

{panelkit-0.2.4 → panelkit-0.2.5}/crates/estimators/src/sc/sdid.rs

@@ -87,6 +87,10 @@ pub fn fit_at(panel: &Panel, t0: usize, cfg: SdidConfig) -> ScFit {
     let t = panel.n_periods();
     let t_pre = t0;
     let t_post = t - t0;
+    assert!(
+        t_pre >= 1 && t_post >= 1,
+        "SDID needs at least one pre- and one post-period (t0 in 1..n_periods)"
+    );
     let n_tr = treated.len();
 
     // Treated-average series.

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

@@ -30,17 +30,14 @@ pub fn project_simplex(v: &[f64]) -> Vec<f64> {
     let mut u = v.to_vec();
     u.sort_by(|a, b| b.partial_cmp(a).unwrap()); // descending
     let mut css = 0.0;
-    let mut rho = 0usize;
     let mut theta = 0.0;
     for (j, &uj) in u.iter().enumerate() {
         css += uj;
         let t = (css - 1.0) / (j as f64 + 1.0);
         if uj - t > 0.0 {
-            rho = j + 1;
             theta = t;
         }
     }
-    let _ = rho;
     v.iter().map(|&vi| (vi - theta).max(0.0)).collect()
 }
 

{panelkit-0.2.4 → panelkit-0.2.5}/crates/pypanelkit/src/api_sc.rs

@@ -111,13 +111,15 @@ pub fn fit_sdid(
 /// Fit Matrix-Completion NNM (Athey et al. 2021). `max_rank`, when set, uses a
 /// fast randomized truncated SVD inside SoftImpute (big speedup, low-rank cap).
 #[pyfunction]
-#[pyo3(signature = (y, treated, treat_time, lambda=None, max_iter=200, tol=1e-5, seed=0, max_rank=None))]
+// `lambda_` (not `lambda`) so it is usable as a Python keyword argument —
+// `lambda` is a reserved word in Python.
+#[pyo3(signature = (y, treated, treat_time, lambda_=None, max_iter=200, tol=1e-5, seed=0, max_rank=None))]
 #[allow(clippy::too_many_arguments)]
 pub fn fit_mcnnm(
     y: PyReadonlyArray2<f64>,
     treated: Vec<usize>,
     treat_time: usize,
-    lambda: Option<f64>,
+    lambda_: Option<f64>,
     max_iter: usize,
     tol: f64,
     seed: u64,
@@ -125,7 +127,7 @@ pub fn fit_mcnnm(
 ) -> PyResult<PyScResult> {
     let panel = Panel::block(mat_from_numpy(&y), &treated, treat_time);
     let cfg = McnnmConfig {
-        lambda,
+        lambda: lambda_,
         max_iter,
         tol,
         seed,

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "panelkit"
-version = "0.2.4"
+version = "0.2.5"
 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.4 → panelkit-0.2.5}/python/panelkit/_panelkit.pyi

@@ -82,7 +82,7 @@ def fit_mcnnm(
     y: npt.NDArray[np.float64],
     treated: Sequence[int],
     treat_time: int,
-    lambda_: Optional[float] = ...,
+    lambda_: Optional[float] = ...,  # NOTE: matches the Rust binding's `lambda_`
     max_iter: int = ...,
     tol: float = ...,
     seed: int = ...,

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

@@ -42,7 +42,8 @@ def _ensemble_weight_arg(spec):
         raise ValueError(f"unknown ensemble_weights {spec!r} (use 'auto', 'equal', "
                          "a dict, or a 3-list)")
     if isinstance(spec, dict):
-        w = [float(spec.get(m, spec.get(m.lower(), 0.0))) for m in _ENSEMBLE_ORDER]
+        norm = {str(k).upper(): v for k, v in spec.items()}  # case-insensitive keys
+        w = [float(norm.get(m, 0.0)) for m in _ENSEMBLE_ORDER]
     else:
         w = [float(x) for x in spec]
         if len(w) != 3:
@@ -407,7 +408,7 @@ class GeoDesign:
                              target_power=target_power, recommended=recommended,
                              lookback=lookback, ensemble=ensemble,
                              ensemble_weights=ensemble_weights)
-        idx = self._resolve(treated)
+        idx = list(dict.fromkeys(self._resolve(treated)))  # dedup, preserve order
         names = [self.names[i] for i in idx]
         lifts = list(_DEFAULT_LIFTS if lifts is None else lifts)
         if 0.0 not in lifts:
@@ -443,7 +444,7 @@ class GeoDesign:
             if bad:
                 raise ValueError(f"treated markets were also excluded: {bad}")
             return sub.diagnose(tnames, test_len)
-        idx = self._resolve(treated)
+        idx = list(dict.fromkeys(self._resolve(treated)))  # dedup, preserve order
         names = [self.names[i] for i in idx]
         t0 = self.t - int(test_len)
         diag = _panelkit.geo_diagnostics(self.Y, idx, int(test_len))
@@ -733,7 +734,7 @@ class GeoDesign:
                 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)
-        idx = self._resolve(treated)
+        idx = list(dict.fromkeys(self._resolve(treated)))  # dedup, preserve order
         names = [self.names[i] for i in idx]
         t0 = int(treat_start)
         if not (1 <= t0 < self.t):
@@ -807,7 +808,8 @@ class GeoDesign:
             s = sum(prec)
             wv = [p / s for p in prec] if s > 0 else [1.0 / len(order)] * len(order)
         elif isinstance(weights, dict):
-            raw = [float(weights.get(m, weights.get(m.lower(), 0.0))) for m in order]
+            norm = {str(k).upper(): v for k, v in weights.items()}  # case-insensitive
+            raw = [float(norm.get(m, 0.0)) for m in order]
             s = sum(raw)
             if s <= 0:
                 raise ValueError("ensemble weights must sum to > 0")
@@ -822,15 +824,27 @@ class GeoDesign:
         a = (1.0 - float(level)) / 2.0
 
         def _ci(point, null_samples):
-            """Pivot CI: point estimate ± the placebo null spread (null ≈ 0)."""
+            """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 point, point
-
-        # --- per-method point CIs from each method's placebo att spread ---
+            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) ---
         for m in order:
-            mp = np.array([p.mean() for (p, _) in pb[m]]) if pb[m] else np.array([])
+            mp = _kept_att(pb[m], per[m]["pre_rmspe"])
             lo, hi = _ci(per[m]["att"], mp)
             cfm = per[m]["cf_mean"]
             per[m]["att_lo"], per[m]["att_hi"] = lo, hi
@@ -866,10 +880,12 @@ class GeoDesign:
             pb_att = pb_mat.mean(axis=1)
             p_value = float((1.0 + np.sum(np.abs(pb_att) >= abs(ens_att))) / (1.0 + n_pb))
         else:
-            point_lo = point_hi = ens_path.copy()
-            point_hw = 0.0
+            # too few comparable placebos → inference undefined (no fake band)
             run = np.cumsum(ens_path)
-            cum_lo_band = cum_hi_band = np.zeros(post_len)
+            point_lo = np.full(post_len, np.nan)
+            point_hi = np.full(post_len, np.nan)
+            point_hw = 0.0
+            cum_lo_band = cum_hi_band = np.full(post_len, np.nan)
             pb_att = np.array([])
             p_value = None
         att_lo, att_hi = _ci(ens_att, pb_att)
@@ -883,6 +899,7 @@ class GeoDesign:
             "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
         }
 
         # full-timeline counterfactual + gap path (pre shows fit; post = effect)
@@ -1000,11 +1017,14 @@ class _MultiCellReport:
                      f"({', '.join(map(str, self.cells))})")
         lines.append(f"Test duration     : {self.test_len} periods")
         lines.append(f"Shared donor pool : {len(self.donor_names)} markets")
-        lines.append(f"Combined holdout  : {100*self.pooled_holdout:.1f}% of total volume")
+        lines.append(f"Combined holdout  : {100*self.pooled_holdout:.1f}% of total volume "
+                     f"(all cells together)")
         lines.append(f"Powered at {int(100*self.target_power)}% power, "
                      f"{int(100*(1-self.alpha))}% confidence "
                      f"(each cell vs. the shared pool).")
         lines.append("")
+        # Per-cell 'Holdout' is that cell's share of its OWN sub-panel (cell +
+        # shared donors); the Combined holdout above is over the full panel.
         lines.append(f"{'Cell':<14}{'Markets':<28}{'MDE':>8}{'Conf':>7}{'Holdout':>9}")
         lines.append("-" * 64)
         for label, rep in self.cells.items():
@@ -1069,8 +1089,11 @@ class _EvalReport:
 
     @property
     def significant(self):
-        """True if the ensemble CI excludes zero (effect detected)."""
+        """True if the ensemble CI is well-defined and excludes zero. Returns
+        False when inference is undefined (too few placebos → NaN interval)."""
         lo, hi = self.ensemble["att_lo"], self.ensemble["att_hi"]
+        if not (np.isfinite(lo) and np.isfinite(hi)):
+            return False
         return (lo > 0) or (hi < 0)
 
     def summary(self) -> str:
@@ -1092,11 +1115,19 @@ class _EvalReport:
         lines.append(f"   ensemble weights: {wstr}")
         lines.append("")
         if self.p_value is not None:
-            lines.append(f"SC in-space placebo p-value : {self.p_value:.3f}")
-        verdict = ("✓ Significant lift — the ensemble interval excludes zero."
-                   if self.significant else
-                   "~ Not distinguishable from zero at this level — the ensemble "
-                   "interval includes zero.")
+            lines.append(f"In-space placebo p-value    : {self.p_value:.3f}  "
+                         f"(ensemble, {e.get('n_placebo', 0)} donors)")
+        if e.get("low_power"):
+            lines.append("⚠ Few comparable donors — inference is low-powered; treat "
+                         "intervals/p-value with caution.")
+        if self.significant:
+            verdict = "✓ Significant lift — the ensemble interval excludes zero."
+        elif not (np.isfinite(e["att_lo"]) and np.isfinite(e["att_hi"])):
+            verdict = ("? Inference undefined — too few comparable donor placebos "
+                       "to form an interval.")
+        else:
+            verdict = ("~ Not distinguishable from zero at this level — the ensemble "
+                       "interval includes zero.")
         lines.append(f"Headline (ensemble)         : {100*e['lift']:+.2f}% lift, "
                      f"{e['cumulative']:,.0f} cumulative incremental")
         if "cum_lo" in e:
@@ -1588,7 +1619,7 @@ def _plot_eval(rep: "_EvalReport", path):
     axc.set_title("Lift by method", fontweight="bold")
     axc.grid(True, axis="x", alpha=0.25)
 
-    pv = f"  ·  SC placebo p={rep.p_value:.3f}" if rep.p_value is not None else ""
+    pv = f"  ·  placebo p={rep.p_value:.3f}" if rep.p_value is not None else ""
     verdict = "significant" if rep.significant else "not significant"
     fig.suptitle(f"panelkit · test evaluation — ensemble lift "
                  f"{100*rep.ensemble['lift']:+.2f}% ({verdict}){pv}",