Implement exact Appendix F pre-treatment DR estimand; expand help documentation

[gorgeousfish]

Summary

The pretrend branch now implements the pre-treatment doubly robust estimand of Imai, Qin & Yanagi (2026, Appendix F) exactly, instead of reusing the post-treatment formula over pre-treatment (g,t) pairs.

• New didhetero_comp_threshold_ord(g, t, delta, t_vals) in mata/didhetero_utils_domain.mata: returns t_ord + delta for post-treatment pairs but g_ord + delta for pre-treatment pairs (t < g - delta), anchoring the not-yet-treated comparison pool at t = g (R_{g,g} instead of R_{g,t}) so cohorts treated within the pre-trend window are excluded from both the GPS and OR samples.
• didhetero_gps.mata, didhetero_or.mata, didhetero_intermediate.mata all call this helper, keeping the three nuisance modules consistent.
• didhetero_pair_in_domain (pretrend branch): always drops the base period t = g-delta-1 (zero by construction); for pre-treatment pairs under notyettreated without a never-treated cohort, admits a pair only when gbar > g + delta so a comparison pool exists.
• ado/catt_gt.sthlp: pretrend documents the Appendix F implementation; biters() documents the (B+1)*alpha convention (e.g. biters(999) with alp(0.05)); zeval() documents that grids much narrower than the sample support of z shrink the analytical uniform band.

Estimates for pre-treatment pairs change only in designs where an intermediate cohort is treated inside the pre-trend window; post-treatment estimates are unchanged. Needs verification on Stata (no Stata on this machine); the same change is vendored in gorgeousfish/sjdidhetero PR #1, whose replication scripts exercise it.

---

Requested by: dlgiuxqnkj (dlgiuxqnkj@outlook.com)
Devin session: https://app.devin.ai/sessions/3764940bd621427aaf490b3bccdca47c

---

Summary by cubic

Implements the exact Appendix F pre-treatment doubly robust estimand by anchoring the not‑yet‑treated comparison at t = g for pre‑treatment (g,t) pairs. Only pre‑treatment estimates change when a cohort is treated inside the pre‑trend window; post‑treatment estimates are unchanged.

• New Features
  • New helper didhetero_comp_threshold_ord: uses t+delta for post‑treatment pairs, g+delta for pre‑treatment pairs.
  • GPS, OR, and intermediate modules now call this helper for consistent comparison pools.
  • didhetero_pair_in_domain: always drops the base period t = g−delta−1; for pre‑treatment pairs with notyettreated and no never‑treated group, admits only when gbar > g+delta.
  • Help updates: pretrend now documents the Appendix F estimator; biters() notes the (B+1)*alpha convention (e.g., biters(999) with alp(0.05)); zeval() notes that narrow grids shrink analytical uniform bands.

^{Written for commit 781246f. Summary will update on new commits.}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[cubic-dev-ai]

1 issue found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="mata/didhetero_utils_domain.mata">

<violation number="1" location="mata/didhetero_utils_domain.mata:157">
P1: With `pretrend control_group(notyettreated)` and no never-treated cohort, late post-treatment pairs can still be admitted even when no not-yet-treated controls exist. The fallback `return(1)` bypasses the same `gbar` support check used by the normal post-treatment domain, so these pairs can fail later in GPS/OR estimation instead of being excluded.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: With pretrend control_group(notyettreated) and no never-treated cohort, late post-treatment pairs can still be admitted even when no not-yet-treated controls exist. The fallback return(1) bypasses the same gbar support check used by the normal post-treatment domain, so these pairs can fail later in GPS/OR estimation instead of being excluded.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At mata/didhetero_utils_domain.mata, line 157:

<comment>With `pretrend control_group(notyettreated)` and no never-treated cohort, late post-treatment pairs can still be admitted even when no not-yet-treated controls exist. The fallback `return(1)` bypasses the same `gbar` support check used by the normal post-treatment domain, so these pairs can fail later in GPS/OR estimation instead of being excluded.</comment>

<file context>
@@ -121,7 +147,14 @@ real scalar didhetero_pair_in_domain(
+            if (gbar_ord >= .) return(0)
+            return(gbar_ord > g_ord + anticipation)
+        }
+        return(1)
     }
 
</file context>

Suggested change

	return(1)
	if (control_group == "nevertreated") {
	return(has_never)
	}
	if (control_group == "notyettreated") {
	if (has_never) return(1)
	gbar_ord = didhetero_period_ord(gbar, t_vals)
	if (gbar_ord >= .) return(0)
	return(t_ord < gbar_ord - anticipation)
	}
	_error(198, "Invalid control_group: " + control_group)
	return(0)