Fix latent doc-snippet bugs from PR igerber#389 (HAD ecosystem)

PR igerber#389 added HAD code snippets to choosing_estimator.rst,
troubleshooting.rst, and r_comparison.rst. None of those edits
triggered rust-test.yml (which only runs on rust/, diff_diff/, tests/,
pyproject.toml, and the workflow file), so tests/test_doc_snippets.py
never executed and the snippets shipped with five latent bugs that now
surface on every code PR via the Pure Python Fallback job.

Bugs addressed:

- r_comparison:block6 — bare HAD.fit(data, ...) with the
  generate_staggered_data fixture failed because the default
  aggregate='overall' requires exactly 2 periods and the namespace
  data has 10. Replaced with an inline HAD-shape panel construction
  (mirrors the upstream choosing_estimator:block7 fix in 55d7a27)
  plus aggregate='event_study'.

- troubleshooting:block20 — the snippet demonstrates
  first_treat_col= auto-filtering on a staggered panel. The fixture's
  first_treat values disagree with the dose path (random per-row dose
  on never-treated units), tripping HAD's first_treat / dose-path
  consistency validator. Inlined a 120-unit / 10-period staggered
  HAD-shape panel (30 never + 30 cohort 5 + 60 cohort 8) so the
  validator passes and the boundary local-linear estimator has
  enough distinct dose values to fit.

- troubleshooting:block17 / block18 / r_comparison:block7 — these are
  legitimately context-dependent snippets that reference est /
  results from prior text-flow context (inspection / output-format
  examples). Added them to _CONTEXT_DEPENDENT_SNIPPETS so the
  expected NameError is suppressed, matching the pattern already
  used for block8, the api_bacon blocks, and the existing
  r_comparison context-dependent set.

choosing_estimator:block7 was the sixth failing snippet but was
already fixed upstream in 55d7a27 with the inline-construction
pattern; this branch rebases onto that.

Verification: PYTHONPATH=. DIFF_DIFF_BACKEND=python pytest
tests/test_doc_snippets.py reports 111 passed, 4 skipped, 0 failed
on this branch (was 6 failed on origin/main before 55d7a27 and 5
failed after).

Follow-up (separate PR queued): carve test_doc_snippets.py out into a
dedicated docs-tests.yml workflow triggered on docs/** + diff_diff/**
+ the test file itself, and exclude it from rust-test.yml's pytest
invocations so doc bugs are caught on doc PRs (not silently inherited
by code PRs).

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

Author: igerber

docs/r_comparison.rst

@@ -237,11 +237,28 @@ identification assumptions (the design path is auto-detected separately by
 
 .. code-block:: python
 
+   import numpy as np
+   import pandas as pd
    from diff_diff import HeterogeneousAdoptionDiD
 
+   # Build a HAD-shape panel: D=0 in pre-periods (t < F), D > 0 only at F+.
+   rng = np.random.default_rng(42)
+   G, F, T = 200, 4, 5
+   doses = rng.beta(0.5, 1.0, size=G)
+   rows = []
+   for g in range(G):
+       for t in range(1, T + 1):
+           y = (rng.normal()
+                + (doses[g] + doses[g] ** 2) * (t >= F)
+                + rng.normal(0, 0.5))
+           d = doses[g] if t >= F else 0.0
+           rows.append({'unit': g, 'period': t, 'y': y, 'dose': d})
+   had_data = pd.DataFrame(rows)
+
    est = HeterogeneousAdoptionDiD()
-   results = est.fit(data, outcome_col='y', unit_col='unit',
-                     time_col='period', dose_col='dose')
+   results = est.fit(had_data, outcome_col='y', unit_col='unit',
+                     time_col='period', dose_col='dose',
+                     aggregate='event_study')
 
 Key Differences
 ---------------

docs/troubleshooting.rst

@@ -593,6 +593,30 @@ a ``UserWarning``). The fit raises only when the panel is staggered
 
 .. code-block:: python
 
+   import numpy as np
+   import pandas as pd
+
+   # Build a staggered HAD panel for this example: 120 units, three
+   # cohorts (30 never-treated + 30 treated at period 5 + 60 treated at
+   # period 8). Dose is zero pre-treatment per unit and a constant
+   # positive value post-treatment, so the first_treat / dose-path
+   # consistency validator passes. The 60-unit last cohort gives the
+   # boundary local-linear estimator enough distinct dose values to fit.
+   np.random.seed(42)
+   n_units, n_periods = 120, 10
+   first_treat_per_unit = np.array([0] * 30 + [5] * 30 + [8] * 60)
+   dose_per_unit = np.where(
+       first_treat_per_unit > 0, np.random.uniform(0.5, 2.0, n_units), 0.0
+   )
+   rows = []
+   for u in range(n_units):
+       ft = first_treat_per_unit[u]
+       for t in range(n_periods):
+           d_ut = dose_per_unit[u] if (ft > 0 and t >= ft) else 0.0
+           y_ut = (d_ut > 0) * dose_per_unit[u] * 0.5 + np.random.normal()
+           rows.append((u, t, d_ut, ft, y_ut))
+   data = pd.DataFrame(rows, columns=["unit", "period", "dose", "first_treat", "y"])
+
    # Primary remedy: pass `first_treat_col` so the estimator auto-filters
    # to the last-treatment cohort + never-treated and emits a UserWarning.
    est = HeterogeneousAdoptionDiD()

tests/test_doc_snippets.py

@@ -366,7 +366,10 @@ def _restore_datasets_module():
     "r_comparison:block3",
     "r_comparison:block4",
     "r_comparison:block6",
+    "r_comparison:block7",
     "troubleshooting:block8",
+    "troubleshooting:block17",
+    "troubleshooting:block18",
 }