Add Tutorial 20: HAD for National Brand Campaign with Regional Spend Intensity

Practitioner walkthrough for HeterogeneousAdoptionDiD on the
no-untreated-controls case: every market got the campaign at varying
intensity and there is no clean comparison group. Fills the structural
gap T14 (ContinuousDiD) cannot address.

Notebook scope (23 cells, 13 markdown / 10 code, mirrors T19's
structure):
- Sections 1-3: framing the no-untreated-controls measurement problem,
  setup imports, synthetic 60-DMA / 8-week panel with Uniform[$5K, $50K]
  regional add-on spend (every DMA participates, no DMA at $0). DGP
  is internally consistent: outcomes are generated from the dose
  values HAD then sees, no post-hoc relabeling.
- Section 4: overall WAS_d_lower fit on a 2-period (pre/post mean)
  collapse - HAD's overall mode requires exactly 2 periods
  (had.py:952-959). Locked headline: per-$1K marginal effect of 100
  weekly visits per DMA above the boundary spend (95% CI [98.6,
  101.4]) with design auto-detection landing on
  `continuous_near_d_lower` (Design 1) and target `WAS_d_lower`.
  Surfaces the Assumption 5/6 advisory the library fires for Design 1
  and explains why it holds in this DGP (linear by construction).
- Section 5: multi-week event-study fit on the 8-week panel,
  per-week WAS_d_lower for e=0..3 (~100 each, CIs cover truth) and
  pre-launch placebos at e=-2..-4 sitting on zero.
- Section 6: stakeholder communication template (T18/T19 markdown
  blockquote pattern), per-DMA dollar-lift interpretation
  `(actual_dose - d_lower) * WAS_d_lower`, Assumption 6 caveat.
- Section 7: extensions (population-weighted/survey path, composite
  pretest workflow described accurately as QUG support-infimum test
  + linearity tests, mass-point design path), related-tutorials
  cross-links (T01, T02, T14, T17, T18, T19), summary checklist.

Drift detection: companion tests/test_t20_had_brand_campaign_drift.py
(13 tests, 0.06s, mirrors T19's test-file-only pattern - T19's
notebook itself has zero in-notebook asserts). Pins panel composition
including sample median, design auto-detection / target / d_lower,
overall WAS_d_lower / SE / CI endpoints to one-decimal display, dose
mean, n_units, full event-study horizon presence (e=-4..-2, 0..3),
per-week post-launch coverage of TRUE_SLOPE=100 and zero coverage at
every placebo horizon (|placebo_att| < 0.1). Tight `round(_, 1) == X.X`
pins throughout - HAD's analytical SE path is bit-identical regardless
of backend env (no Rust kernel involved). Locked DGP seed: MAIN_SEED=87.

Documentation integration:
- docs/tutorials/README.md: new T20 entry following T18/T19's
  5-bullet pattern.
- docs/doc-deps.yaml: T20 added to the existing diff_diff/had.py
  entry; cross-link to docs/practitioner_decision_tree.rst added.
- docs/practitioner_decision_tree.rst: `.. tip::` block at the end
  of `section-no-untreated` (Universal Rollout - landed on main via
  PR #389) cross-links to T20 for the full walkthrough.
- CHANGELOG.md: new ### Added bullet under [Unreleased].

Out of scope (queued in project_had_followups.md memory):
- _handle_had in practitioner.py:_HANDLERS map.
- HAD entries in llms-full.txt / choosing_estimator.rst.
- Pretest workflow tutorial, weighted/survey HAD tutorial,
  mass-point design demo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Tutorial 20: HAD for National Brand Campaign with Regional Spend Intensity** (`docs/tutorials/20_had_brand_campaign.ipynb`) — end-to-end practitioner walkthrough for `HeterogeneousAdoptionDiD` on a 60-DMA panel where every market got the campaign at varying intensity and no untreated comparison group exists. The DGP uses Uniform[\$5K, \$50K] regional add-on spend per DMA (every DMA participates, no DMA at exactly \$0), so `design="auto"` resolves to `continuous_near_d_lower` (Design 1) with target `WAS_d_lower` — interpreted as the average per-dollar marginal effect of regional spend above the lightest-touch DMA's spend (`d_lower` ≈ \$5K). Covers the headline `WAS_d_lower` fit on a 2-period collapse, the multi-week event study with per-week pointwise CIs and pre-launch placebos, and a stakeholder communication template that flags the Assumption 5/6 caveat (non-testable local-linearity at the boundary). Companion drift-test file `tests/test_t20_had_brand_campaign_drift.py` (13 tests pinning panel composition / sample median, design auto-detection / target / `d_lower`, overall `WAS_d_lower`, CI endpoints, dose mean, n_units, full event-study horizon presence, and per-horizon coverage). T20 wired into the existing `had.py` entry in `docs/doc-deps.yaml`; cross-link added from `docs/practitioner_decision_tree.rst` § "Universal Rollout (No Untreated Markets)" via a `.. tip::` block.
+
 ### Changed
 - **Rust dependency upgrades**: bumped `rand` 0.8 → 0.10 and `rand_xoshiro` 0.6 → 0.8 in the Rust backend (the two crates are coupled through `rand_core` and must move together). MSRV bumped from Rust 1.84 → 1.85 to satisfy the new dependency requirements. Three call sites in `rust/src/bootstrap.rs` updated for the `rand 0.9` API rename: `gen::<bool>()` → `random::<bool>()`, `gen::<f64>()` → `random::<f64>()`, `gen_range(0..6)` → `random_range(0..6)`. **Webb wild bootstrap byte stream shifted** as a side effect: `rand 0.9` reworked the internal algorithm for `random_range` (improved rejection sampling), so `Xoshiro256PlusPlus::seed_from_u64(seed)` followed by `random_range(0..6)` consumes RNG bytes differently than the old `gen_range(0..6)` did. Distributional properties of Webb weights are unchanged (still uniform over the 6-point support); aggregate inference (SE, p-values, CI) converges to the same values for any reasonable `n_bootstrap`. Rademacher and Mammen byte streams are bit-identical to the prior release. Anyone with a saved Rust+Webb baseline pinning specific seeded results will see different numbers; the regression test suite uses within-build seed-reproducibility (not cross-version baselines) so all internal tests pass unchanged. New regression guard `TestRustBackend::test_bootstrap_weights_bit_identity_snapshot` pins fixed-seed weights for all three weight types, so any future RNG drift fails loudly with a localized error message.
 

docs/doc-deps.yaml

@@ -371,6 +371,8 @@ sources:
         type: methodology
       - path: docs/api/had.rst
         type: api_reference
+      - path: docs/tutorials/20_had_brand_campaign.ipynb
+        type: tutorial
       - path: README.md
         section: "Estimators (one-line catalog entry)"
         type: user_guide
@@ -379,6 +381,10 @@ sources:
       - path: diff_diff/guides/llms.txt
         section: "Estimators"
         type: user_guide
+      - path: docs/practitioner_decision_tree.rst
+        section: "Universal Rollout (No Untreated Markets)"
+        type: user_guide
+        note: "Tip cross-link to T20 in the no-untreated section"
       # Note: llms-full.txt does not yet have a HeterogeneousAdoptionDiD section
       # (deferred to TODO.md Phase 5 follow-up); the dependency mapping will be
       # added when that section lands.

docs/practitioner_decision_tree.rst

@@ -310,6 +310,13 @@ identification rests on stronger structural assumptions (Design 1).
    :doc:`api/had` for the inference contract (three SE regimes; pointwise CIs;
    sup-t bands only on the weighted event-study path).
 
+.. tip::
+
+   For a full walkthrough including data setup, the design auto-detection
+   diagnostic, the multi-week event study, and a stakeholder communication
+   template, see `Tutorial 20: HAD for National Brand Campaign with Regional
+   Spend Intensity <tutorials/20_had_brand_campaign.ipynb>`_.
+
 
 .. _section-few-markets: