Specify an IV DGP: endogenous focal, control-function probit

Power analysis when the focal variable is endogenous and the study will use instrumental variables via the control-function approach – the estimator of Stata's cfprobit (replicated exactly, including its stacked method-of-moments standard errors; no bootstrap). A continuous focal gets a linear first stage, a binary focal a probit first stage; the control function (first-stage residual or generalized residual) joins the second-stage probit, whose coefficients margins-style ASF averaging turns back into the APE/AIE.

Usage

ape_dgp_iv(
  focal,
  moderator = NULL,
  covariates = list(),
  instruments,
  endogeneity,
  iv_strength,
  correlation = NULL,
  baseline,
  signal = 0,
  n_int = 1e+05,
  seed_int = 20260814L
)

Arguments

focal: pa_var(), "normal" (linear first stage) or "binary" (probit first stage). The endogenous variable.
moderator: Optional binary pa_var() for AIE designs.
covariates: List of pa_var() objects (may be empty).
instruments: A pa_var() or list of them: the excluded instruments. Equal standardized first-stage weights.
endogeneity: Correlation of the structural and first-stage errors (u, v) – the reason plain probit would be biased. In (-1, 1).
iv_strength: First-stage strength: the share of the focal's variance (latent variance for a binary focal) explained by the instruments. In (0, 1); small values mean weak instruments.
correlation: Dependence among the exogenous block (moderator, covariates, instruments): scalar exchangeable correlation or a matrix. The focal is generated by the first stage, not drawn.
baseline: Baseline outcome rate in (0, 1): the average probability P(Y = 1) with the focal (and moderator, if any) set to their reference values (0 for binary, the mean for continuous), covariates at their population distribution. The intercept is calibrated to reproduce it.
signal: Nuisance-signal strength: the share of the latent-index variance due to the nuisance covariates, Var(z'gamma) / (Var(z'gamma) + 1), with the latent error variance fixed at 1 under both links. Under probit this is the covariates' McKelvey-Zavoina R-squared. Under logit the latent error variance is pi^2/3, so the same signal describes a weaker world: with s2 = signal / (1 - signal), the covariates' McKelvey-Zavoina R-squared on the logistic scale is s2 / (s2 + pi^2/3) (0.033 at signal = 0.10, 0.115 at 0.30). To match an R-squared R2 read off a logit pilot, use s2 = R2 * (pi^2/3) / (1 - R2) and signal = s2 / (1 + s2). Equal standardized weights, scaled to hit signal. Ignored when gamma is supplied.
n_int, seed_int: Size and seed of the deterministic Monte Carlo integration draw used for calibration and inversion.

Value

An object of class powerape_dgp (route "iv"). Pin the effect with set_ape() or, with a moderator, set_aie().

Details

The estimand is unchanged: the ASF-based APE of the focal (or the AIE with a binary exogenous moderator). Because the structural error is standard normal marginally, targets, feasibility, and truth evaluation work exactly as in ape_dgp().

Two documented properties of the control-function estimator (validation battery V13-V15): (1) for a binary endogenous focal the generalized residual is the standard Wooldridge approximation, with a small negative bias (about -0.01 at endogeneity = 0.4, iv_strength = 0.2) that makes the directional detect claim conservative at the null (empirical size ~1.6% against the nominal 2.5%; the standard errors themselves are correctly calibrated); (2) for a continuous endogenous focal, the margins convention (control functions held at observed values) evaluates the ASF over the observed (focal, residual) pairs, which understates the product-measure ASF slightly (about -0.005 on a 0.08 effect at endogeneity = 0.5, iv_strength = 0.3) because the focal and its residual are correlated by construction. powerape replicates the field-standard (cfprobit/margins) convention exactly; a product-measure ASF option is on the roadmap.

For AIE designs the estimating model includes the focal-by-moderator term, the control function, and the control-function-by-moderator interaction (Stata: interact() + mainonly()); the first stage includes the moderator and the instrument-by-moderator interactions – the general IV requirement for interaction models. Inference is robust (stacked sandwich) throughout.

Examples

# \donttest{
d <- ape_dgp_iv(
  focal = pa_var("training", "binary", p = 0.4),
  covariates = list(pa_var("size", "normal")),
  instruments = pa_var("subsidy", "binary", p = 0.5),
  endogeneity = 0.4, iv_strength = 0.2,
  baseline = 0.30, signal = 0.10
)
d <- set_ape(d, target = 0.10)
ape_power(d, n = 1500, claim = "detect", nsim = 300, seed = 1)
#> powerape -- detection claim (CI excludes 0, directional)
#>   probit, n = 1500, assumed true APE +0.1000, 95% CI (alpha = 0.05), nsim = 300, stacked robust SEs
#>   power = 0.220 (MCSE 0.024)
#>   outcomes: detect 0.220 | inconclusive 0.780 | failed 0.000 
# }