Skip to contents

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 + x2 with the 0/1 outcome and the exogenous controls (factors and interactions allowed; use y ~ 1 for 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 as d + d:x, with its instruments on the right (e.g. d + d:x ~ z + z:x); combine it with aie = 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; uses mu and omega unless prior_params is given), one of "uniform", "chi2", "t", "gamma", "poisson", "special" (parameters in prior_params), or a function function(n) returning an n x K matrix of draws.

prior_params

List with one parameter vector per instrument (or one, broadcast): normal c(mean, sd), uniform c(min, max), chi2 df, t df, gamma c(shape, scale), poisson mean, special: a numeric donor vector sampled with replacement.

draws

Optional iterations x K matrix of \(\gamma\) draws (in gunits) used instead of a prior, e.g. a joint prior of your own. Passing Stata's e(gamma_sim) (latent units, so with the default gunits = "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 as d: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 of X and Z. Each must be an exogenous control column or an endogenous regressor (use numeric 0/1 variables, not factor()). If the product X:Z is a declared endogenous regressor (endog = d + d:x ~ ...) that regressor is the target; otherwise the product is taken from formula when it is written as x:z or x*z, or added as an exogenous control. Do not write it as I(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. With firststage = "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 in endog, 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 X and Z (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's cfinteract). 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 as gs_max); print reports 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 and print warns 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 length nrow(data).

subset

Optional logical expression evaluated in data. Observations where it is NA are dropped (Stata's if treats a missing value as +Inf and may keep them).

sweep_omega, sweep_mu, sweep_delta

LTZ, Gaussian prior: rerun the simulation for each prior variance in sweep_omega (means sweep_mu, default 0; x-axis labels sweep_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