Merge pull request #373 from igerber/dcdh-tutorial

Add Tutorial 19: dCDH for Marketing Pulse Campaigns

Author: igerber

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - **`ChaisemartinDHaultfoeuille.by_path` + `placebo=True`** — per-path backward-horizon placebos `DID^{pl}_{path, l}` for `l = 1..L_max`. The same per-path SE convention used for the event-study (joiners/leavers IF precedent: switcher-side contributions zeroed for non-path groups; cohort structure and control pool unchanged; plug-in SE with path-specific divisor `N^{pl}_{l, path}`) is applied to backward horizons via the new `switcher_subset_mask` parameter on `_compute_per_group_if_placebo_horizon`. Surfaced on `results.path_placebo_event_study[path][-l]` (negative-int inner keys mirroring `placebo_event_study`); `summary()` renders the rows alongside per-path event-study horizons; `to_dataframe(level="by_path")` emits negative-horizon rows alongside the existing positive-horizon rows. **Bootstrap** (when `n_bootstrap > 0`) propagates per-`(path, lag)` percentile CI / p-value through the same `_bootstrap_one_target` dispatch as the per-path event-study, with the canonical NaN-on-invalid contract enforced on the new surface (PR #364 library-wide invariant). **SE inherits the cross-path cohort-sharing deviation from R** documented for `path_effects` (full-panel cohort-centered plug-in vs R's per-path re-run): tracks R within tolerance on single-path-cohort panels, diverges materially on cohort-mixed panels — the bootstrap SE is a Monte Carlo analog of the analytical SE and inherits the same deviation. R-parity confirmed at `tests/test_chaisemartin_dhaultfoeuille_parity.py::TestDCDHDynRParityByPathPlacebo` on the new `multi_path_reversible_by_path_placebo` scenario (point estimates exact match; SE within Phase-2 envelope rtol ≤ 5%); positive analytical + bootstrap invariants at `tests/test_chaisemartin_dhaultfoeuille.py::TestByPathPlacebo` (and the gated `::TestBootstrap` subclass). See `docs/methodology/REGISTRY.md` §ChaisemartinDHaultfoeuille `Note (Phase 3 by_path ...)` → "Per-path placebos" for the full contract.
+- **Tutorial 19: dCDH for Marketing Pulse Campaigns** (`docs/tutorials/19_dcdh_marketing_pulse.ipynb`) — end-to-end practitioner walkthrough on a 60-market reversible-treatment panel covering the TWFE decomposition diagnostic (`twowayfeweights`), `DCDH` Phase 1 (DID_M, joiners-vs-leavers, single-lag placebo), the `L_max` multi-horizon event study with multiplier bootstrap, a stakeholder communication template, and drift guards. README listing for Tutorial 17 (Brand Awareness Survey) backfilled in the same edit. Cross-link from `docs/practitioner_decision_tree.rst` § "Reversible Treatment" added.
 
 ## [3.3.0] - 2026-04-25
 

docs/doc-deps.yaml

@@ -280,6 +280,8 @@ sources:
       - path: docs/practitioner_decision_tree.rst
         section: "Reversible Treatment"
         type: user_guide
+      - path: docs/tutorials/19_dcdh_marketing_pulse.ipynb
+        type: tutorial
       - path: ROADMAP.md
         section: "de Chaisemartin-D'Haultfœuille (dCDH) Estimator"
         type: roadmap

docs/practitioner_decision_tree.rst

@@ -205,6 +205,14 @@ a joiners-only view `DID_+`, and a leavers-only view `DID_-`.
    influence-function derivation for the single-lag placebo is a planned
    extension. Dynamic placebos (``L_max >= 1``) do have valid analytical SE.
 
+.. tip::
+
+   For a full walkthrough on a marketing-pulse panel - including the TWFE
+   decomposition diagnostic, joiners-vs-leavers reading, multi-horizon event
+   study with multiplier bootstrap, and a stakeholder communication template,
+   see `Tutorial 19: dCDH Marketing Pulse Campaigns
+   <tutorials/19_dcdh_marketing_pulse.ipynb>`_.
+
 
 .. _section-dose: