panelkit 0.2.0__tar.gz → 0.2.1__tar.gz

{panelkit-0.2.0 → panelkit-0.2.1}/Cargo.lock

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

{panelkit-0.2.0 → panelkit-0.2.1}/Cargo.toml

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

{panelkit-0.2.0 → panelkit-0.2.1}/GUIDE.md

@@ -251,16 +251,58 @@ SC / ASC / SDID. Returns a report with:
   estimate-accuracy CI, design-quality bars).
 
 Key options: `alpha` (significance level, default 0.10), `target_power`
-(default 0.80), `lifts` (the % grid), `methods`, `recommended` (default SDID).
+(default 0.80), `lifts` (the % grid), `methods`, `recommended` (default SDID),
+`lookback`.
+
+**How power is simulated (many placebos, not one).** For a treated set, the test
+window of length `test_len` is *slid across the whole history*: every valid start
+position is one placebo experiment. The detection threshold (critical |ATT|)
+comes from those same windows with **no** injected lift (the historical null), and
+power at lift τ is the share of windows whose injected effect clears that
+threshold. So the estimate is averaged over **many** placebos — `result.n_windows`
+reports how many.
+
+**Relationship to GeoLift's `lookback_window`.** GeoLift's lookback is exactly
+this idea — how many recent test-start points to simulate over. By default
+panelkit uses *all* available windows (more placebo samples → a more stable power
+estimate). Pass `lookback=k` to use only the **most-recent k** windows: those have
+the longest pre-periods and reflect current dynamics, so they're the most
+representative of the test you're about to run — at the cost of fewer samples (a
+noisier estimate). It matters when older history is unrepresentative (regime
+change, growth, format changes) or when early windows have very short pre-periods;
+use a `lookback` covering your relevant recent history (e.g. the last ~6–12
+months of windows).
 
 ### Choosing a specification — `design.recommend(test_lengths, n_geos_options, target_lift, alphas=…)`
 
 Sweeps designs across **test length × number of geos × alpha** and recommends the
 best (smallest MDE among trustworthy designs, ties broken toward shorter/cheaper).
 `grid.summary()` prints the recommendation + alternatives; `grid.plot(path)`
-renders the **tradeoffs figure** (MDE vs length per #geos, an MDE heatmap over
-length × #geos, and alpha sensitivity). Use it to find the "knee" — the cheapest
-design that still detects your target lift.
+renders the **tradeoffs figure**. Use it to find the "knee" — the cheapest design
+that still detects your target lift.
+
+**Reading the tradeoffs figure:**
+- **Top panel** — minimum detectable lift (%) vs test length, one line per number
+  of treated geos. *Lower is better.* The red band marks lifts you *can't*
+  detect; lines below your target lift are viable designs. More geos and longer
+  tests pull the line down (more signal), but cost more holdout/time — pick the
+  knee where the curve flattens.
+- **Bottom-left heatmap** — the same MDE across every (test length × #geos) cell,
+  green = small detectable lift (good), red = large (bad), grey = underpowered.
+- **Bottom-right** — with multiple alphas, how the MDE of the recommended design
+  moves with the significance level (looser α → smaller MDE, more false
+  positives); with one alpha, design confidence by spec.
+- The black ★ marks the recommended design.
+
+### Guardrails — `design.diagnose(treated, test_len)`
+
+Before trusting a design, check it. `diagnose` returns a report with
+`.summary()` and `.plot(path)` (the **guardrails figure**): the pre-period fit
+(treated vs synthetic control, so you can *see* whether the counterfactual
+tracks), a seasonality ACF, the holdout share against a healthy band, and a
+banner listing any plain-language warnings (weak fit, volatile markets, strong
+seasonality vs short history, tiny/huge holdout, too few donors). It also exposes
+`.confidence`, `.holdout_pct`, and `.warnings`.
 
 ### Picking markets — `design.select_markets(test_len, target_lift, max_treated, …)`
 

{panelkit-0.2.0 → panelkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: panelkit
-Version: 0.2.0
+Version: 0.2.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering
@@ -217,11 +217,16 @@ rep = design.power(treated=["chicago", "denver"], test_len=8, alpha=0.10)
 print(rep.summary())          # plain-English report: MDE, confidence, warnings
 rep.plot("design.png")        # the figure below
 
+# guardrails: is this design trustworthy? (pre-fit, seasonality, holdout, warnings)
+guard = design.diagnose(treated=["chicago", "denver"], test_len=8)
+print(guard.summary())
+guard.plot("guardrails.png")  # the guardrails figure below
+
 # let it pick the markets for you:
 ranked = design.select_markets(test_len=8, target_lift=0.05, max_treated=3)
 
 # or sweep specifications (length × #geos × significance) and recommend one:
-grid = design.recommend(test_lengths=[4, 6, 8, 12], n_geos_options=[1, 2, 3, 4],
+grid = design.recommend(test_lengths=[4, 6, 8, 12], n_geos_options=[3, 5, 10, 20],
                         target_lift=0.05, alphas=[0.05, 0.10])
 print(grid.summary())
 grid.plot("tradeoffs.png")    # the tradeoffs figure below
@@ -229,9 +234,16 @@ grid.plot("tradeoffs.png")    # the tradeoffs figure below
 
 ![geo design report](assets/geo_design.png)
 
+**Guardrails — can you trust the design?** `diagnose(...)` visualizes the
+pre-period fit (treated vs synthetic control), seasonality, holdout share, and
+surfaces plain-language warnings when the design is risky:
+
+![guardrails](assets/geo_guardrails.png)
+
 **Recommendations across specifications.** `recommend(...)` sweeps test length ×
 number of geos × significance level (`alpha`) and points you at the cheapest
-design that still detects your target lift — with a figure of the tradeoffs:
+design that still detects your target lift — with a readable figure of the
+tradeoffs (MDE vs length per #geos, an intuitive heatmap, and alpha sensitivity):
 
 ![specification tradeoffs](assets/geo_scenarios.png)
 

{panelkit-0.2.0 → panelkit-0.2.1}/README.md

@@ -187,11 +187,16 @@ rep = design.power(treated=["chicago", "denver"], test_len=8, alpha=0.10)
 print(rep.summary())          # plain-English report: MDE, confidence, warnings
 rep.plot("design.png")        # the figure below
 
+# guardrails: is this design trustworthy? (pre-fit, seasonality, holdout, warnings)
+guard = design.diagnose(treated=["chicago", "denver"], test_len=8)
+print(guard.summary())
+guard.plot("guardrails.png")  # the guardrails figure below
+
 # let it pick the markets for you:
 ranked = design.select_markets(test_len=8, target_lift=0.05, max_treated=3)
 
 # or sweep specifications (length × #geos × significance) and recommend one:
-grid = design.recommend(test_lengths=[4, 6, 8, 12], n_geos_options=[1, 2, 3, 4],
+grid = design.recommend(test_lengths=[4, 6, 8, 12], n_geos_options=[3, 5, 10, 20],
                         target_lift=0.05, alphas=[0.05, 0.10])
 print(grid.summary())
 grid.plot("tradeoffs.png")    # the tradeoffs figure below
@@ -199,9 +204,16 @@ grid.plot("tradeoffs.png")    # the tradeoffs figure below
 
 ![geo design report](assets/geo_design.png)
 
+**Guardrails — can you trust the design?** `diagnose(...)` visualizes the
+pre-period fit (treated vs synthetic control), seasonality, holdout share, and
+surfaces plain-language warnings when the design is risky:
+
+![guardrails](assets/geo_guardrails.png)
+
 **Recommendations across specifications.** `recommend(...)` sweeps test length ×
 number of geos × significance level (`alpha`) and points you at the cheapest
-design that still detects your target lift — with a figure of the tradeoffs:
+design that still detects your target lift — with a readable figure of the
+tradeoffs (MDE vs length per #geos, an intuitive heatmap, and alpha sensitivity):
 
 ![specification tradeoffs](assets/geo_scenarios.png)
 

{panelkit-0.2.0 → panelkit-0.2.1}/crates/geo/src/power.rs

@@ -103,6 +103,7 @@ pub fn power_curve(
     alpha: f64,
     target_power: f64,
     min_pre: usize,
+    lookback: Option<usize>,
 ) -> PowerResult {
     let t = y.cols();
     assert!(test_len >= 1 && test_len < t, "test_len out of range");
@@ -111,7 +112,18 @@ pub fn power_curve(
         first <= t - test_len,
         "not enough periods for the requested pre-window + test_len"
     );
-    let starts: Vec<usize> = (first..=(t - test_len)).collect();
+    // Every valid sliding test-window start position is one historical placebo.
+    // We power over MANY of them (the count is `n_windows`). `lookback`, when set,
+    // keeps only the most-recent K windows — GeoLift's "lookback_window": those
+    // are the most representative of the upcoming test (recent dynamics, longest
+    // pre-periods), at the cost of fewer placebo samples.
+    let mut starts: Vec<usize> = (first..=(t - test_len)).collect();
+    if let Some(k) = lookback {
+        let k = k.max(1);
+        if starts.len() > k {
+            starts = starts.split_off(starts.len() - k);
+        }
+    }
     let n_windows = starts.len();
     let (base_mean, base_sum) = treated_baseline(y, treated);
 

{panelkit-0.2.0 → panelkit-0.2.1}/crates/geo/src/selection.rs

@@ -46,6 +46,13 @@ pub struct SelectConfig {
     /// How many candidate sets to sample/evaluate.
     pub n_candidates: usize,
     pub seed: u64,
+    /// If `Some(k)`, only consider candidate sets of **exactly** `k` markets
+    /// (used by the spec sweep so each "#geos" row reflects that size). If
+    /// `None`, considers all sizes from 1 to `max_treated`.
+    pub exact_size: Option<usize>,
+    /// Number of most-recent historical placebo windows to power over
+    /// (GeoLift's lookback). `None` = all available windows.
+    pub lookback: Option<usize>,
 }
 
 /// Evaluate a single candidate set: quick power probe + diagnostics → score.
@@ -61,6 +68,7 @@ pub fn evaluate(y: &Mat, treated: &[usize], cfg: &SelectConfig) -> MarketCandida
         cfg.alpha,
         cfg.target_power,
         cfg.min_pre,
+        cfg.lookback,
     );
     let power_at_target = pr
         .points
@@ -87,13 +95,36 @@ pub fn evaluate(y: &Mat, treated: &[usize], cfg: &SelectConfig) -> MarketCandida
     }
 }
 
-/// Build the candidate list: every single eligible market, plus sampled subsets
-/// of size 2..=max_treated.
+/// Build the candidate list. With `exact_size = Some(k)`, every candidate has
+/// exactly `k` markets; otherwise it's every singleton plus sampled subsets of
+/// size 2..=max_treated.
 fn candidate_sets(cfg: &SelectConfig) -> Vec<Vec<usize>> {
-    let mut sets: Vec<Vec<usize>> = cfg.eligible.iter().map(|&u| vec![u]).collect();
+    let mut rng = Xoshiro256pp::seed_from_u64(cfg.seed);
+    let mut seen = std::collections::HashSet::new();
+    let mut sets: Vec<Vec<usize>> = Vec::new();
+
+    if let Some(k) = cfg.exact_size {
+        let k = k.min(cfg.eligible.len()).max(1);
+        if k == 1 {
+            return cfg.eligible.iter().map(|&u| vec![u]).collect();
+        }
+        let mut attempts = 0;
+        while sets.len() < cfg.n_candidates && attempts < cfg.n_candidates * 40 {
+            attempts += 1;
+            let mut pool = cfg.eligible.clone();
+            rng.shuffle(&mut pool);
+            let mut pick: Vec<usize> = pool.into_iter().take(k).collect();
+            pick.sort_unstable();
+            if seen.insert(pick.clone()) {
+                sets.push(pick);
+            }
+        }
+        return sets;
+    }
+
+    // Mixed-size search: all singletons + sampled subsets of size 2..=max_treated.
+    sets = cfg.eligible.iter().map(|&u| vec![u]).collect();
     if cfg.max_treated >= 2 && cfg.eligible.len() >= 2 {
-        let mut rng = Xoshiro256pp::seed_from_u64(cfg.seed);
-        let mut seen = std::collections::HashSet::new();
         for s in &sets {
             seen.insert(s.clone());
         }

{panelkit-0.2.0 → panelkit-0.2.1}/crates/geo/tests/geo.rs

@@ -31,7 +31,7 @@ fn geo_panel(n: usize, t: usize, seed: u64) -> Mat {
 fn power_increases_with_lift_and_mde_is_sane() {
     let y = geo_panel(15, 60, 1);
     let lifts = vec![0.0, 0.02, 0.05, 0.10, 0.20];
-    let pr = power_curve(&y, &[0], 10, &lifts, Method::Sc, 0.10, 0.8, 20);
+    let pr = power_curve(&y, &[0], 10, &lifts, Method::Sc, 0.10, 0.8, 20, None);
 
     // Power is (weakly) increasing in lift.
     for w in pr.points.windows(2) {
@@ -60,11 +60,24 @@ fn power_increases_with_lift_and_mde_is_sane() {
     }
 }
 
+#[test]
+fn lookback_limits_to_recent_windows() {
+    let y = geo_panel(15, 60, 1);
+    let lifts = vec![0.0, 0.05];
+    let all = power_curve(&y, &[0], 10, &lifts, Method::Sc, 0.10, 0.8, 20, None);
+    let recent = power_curve(&y, &[0], 10, &lifts, Method::Sc, 0.10, 0.8, 20, Some(8));
+    assert_eq!(recent.n_windows, 8, "lookback should cap to 8 windows");
+    assert!(
+        all.n_windows > recent.n_windows,
+        "all-windows count should exceed lookback"
+    );
+}
+
 #[test]
 fn estimated_lift_tracks_true_lift() {
     let y = geo_panel(15, 60, 2);
     let lifts = vec![0.0, 0.10];
-    let pr = power_curve(&y, &[0], 10, &lifts, Method::Sc, 0.10, 0.8, 20);
+    let pr = power_curve(&y, &[0], 10, &lifts, Method::Sc, 0.10, 0.8, 20, None);
     // At a 10% injected lift, the mean estimated lift should be in the ballpark.
     let p10 = pr.points.last().unwrap();
     assert!(
@@ -90,7 +103,7 @@ fn all_three_methods_run() {
     let y = geo_panel(15, 60, 4);
     let lifts = vec![0.0, 0.10];
     for m in [Method::Sc, Method::Asc, Method::Sdid] {
-        let pr = power_curve(&y, &[0], 10, &lifts, m, 0.10, 0.8, 20);
+        let pr = power_curve(&y, &[0], 10, &lifts, m, 0.10, 0.8, 20, None);
         assert_eq!(pr.method, m);
         assert_eq!(pr.points.len(), 2);
     }
@@ -110,6 +123,8 @@ fn market_selection_ranks_candidates() {
         min_pre: 20,
         n_candidates: 20,
         seed: 7,
+        exact_size: None,
+        lookback: None,
     };
     let ranked = select_markets(&y, &cfg);
     assert!(!ranked.is_empty());
@@ -117,6 +132,13 @@ fn market_selection_ranks_candidates() {
     for w in ranked.windows(2) {
         assert!(w[0].score >= w[1].score - 1e-12);
     }
+    // exact_size: every candidate has exactly that many markets.
+    let cfg2 = SelectConfig {
+        exact_size: Some(2),
+        ..cfg.clone()
+    };
+    let ranked2 = select_markets(&y, &cfg2);
+    assert!(ranked2.iter().all(|c| c.treated.len() == 2));
     // Every candidate has a valid holdout and confidence.
     for c in &ranked {
         assert!(c.holdout_pct > 0.0 && c.holdout_pct < 1.0);

{panelkit-0.2.0 → panelkit-0.2.1}/crates/pypanelkit/src/api_geo.rs

@@ -23,7 +23,7 @@ fn parse_method(s: &str) -> PyResult<Method> {
 
 /// Power analysis for one method via historical placebo with injected lift.
 #[pyfunction]
-#[pyo3(signature = (y, treated, test_len, lifts, method="sdid", alpha=0.1, target_power=0.8, min_pre=0))]
+#[pyo3(signature = (y, treated, test_len, lifts, method="sdid", alpha=0.1, target_power=0.8, min_pre=0, lookback=None))]
 #[allow(clippy::too_many_arguments)]
 pub fn geo_power(
     py: Python<'_>,
@@ -35,6 +35,7 @@ pub fn geo_power(
     alpha: f64,
     target_power: f64,
     min_pre: usize,
+    lookback: Option<usize>,
 ) -> PyResult<PyPowerResult> {
     let m = parse_method(method)?;
     let mat = mat_from_numpy(&y);
@@ -53,6 +54,7 @@ pub fn geo_power(
             alpha,
             target_power,
             min_pre,
+            lookback,
         )
     });
     Ok(PyPowerResult {
@@ -94,7 +96,7 @@ pub fn geo_diagnostics(
 
 /// Search and rank candidate treatment-market sets.
 #[pyfunction]
-#[pyo3(signature = (y, eligible, max_treated, test_len, target_lift, method="sdid", alpha=0.1, target_power=0.8, min_pre=0, n_candidates=200, seed=0))]
+#[pyo3(signature = (y, eligible, max_treated, test_len, target_lift, method="sdid", alpha=0.1, target_power=0.8, min_pre=0, n_candidates=200, seed=0, exact_size=None, lookback=None))]
 #[allow(clippy::too_many_arguments)]
 pub fn geo_select(
     py: Python<'_>,
@@ -109,6 +111,8 @@ pub fn geo_select(
     min_pre: usize,
     n_candidates: usize,
     seed: u64,
+    exact_size: Option<usize>,
+    lookback: Option<usize>,
 ) -> PyResult<Vec<PyMarketCandidate>> {
     let m = parse_method(method)?;
     let mat = mat_from_numpy(&y);
@@ -128,6 +132,8 @@ pub fn geo_select(
         min_pre,
         n_candidates,
         seed,
+        exact_size,
+        lookback,
     };
     let ranked = py.allow_threads(move || select_markets(&mat, &cfg));
     Ok(ranked

{panelkit-0.2.0 → panelkit-0.2.1}/pyproject.toml

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

@@ -160,6 +160,7 @@ def geo_power(
     alpha: float = ...,
     target_power: float = ...,
     min_pre: int = ...,
+    lookback: Optional[int] = ...,
 ) -> PowerResult: ...
 def geo_diagnostics(
     y: npt.NDArray[np.float64], treated: Sequence[int], test_len: int
@@ -176,6 +177,8 @@ def geo_select(
     min_pre: int = ...,
     n_candidates: int = ...,
     seed: int = ...,
+    exact_size: Optional[int] = ...,
+    lookback: Optional[int] = ...,
 ) -> list[MarketCandidate]: ...
 def fit_callaway_py(
     y: npt.NDArray[np.float64],

{panelkit-0.2.0 → panelkit-0.2.1}/python/panelkit/design.py

@@ -134,6 +134,56 @@ def _verdict(confidence, mde_pct):
             "history length, or holdout size before spending.")
 
 
+class _DiagnosticsReport:
+    """Real-world guardrails for a design, with a summary and a visual."""
+
+    def __init__(self, treated_names, t0, test_len, diag, treated_series, synthetic):
+        self.treated_names = treated_names
+        self.t0 = t0
+        self.test_len = test_len
+        self._raw = diag
+        self.treated_series = np.asarray(treated_series, dtype=float)
+        self.synthetic = np.asarray(synthetic, dtype=float)
+
+    @property
+    def holdout_pct(self):
+        return self._raw.holdout_pct
+
+    @property
+    def confidence(self):
+        return self._raw.confidence
+
+    @property
+    def warnings(self):
+        return list(self._raw.warnings)
+
+    def summary(self) -> str:
+        d = self._raw
+        lines = ["GUARDRAILS — " + ", ".join(map(str, self.treated_names))]
+        lines.append(f"  holdout            : {100*d.holdout_pct:.1f}% of volume")
+        lines.append(f"  pre-period fit     : rel. RMSPE {d.pre_fit_rel:.2f} "
+                     f"({'good' if d.pre_fit_rel < 0.25 else 'fair' if d.pre_fit_rel < 0.5 else 'weak'})")
+        lines.append(f"  improvement v naive: {100*d.improvement_vs_naive:.0f}%")
+        lines.append(f"  seasonality        : {d.seasonality_strength:.2f}")
+        lines.append(f"  stability          : {d.stability_score:.2f}")
+        lines.append(f"  confidence         : {d.confidence:.0f}/100")
+        if d.warnings:
+            lines.append("  warnings:")
+            for w in d.warnings:
+                lines.append(f"    ⚠ {w}")
+        else:
+            lines.append("  ✓ no warnings")
+        return "\n".join(lines)
+
+    def plot(self, path: str | None = None):
+        """Render the guardrails figure. Returns the matplotlib Figure."""
+        return _plot_guardrails(self, path)
+
+    def __repr__(self):
+        return (f"GuardrailsReport(confidence={self.confidence:.0f}, "
+                f"holdout={100*self.holdout_pct:.1f}%, warnings={len(self.warnings)})")
+
+
 class GeoDesign:
     """A geo panel ready for power analysis and market selection.
 
@@ -281,23 +331,48 @@ class GeoDesign:
         alpha: float = 0.10,
         target_power: float = 0.80,
         recommended: str = "SDID",
+        lookback: int | None = None,
     ) -> _PowerReport:
-        """Power analysis for a specified treated-market set across methods."""
+        """Power analysis for a specified treated-market set across methods.
+
+        Powers over many historical placebo windows (sliding the test window
+        across history); ``lookback=k`` restricts to the most-recent ``k`` windows
+        (GeoLift-style), which are most representative of the upcoming test."""
         idx = self._resolve(treated)
         names = [self.names[i] for i in idx]
         lifts = list(_DEFAULT_LIFTS if lifts is None else lifts)
         if 0.0 not in lifts:
             lifts = [0.0] + list(lifts)
         lifts = sorted(set(float(x) for x in lifts))
+        lb = None if lookback is None else int(lookback)
         results = {}
         for m in methods:
             results[m] = _panelkit.geo_power(
-                self.Y, idx, int(test_len), lifts, m.lower(), alpha, target_power, 0
+                self.Y, idx, int(test_len), lifts, m.lower(), alpha, target_power, 0, lb
             )
         diag = _panelkit.geo_diagnostics(self.Y, idx, int(test_len))
         rec = recommended if recommended in results else list(results)[0]
         return _PowerReport(self, idx, names, test_len, results, diag, rec, alpha, target_power)
 
+    def diagnose(self, treated, test_len: int) -> "_DiagnosticsReport":
+        """Real-world guardrails for a treated-market set: pre-period fit,
+        seasonality, holdout, stability, and warnings — with a visual.
+
+        Returns a report with ``.summary()`` and ``.plot(path)`` (the guardrails
+        figure: treated-vs-synthetic pre-fit, seasonality ACF, holdout share, and
+        a scorecard listing any warnings)."""
+        idx = self._resolve(treated)
+        names = [self.names[i] for i in idx]
+        t0 = self.t - int(test_len)
+        diag = _panelkit.geo_diagnostics(self.Y, idx, int(test_len))
+        # Treated-average series and the SC counterfactual (from the SC weights).
+        treated_series = self.Y[idx].mean(axis=0)
+        scres = _panelkit.fit_sc(self.Y, idx, int(t0), 0.0, False, 0.95)
+        w = np.asarray(scres.weights, dtype=float)
+        donors = np.asarray(scres.donor_ids, dtype=int)
+        synthetic = self.Y[donors].T @ w if len(donors) else np.full(self.t, np.nan)
+        return _DiagnosticsReport(names, t0, test_len, diag, treated_series, synthetic)
+
     def select_markets(
         self,
         test_len: int,
@@ -310,12 +385,20 @@ class GeoDesign:
         n_candidates: int = 200,
         seed: int = 0,
         top: int = 10,
+        exact_size: int | None = None,
+        lookback: int | None = None,
     ) -> list:
-        """Search candidate treatment-market sets and return the top ranked."""
+        """Search candidate treatment-market sets and return the top ranked.
+
+        ``exact_size=k`` restricts the search to sets of exactly ``k`` markets
+        (otherwise sizes 1..``max_treated`` are considered). ``lookback=k`` powers
+        over the most-recent ``k`` historical windows (GeoLift-style)."""
         elig = self._resolve(eligible) if eligible is not None else list(range(self.n))
         ranked = _panelkit.geo_select(
             self.Y, elig, int(max_treated), int(test_len), float(target_lift),
             method.lower(), alpha, target_power, 0, int(n_candidates), int(seed),
+            None if exact_size is None else int(exact_size),
+            None if lookback is None else int(lookback),
         )
         out = []
         for c in ranked[:top]:
@@ -342,6 +425,7 @@ class GeoDesign:
         n_candidates: int = 80,
         seed: int = 0,
         min_confidence: float = 60.0,
+        lookback: int | None = None,
     ) -> "_ScenarioGrid":
         """Sweep designs across **specifications** — test length × number of geos
         × significance level (alpha) — and recommend the best.
@@ -359,10 +443,9 @@ class GeoDesign:
                         test_len=tl, target_lift=target_lift, max_treated=ng,
                         eligible=eligible, method=method, alpha=alpha,
                         target_power=target_power, n_candidates=n_candidates,
-                        seed=seed, top=n_candidates,
+                        seed=seed, top=1, exact_size=ng, lookback=lookback,
                     )
-                    exact = [c for c in ranked if len(c["markets"]) == ng]
-                    best = exact[0] if exact else (ranked[0] if ranked else None)
+                    best = ranked[0] if ranked else None
                     if best is None:
                         continue
                     rows.append({
@@ -549,6 +632,10 @@ def _plot_power(rep: _PowerReport, path):
     return fig
 
 
+# Distinct, colorblind-friendly line colors (one per #geos), not a gradient.
+_GEO_PALETTE = ["#2563eb", "#059669", "#d97706", "#dc2626", "#7c3aed", "#0891b2"]
+
+
 def _plot_scenarios(grid: "_ScenarioGrid", path):
     _, plt = _require_mpl()
     import numpy as _np
@@ -557,37 +644,56 @@ def _plot_scenarios(grid: "_ScenarioGrid", path):
     a0 = grid.alphas[0]                       # primary alpha for the main panels
     rec = grid.recommended
     by = {(r["alpha"], r["test_len"], r["n_geos"]): r for r in grid.rows}
+    color_for = {ng: _GEO_PALETTE[i % len(_GEO_PALETTE)]
+                 for i, ng in enumerate(grid.n_geos_options)}
 
-    fig = plt.figure(figsize=(11, 7.4))
+    plt.rcParams.update({"font.size": 11, "axes.titlesize": 12})
+    fig = plt.figure(figsize=(12, 7.6))
     fig.patch.set_facecolor("white")
-    gs = GridSpec(2, 2, figure=fig, height_ratios=[1.1, 1.0], hspace=0.36, wspace=0.28)
+    gs = GridSpec(2, 2, figure=fig, height_ratios=[1.15, 1.0], hspace=0.42, wspace=0.30)
 
-    # Panel 1: MDE vs test length, one line per #geos (at primary alpha).
+    # ---- Panel 1: MDE vs test length, one labelled line per #geos. ----
     ax = fig.add_subplot(gs[0, :])
-    cmap = plt.get_cmap("viridis")
-    for j, ng in enumerate(grid.n_geos_options):
+    ymax = 0.0
+    for ng in grid.n_geos_options:
         xs, ys = [], []
         for tl in grid.test_lengths:
             r = by.get((a0, tl, ng))
             if r and r["mde_pct"] is not None:
                 xs.append(tl)
                 ys.append(100 * r["mde_pct"])
-        if xs:
-            color = cmap(j / max(1, len(grid.n_geos_options) - 1))
-            ax.plot(xs, ys, "o-", color=color, lw=2.0, markersize=5, label=f"{ng} geos")
-    ax.axhline(100 * grid.target_lift, ls="--", color="#374151", lw=1.0,
-               label=f"target lift {100*grid.target_lift:.0f}%")
+        if not xs:
+            continue
+        ymax = max(ymax, max(ys))
+        c = color_for[ng]
+        ax.plot(xs, ys, "o-", color=c, lw=2.6, markersize=7, label=f"{ng} geos", zorder=3)
+        # label each line at its right end so you don't need to trace the legend
+        ax.annotate(f"{ng} geos", (xs[-1], ys[-1]), textcoords="offset points",
+                    xytext=(8, 0), va="center", color=c, fontweight="bold", fontsize=10)
+    tgt = 100 * grid.target_lift
+    ax.axhline(tgt, ls="--", color="#374151", lw=1.2)
+    ax.axhspan(tgt, max(ymax, tgt) * 1.08 + 0.5, color="#fca5a5", alpha=0.12)
+    ax.annotate("can't detect below this lift", (grid.test_lengths[0], tgt),
+                textcoords="offset points", xytext=(4, 6), color="#b91c1c", fontsize=9)
     if rec is not None and rec["alpha"] == a0 and rec["mde_pct"] is not None:
-        ax.plot(rec["test_len"], 100 * rec["mde_pct"], "*", color="#dc2626",
-                markersize=20, zorder=5, label="recommended")
+        ax.plot(rec["test_len"], 100 * rec["mde_pct"], "*", color="#111827",
+                markersize=22, zorder=6)
+        ax.annotate("recommended", (rec["test_len"], 100 * rec["mde_pct"]),
+                    textcoords="offset points", xytext=(6, -16), fontweight="bold")
     ax.set_xlabel("test length (periods)")
-    ax.set_ylabel("minimum detectable lift (%)")
-    ax.set_title(f"Detectable lift vs test length & number of geos  (α={a0:.2f})",
-                 fontweight="bold")
+    ax.set_ylabel("min. detectable lift (%)  ·  lower = better")
+    ax.set_title(f"How small a lift can you detect?  (α = {a0:.2f})", fontweight="bold")
+    ax.set_xticks(grid.test_lengths)
+    ax.set_ylim(0, max(ymax, tgt) * 1.12 + 0.5)
+    ax.margins(x=0.08)
     ax.grid(True, alpha=0.25)
-    ax.legend(loc="upper right", framealpha=0.9, fontsize=8, ncol=2)
+    # endpoint labels already identify lines; keep the legend out of the way
+    # (lower-left, where the curves don't go).
+    ax.legend(title="treatment markets", loc="lower left", framealpha=0.95, ncol=2,
+              fontsize=9)
+    ax.margins(x=0.12)  # room for the right-edge endpoint labels
 
-    # Panel 2: heatmap of MDE over (n_geos × test_len) at primary alpha.
+    # ---- Panel 2: MDE heatmap (red = worse, green = better), readable text. ----
     ax2 = fig.add_subplot(gs[1, 0])
     grid_mde = _np.full((len(grid.n_geos_options), len(grid.test_lengths)), _np.nan)
     for i, ng in enumerate(grid.n_geos_options):
@@ -595,23 +701,34 @@ def _plot_scenarios(grid: "_ScenarioGrid", path):
             r = by.get((a0, tl, ng))
             if r and r["mde_pct"] is not None:
                 grid_mde[i, k] = 100 * r["mde_pct"]
-    im = ax2.imshow(grid_mde, aspect="auto", cmap="viridis_r", origin="lower")
+    cmap = plt.get_cmap("RdYlGn_r").copy()
+    cmap.set_bad("#e5e7eb")  # grey for un-powered cells
+    finite = grid_mde[_np.isfinite(grid_mde)]
+    vmin = float(finite.min()) if finite.size else 0.0
+    vmax = float(finite.max()) if finite.size else 1.0
+    im = ax2.imshow(grid_mde, aspect="auto", cmap=cmap, origin="lower",
+                    vmin=vmin, vmax=vmax)
     ax2.set_xticks(range(len(grid.test_lengths)))
     ax2.set_xticklabels(grid.test_lengths)
     ax2.set_yticks(range(len(grid.n_geos_options)))
     ax2.set_yticklabels(grid.n_geos_options)
     ax2.set_xlabel("test length")
     ax2.set_ylabel("number of geos")
-    ax2.set_title("MDE (%) heatmap", fontweight="bold")
+    ax2.set_title("Detectable lift (%) by design", fontweight="bold")
+    span = (vmax - vmin) or 1.0
     for i in range(grid_mde.shape[0]):
         for k in range(grid_mde.shape[1]):
-            if not _np.isnan(grid_mde[i, k]):
-                ax2.text(k, i, f"{grid_mde[i, k]:.1f}", ha="center", va="center",
-                         color="white", fontsize=8)
-    fig.colorbar(im, ax=ax2, fraction=0.046, pad=0.04, label="MDE %")
-
-    # Panel 3: alpha sensitivity for the recommended (test_len, n_geos), or — if
-    # only one alpha — confidence vs test length by #geos.
+            v = grid_mde[i, k]
+            if not _np.isnan(v):
+                r_, g_, b_, _ = cmap((v - vmin) / span)
+                lum = 0.299 * r_ + 0.587 * g_ + 0.114 * b_
+                ax2.text(k, i, f"{v:.1f}", ha="center", va="center",
+                         color="black" if lum > 0.55 else "white",
+                         fontsize=10, fontweight="bold")
+    fig.colorbar(im, ax=ax2, fraction=0.046, pad=0.04).set_label(
+        "MDE (%) — greener is better", fontsize=9)
+
+    # ---- Panel 3: alpha sensitivity (recommended spec), else confidence. ----
     ax3 = fig.add_subplot(gs[1, 1])
     if len(grid.alphas) > 1 and rec is not None:
         xs, ys = [], []
@@ -620,14 +737,17 @@ def _plot_scenarios(grid: "_ScenarioGrid", path):
             if r and r["mde_pct"] is not None:
                 xs.append(a)
                 ys.append(100 * r["mde_pct"])
-        ax3.plot(xs, ys, "o-", color=_PK_BLUE, lw=2.0)
+        ax3.plot(xs, ys, "o-", color=_PK_BLUE, lw=2.6, markersize=7)
+        for xa, ya in zip(xs, ys):
+            ax3.annotate(f"{ya:.1f}%", (xa, ya), textcoords="offset points",
+                         xytext=(0, 8), ha="center", fontsize=9)
         ax3.set_xlabel("significance level α")
-        ax3.set_ylabel("MDE (%)")
-        ax3.set_title(f"Alpha sensitivity  ({rec['n_geos']}g × {rec['test_len']}p)",
+        ax3.set_ylabel("min. detectable lift (%)")
+        ax3.set_title(f"Looser α → smaller MDE  ({rec['n_geos']}g × {rec['test_len']}p)",
                       fontweight="bold")
+        ax3.margins(x=0.15, y=0.2)
     else:
-        cmap = plt.get_cmap("viridis")
-        for j, ng in enumerate(grid.n_geos_options):
+        for ng in grid.n_geos_options:
             xs, ys = [], []
             for tl in grid.test_lengths:
                 r = by.get((a0, tl, ng))
@@ -635,19 +755,113 @@ def _plot_scenarios(grid: "_ScenarioGrid", path):
                     xs.append(tl)
                     ys.append(r["confidence"])
             if xs:
-                ax3.plot(xs, ys, "o-", lw=1.8, markersize=4,
-                         color=cmap(j / max(1, len(grid.n_geos_options) - 1)),
-                         label=f"{ng} geos")
-        ax3.axhline(grid.min_confidence, ls=":", color="#dc2626", lw=1.0,
+                ax3.plot(xs, ys, "o-", lw=2.2, markersize=6,
+                         color=color_for[ng], label=f"{ng} geos")
+        ax3.axhline(grid.min_confidence, ls=":", color="#dc2626", lw=1.2,
                     label="min confidence")
         ax3.set_xlabel("test length")
-        ax3.set_ylabel("design confidence")
-        ax3.legend(fontsize=7, framealpha=0.9)
+        ax3.set_ylabel("design confidence (0–100)")
+        ax3.legend(fontsize=8, framealpha=0.95)
         ax3.set_title("Design confidence by spec", fontweight="bold")
     ax3.grid(True, alpha=0.25)
 
-    fig.suptitle("panelkit · specification tradeoffs", fontsize=13, fontweight="bold",
-                 x=0.01, ha="left")
+    fig.suptitle("panelkit · specification tradeoffs", fontsize=14, fontweight="bold",
+                 x=0.012, ha="left")
+    if path:
+        fig.savefig(path, dpi=150, bbox_inches="tight")
+    return fig
+
+
+def _plot_guardrails(rep: "_DiagnosticsReport", path):
+    _, plt = _require_mpl()
+    import numpy as _np
+    from matplotlib.gridspec import GridSpec
+
+    d = rep._raw
+    t0 = rep.t0
+    T = len(rep.treated_series)
+    x = _np.arange(T)
+
+    plt.rcParams.update({"font.size": 11, "axes.titlesize": 12})
+    fig = plt.figure(figsize=(12, 7.8))
+    fig.patch.set_facecolor("white")
+    gs = GridSpec(2, 2, figure=fig, height_ratios=[1.0, 1.0], hspace=0.40, wspace=0.26)
+
+    # ---- A: pre-period fit — treated vs synthetic control. ----
+    ax = fig.add_subplot(gs[0, :])
+    ax.axvspan(t0 - 0.5, T - 0.5, color="#dbeafe", alpha=0.5, label="test window")
+    ax.plot(x, rep.treated_series, color="#111827", lw=2.2, label="treated (actual)")
+    if _np.isfinite(rep.synthetic).all():
+        ax.plot(x, rep.synthetic, color="#2563eb", lw=2.0, ls="--",
+                label="synthetic control")
+    ax.axvline(t0 - 0.5, color="#374151", lw=1.0, ls=":")
+    fit_word = "good" if d.pre_fit_rel < 0.25 else "fair" if d.pre_fit_rel < 0.5 else "weak"
+    fit_color = "#059669" if d.pre_fit_rel < 0.25 else "#d97706" if d.pre_fit_rel < 0.5 else "#dc2626"
+    ax.set_title("Pre-period fit: does the synthetic control track the treated markets?",
+                 fontweight="bold")
+    ax.set_xlabel("period")
+    ax.set_ylabel("outcome")
+    ax.grid(True, alpha=0.25)
+    ax.legend(loc="upper left", framealpha=0.95, fontsize=9)
+    ax.annotate(f"pre-fit: {fit_word}  (rel. RMSPE {d.pre_fit_rel:.2f})",
+                xy=(0.99, 0.04), xycoords="axes fraction", ha="right",
+                color=fit_color, fontweight="bold", fontsize=10)
+
+    # ---- B: seasonality — ACF of pre-period first differences. ----
+    axb = fig.add_subplot(gs[1, 0])
+    pre = rep.treated_series[:t0]
+    dd = _np.diff(pre)
+    dd = dd - dd.mean()
+    denom = (dd ** 2).sum()
+    max_lag = int(min(len(dd) // 2, 26))
+    lags = list(range(1, max(max_lag, 2)))
+    acf = [float((dd[lag:] * dd[:-lag]).sum() / denom) if denom > 0 else 0.0 for lag in lags]
+    best_lag = lags[int(_np.argmax(acf))] if acf else 0
+    colors = ["#dc2626" if (lg == best_lag and d.seasonality_strength > 0.3) else "#93c5fd"
+              for lg in lags]
+    axb.bar(lags, acf, color=colors)
+    axb.axhline(0, color="#374151", lw=0.8)
+    axb.set_xlabel("lag (periods)")
+    axb.set_ylabel("autocorrelation")
+    seas_word = ("strong" if d.seasonality_strength > 0.5 else
+                 "some" if d.seasonality_strength > 0.3 else "weak")
+    title = f"Seasonality: {seas_word} (strength {d.seasonality_strength:.2f})"
+    if d.seasonality_strength > 0.3 and best_lag:
+        title += f", ≈{best_lag}-period cycle"
+    axb.set_title(title, fontweight="bold")
+    axb.grid(True, axis="y", alpha=0.25)
+
+    # ---- C: holdout share. ----
+    axc = fig.add_subplot(gs[1, 1])
+    h = d.holdout_pct
+    in_band = 0.03 <= h <= 0.35
+    bar_color = "#059669" if in_band else "#d97706"
+    axc.barh([0], [100 * h], color=bar_color, height=0.5, label="treated")
+    axc.barh([0], [100 * (1 - h)], left=[100 * h], color="#e5e7eb", height=0.5,
+             label="control / donors")
+    axc.axvspan(3, 35, color="#bbf7d0", alpha=0.35)  # healthy band
+    axc.set_xlim(0, 100)
+    axc.set_yticks([])
+    axc.set_xlabel("% of total volume")
+    axc.set_title(f"Holdout: treated = {100*h:.1f}% of volume "
+                  f"({'healthy' if in_band else 'check'})", fontweight="bold")
+    axc.annotate(f"{100*h:.1f}%", (100 * h / 2, 0), ha="center", va="center",
+                 color="white", fontweight="bold")
+    axc.legend(loc="lower right", fontsize=8, framealpha=0.95)
+    axc.annotate("healthy 3–35%", (19, 0.32), ha="center", color="#15803d", fontsize=8)
+
+    # ---- Warnings / verdict banner across the bottom. ----
+    warns = list(d.warnings)
+    if warns:
+        txt = "⚠ Guardrail warnings:\n" + "\n".join(f"  • {w}" for w in warns)
+        box = dict(boxstyle="round,pad=0.5", fc="#fef3c7", ec="#d97706")
+    else:
+        txt = "✓ No guardrail warnings — design looks clean."
+        box = dict(boxstyle="round,pad=0.5", fc="#dcfce7", ec="#059669")
+    fig.text(0.012, -0.02, txt, ha="left", va="top", fontsize=9, bbox=box, wrap=True)
+
+    fig.suptitle(f"panelkit · guardrails — confidence {d.confidence:.0f}/100",
+                 fontsize=14, fontweight="bold", x=0.012, ha="left")
     if path:
         fig.savefig(path, dpi=150, bbox_inches="tight")
     return fig