Sensitivity analysis for a binary-outcome instrumental-variables model in the spirit of Conley, Hansen and Rossi (2012). The exclusion restriction is relaxed to \(y^* = x'\beta + d\delta + z'\gamma + \varepsilon\), and the target is the average partial effect (APE) of each endogenous regressor (or an average interaction effect, AIE) on the probability scale, estimated by a control-function probit (two-step standard errors: the Murphy-Topel parameter covariance plus the direct first-stage term) or, for one 0/1 treatment, by a recursive bivariate probit. At every assumed violation \(\gamma\) the model is refit with \(z'\gamma\) as an offset in the outcome index.
Usage
apexog(
formula,
endog,
data,
method = c("uci", "ltz"),
gmin = NULL,
gmax = NULL,
grid = 11,
mu = NULL,
omega = NULL,
prior = "normal",
prior_params = NULL,
draws = NULL,
iterations = 1000,
seed = NULL,
firststage = "linear",
target = NULL,
aie = NULL,
aie_binary = NULL,
cfinteract = FALSE,
gunits = c("latent", "pr", "structural"),
level = 0.95,
cluster = NULL,
subset = NULL,
sweep_omega = NULL,
sweep_mu = NULL,
sweep_delta = NULL,
verbose = TRUE
)Arguments
- formula
Two-sided formula
y ~ x1 + x2with the 0/1 outcome and the exogenous controls (factors and interactions allowed; usey ~ 1for no controls). A constant is always included.- endog
Two-sided formula
d ~ z1 + z2(endogenous regressor(s) on the left, excluded instruments on the right), or a list of such formulas, one per group of endogenous regressors sharing an instrument set (Stata's multi-clause syntax). An endogenous interaction of a treatment with a moderator is written on the left asd + d:x, with its instruments on the right (e.g.d + d:x ~ z + z:x); combine it withaie = c("d", "x").- data
A data frame.
- method
"uci"or"ltz".- gmin, gmax
UCI: lower and upper end of the assumed \(\gamma\) range, one value per instrument or a single value (broadcast).
- grid
UCI: number of grid points per instrument (default 11).
- mu, omega
LTZ, Gaussian prior: mean and variance of each instrument's \(\gamma\) (single values are broadcast).
- prior
LTZ prior.
"normal"(default; usesmuandomegaunlessprior_paramsis given), one of"uniform","chi2","t","gamma","poisson","special"(parameters inprior_params), or a functionfunction(n)returning ann x Kmatrix of draws.- prior_params
List with one parameter vector per instrument (or one, broadcast): normal
c(mean, sd), uniformc(min, max), chi2df, tdf, gammac(shape, scale), poissonmean, special: a numeric donor vector sampled with replacement.- draws
Optional
iterations x Kmatrix of \(\gamma\) draws (ingunits) used instead of a prior, e.g. a joint prior of your own. Passing Stata'se(gamma_sim)(latent units, so with the defaultgunits = "latent") reproduces a Stata LTZ run draw by draw; only the convolution noise then differs.- iterations
LTZ: number of prior draws (default 1000).
- seed
Optional seed passed to
set.seed()before drawing.- firststage
First-stage model:
"linear"(default),"probit"(0/1 regressor, generalized residual),"fprobit"(fractional regressor),"poisson"(count), or"biprobit"(recursive bivariate probit for a single 0/1 regressor; exact under joint normality; its APE, or since 0.22.0 its AIE with an exogenous moderator). A single value applies to every endogenous regressor, including a declared interaction such asd:x(which needs"linear"); otherwise give one value per endogenous regressor, in order of appearance, or a named vector (unnamed regressors default to"linear"), e.g.c(d = "probit").- target
Character vector of endogenous regressors whose APE bounds are reported (default: all).
- aie
Character vector
c(X, Z): switch the target to the average interaction effect ofXandZ. Each must be an exogenous control column or an endogenous regressor (use numeric 0/1 variables, notfactor()). If the productX:Zis a declared endogenous regressor (endog = d + d:x ~ ...) that regressor is the target; otherwise the product is taken fromformulawhen it is written asx:zorx*z, or added as an exogenous control. Do not write it asI(x*z): that is detected as a duplicate and refused. When one interactor is an endogenous regressor in a clause of its own, its control function covers the product (Wooldridge 2015, pp. 428-429, 437), but list the instruments interacted with the moderator in that clause (e.g.endog = d ~ z + z:x): the control function is right only if the first stage lets the instrument's effect differ with the moderator, and the AIE is biased without them whenever it does. Withfirststage = "biprobit"one of the two must be the 0/1 treatment and the other an exogenous moderator; the product then enters only the outcome equation of the joint fit (write the treatment alone inendog, e.g.endog = d ~ z + z:m), and the AIE is the interaction contrast of the average structural function under joint normality.- aie_binary
Logical length-2 vector forcing the type of
XandZ(TRUE= binary,FALSE= continuous,NA= detect from the data). Continuous x continuous gives the cross-partial, continuous x binary the first difference of the slope, binary x binary the second discrete difference.- cfinteract
Add the products of the control functions to the main probit (as
cfprobit'scfinteract). Automatic for a declared endogenous interaction.- gunits
Units of all user-supplied \(\gamma\) values:
"latent"(probit-index units; default),"pr"(probability points, divided by \(m_\phi\), the average density at the baseline fit), or"structural"(structural-latent units, divided by \(\tilde\sigma\); derived for a linear first stage). The structural conversion uses the baseline \(\tilde\sigma\), which is exact only at \(\gamma = 0\). With one continuous endogenous regressor, one instrument and a linear first stage, a structural value has a unique index-scale counterpart only below \(|\pi_z|/\sigma_v\) in absolute value (returned asgs_max);printreports that limit and warns when the UCI box or LTZ prior draws reach it. For a 0/1 regressor with a linear first stage the conversion is not derived andprintwarns of that instead. Results are not changed.- level
Confidence level, as a fraction or a percent (default 0.95).
- cluster
Optional cluster identifier: a one-sided formula (
~ id), a column name, or a vector of lengthnrow(data).- subset
Optional logical expression evaluated in
data. Observations where it isNAare dropped (Stata'siftreats a missing value as+Infand may keep them).- sweep_omega, sweep_mu, sweep_delta
LTZ, Gaussian prior: rerun the simulation for each prior variance in
sweep_omega(meanssweep_mu, default 0; x-axis labelssweep_delta, default the variances) and store the bounds-versus-width table in$sweep.- verbose
Print notes while fitting (default
TRUE).
Value
An object of class "apexog": a list with, among others,
baseline (estimates at \(\gamma = 0\)), bounds (UCI union or
LTZ interval per target), prior_band (LTZ), grid and
grid_pr (UCI), sims (LTZ draws and refit estimates),
mphi, stilde, gs_max (the limit of the structural
scale, NA when not defined), binlin (0/1 endogenous
regressors that got a linear first stage, for which the effect is a
descriptive fitted contrast rather than a causal estimate; print
says so), coefficients and vcov (baseline
targets), and model (the baseline main-equation coefficients with
their Murphy-Topel covariance, or the bivariate-probit coefficients with
their robust MLE covariance). Methods: print, summary, coef, vcov,
confint, plot.
Details
method = "uci"Union of confidence intervals over a grid of assumed \(\gamma\) values (
gmin,gmax,grid).method = "ltz"Local-to-zero: \(\gamma\) is drawn from a prior, the model is refit per draw, and the reported interval is the percentile interval of the refit estimates convolved with their sampling noise (CHR 2012, eq. 7). The prior-only spread is reported as well.
This is an R port of the Stata command apexog (v0.22.0); results agree
with Stata to optimizer tolerance (about 1e-7 relative on the validation
specifications). Random draws differ between R and Stata, so LTZ intervals
agree only in distribution unless the same draws are supplied.
Stata apexog up to v0.20.0 omitted the control-function-product
coefficients from the APE standard error when cfinteract was used
with an APE target (0.02% of the SE in the validation design); v0.20.1 and
this package include them. Since v0.21.0 (Stata and R) the standard error
of every two-step effect also includes the effect's direct dependence on the
estimated first-stage parameters through the control function (influence
function J_beta' psi_beta + J_pi' psi_pi); earlier versions, and
Stata's cfprobit followed by margins, use the first term only.
Point estimates are unchanged; the difference is about 1% of the SE in the
validation designs.
References
Conley, T. G., Hansen, C. B. and Rossi, P. E. (2012). Plausibly exogenous. Review of Economics and Statistics 94(1), 260-272.
Murphy, K. M. and Topel, R. H. (1985). Estimation and inference in two-step econometric models. Journal of Business and Economic Statistics 3(4), 370-379.
Wooldridge, J. M. (2014). Quasi-maximum likelihood estimation and testing for nonlinear models with endogenous explanatory variables. Journal of Econometrics 182(1), 226-234.
Examples
set.seed(1)
n <- 2000
dat <- data.frame(x = rnorm(n), z = rnorm(n), v = rnorm(n))
dat$d <- 0.7 * dat$z + 0.3 * dat$x + dat$v
dat$y <- as.integer(-0.3 + 0.5 * dat$d + 0.4 * dat$x +
0.5 * dat$v + sqrt(0.75) * rnorm(n) > 0)
fit <- apexog(y ~ x, endog = d ~ z, data = dat, method = "uci",
gmin = -0.1, gmax = 0.1, grid = 5)
#> Running UCI grid: 5 point(s) per instrument, 1 instrument(s), 5 total grid point(s).
fit
#> ------------------------------------------------------------------------------
#> Plausibly-exogenous APE bounds (CHR 2012, UCI method)
#> Estimator: cfprobit | First stage: linear | SE: two-step | N = 2000
#> Endogenous: d
#> Target: APE of d
#> ------------------------------------------------------------------------------
#> Baseline (gamma = 0):
#> APE(d) = 0.128429 (SE 0.013711) [0.101556, 0.155302]
#>
#> Scale: 1 latent-index unit of gamma = 0.2377 pr. points per unit of Z (avg., baseline)
#> 1 structural-latent unit of gamma = 1.1558 latent-index units (sigma_tilde = 0.8652)
#>
#> UCI union over gamma grid (5 point(s) per instrument):
#> gamma_z range: [-0.1000, 0.1000] exact Pr scale: [-0.0238, 0.0238]
#>
#> APE(d) bounds = [0.061910, 0.192398]
#> ------------------------------------------------------------------------------
confint(fit)
#> lower upper
#> d 0.06190973 0.1923978
fit2 <- apexog(y ~ x, endog = d ~ z, data = dat, method = "ltz",
mu = 0, omega = 0.0025, iterations = 100, seed = 1)
#> Running LTZ: 100 draw(s) from the gaussian prior over 1 instrument violation(s).
#> ... 100 / 100 draws done
summary(fit2)
#> ------------------------------------------------------------------------------
#> Plausibly-exogenous APE bounds (CHR 2012, LTZ method, gaussian prior)
#> Estimator: cfprobit | First stage: linear | SE: two-step | N = 2000
#> Endogenous: d
#> Target: APE of d
#> ------------------------------------------------------------------------------
#> Baseline (gamma = 0):
#> APE(d) = 0.128429 (SE 0.013711) [0.101556, 0.155302]
#>
#> Scale: 1 latent-index unit of gamma = 0.2377 pr. points per unit of Z (avg., baseline)
#> 1 structural-latent unit of gamma = 1.1558 latent-index units (sigma_tilde = 0.8652)
#>
#> LTZ prior:
#> gamma_z ~ N(0.0000, 0.0025)
#> exact Pr scale of the draws: mean 0.0013, sd 0.0107
#> iterations = 100
#>
#> LTZ 95% interval (sampling noise convolved with the prior; CHR 2012 eq. 7):
#> APE(d) 95% CI = [0.080154, 0.164078]
#>
#> Prior-only spread of the point estimates (sensitivity band, no sampling noise):
#> APE(d) 95% range = [0.090592, 0.162915]
#> ------------------------------------------------------------------------------
#>
#> Refit estimates across the draws:
#> 0% 2.5% 25% 50% 75% 97.5% 100%
#> d (point) 0.082544 0.094087 0.115217 0.126253 0.137872 0.160361 0.170744
#> d (convolved) 0.075071 0.080490 0.113037 0.125569 0.140057 0.163198 0.172027