The help file of the Stata command, version 0.22.0, as Stata displays
it with help apexog (rendered to text with Stata’s
smcl2txt translator).
Title
apexog -- APE bounds in a control-function probit (or a recursive
bivariate probit) under plausibly-exogenous instruments (Conley,
Hansen, & Rossi 2012)
Syntax
apexog method depvar [indepvars] (endog = iv) [(endog2 = iv2) ...] [
if] [in] [, options]
depvar must be coded 0/1. Each endog may carry a c. or i. prefix (which
sets the default first stage) or be a two-way interaction such as
c.d#c.X of an endogenous treatment with a moderator (see the
canonical case under Examples). Weights and the svy prefix are not
supported. Typing apexog alone after estimation replays the posted
results; apexog, level(90) replays at another level.
where method is one of:
method Description
-------------------------------------------------------------------------
uci Union of Confidence Intervals over a grid of
assumed gamma values
ltz Local-to-Zero simulation from a Gaussian prior on
gamma
-------------------------------------------------------------------------
options Description
-------------------------------------------------------------------------
Model
estimator(cfprobit) main-equation estimator; only cfprobit
is supported (default).
firststage(biprobit) switches the
whole estimator to the recursive
bivariate probit.
firststage(type) first-stage model: linear (default),
probit, fprobit, poisson, or biprobit
(recursive bivariate probit for one
0/1 endogenous regressor: joint MLE
instead of a control function;
v0.19). Accepts one type (applied to
all endogs) or one per endog.
aie(X Z) switch the sensitivity target from the
APE to the Average Interaction Effect
of X and Z (cts x cts, cts x binary,
or binary x binary; type
auto-detected). See ginteff (Radean
2023).
cfinteract add the products of the control
functions to the main probit
(replicates cfprobit's cfinteract).
Auto-on when an interaction of an
endogenous treatment with a moderator
is declared as an endogenous
regressor (see below).
UCI (method = uci)
gmin(numlist) lower bound of assumed gamma range; one
value per instrument (a single value
is broadcast to all)
gmax(numlist) upper bound of assumed gamma range; one
value per instrument (a single value
is broadcast to all)
grid(#) number of grid points per instrument;
default grid(11)
LTZ (method = ltz)
mu(numlist) Gaussian prior mean for each
instrument's gamma (single value
broadcast to all)
omega(numlist) Gaussian prior variance for each
instrument's gamma (single value
broadcast to all)
iterations(#) number of Monte-Carlo draws; default
iterations(1000)
seed(#) random-number seed for reproducibility
distribution(type params) non-Gaussian prior on gamma instead of
mu()/omega(): normal mean sd, uniform
min max, chi2 df, t df, gamma shape
scale, poisson mean, or special
varname (empirical draws); one
parameter set per instrument
graphomega(numlist) delta sweep: rerun the LTZ simulation
for each prior variance in the list
(one value per step, broadcast to all
instruments; Gaussian priors only)
and store/plot bounds vs delta
graphmu(numlist) prior means for the sweep steps
(default: zeros)
graphdelta(numlist) x-axis labels for the sweep steps
(default: the omega values)
Inference
gunits(latent|pr|structural) units of the user-supplied gamma
values: latent (default, probit-index
units; synonym index), pr
(probability points; divided by m_phi
from the baseline fit), or structural
(structural-latent units, total error
variance 1; divided by sigma_tilde
from the baseline fit -- a conversion
derived for a LINEAR first stage; not
for use with a probit, fprobit, or
poisson first stage, see gunits())
level(#) confidence level as a fraction
(level(.95), the default) or as a
percent (level(95))
vce(vcetype) vcetype may be robust (default) or
cluster clustvar
Target selection (v0.11)
target(spec list) selects the sensitivity target. Three
forms:
target(d1 d2) APE for the listed endogenous
regressors (subset of varlist2)
target(c.d1) same as target(d1); the i./c. prefix on
an APE spec is stripped
target(c.X#i.d) AIE for the interaction; prefixes drive
the formula:
c.X#c.Z cts × cts → cross-partial
c.X#i.d cts × binary → firstdiff in the binary
i.X#i.d binary × binary → 2nd discrete
difference
target() is mutually exclusive with
aie(). Default (target omitted): APE
for every endog in the model.
Display
noheader suppress the results display (notes are
still printed; everything is stored
in e())
graph produce a graph of UCI bounds vs gamma
(uci) or histogram of LTZ draws (ltz)
graphoptions(string) extra options passed to the twoway call
(overrides defaults)
debug print the per-iteration probit fits and
Mata intermediates
-------------------------------------------------------------------------
Description
apexog answers the question: in a control-function probit model, how
large would the exclusion-restriction violation gamma have to be before
the estimated Average Partial Effect of the endogenous regressor crosses
zero or loses significance? It adapts Conley, Hansen, and Rossi's (2012)
"Plausibly Exogenous" framework -- originally formulated for 2SLS
coefficients -- to target the APE (probability scale) in cfprobit.
With aie(X Z) or a target() interaction spec, the same UCI/LTZ machinery
instead targets the Average Interaction Effect (the AIE quantity reported
by ginteff; Radean 2023). All three interaction types are supported --
continuous x continuous (cross-partial), continuous x binary (first
difference), and binary x binary (second discrete difference) -- with the
type auto-detected from the data, or forced via the c./i. prefixes in
target().
apexog does NOT require StataNow: it implements the control-function
probit directly (regress/probit/fracreg/poisson/biprobit plus Mata) and
never calls cfprobit at runtime; the cfprobit comparisons live in the
validation suite only. Typing apexog without arguments after estimation
replays the posted baseline estimates.
Two methods are available:
uci -- Union of Confidence Intervals. For each gamma on a grid over
[gmin, gmax], the main-equation latent index is shifted by Z*gamma
(via an offset term) and the APE + its delta-method standard error
are recomputed. Reports the union of per-gamma CIs. This is the
conservative interval: it provides correct coverage as long as the
true gamma lies somewhere in [gmin, gmax].
ltz -- Local-to-Zero. Draws gamma_i from the prior (Gaussian N(mu,
omega) or distribution()), recomputes the APE and its Murphy-Topel SE
for each draw, and convolves each point APE with its sampling noise:
APE*_i = APE_i + SE_i * eps_i, eps_i ~ N(0,1). The reported interval
is the percentile interval of the CONVOLVED draws -- the simulation
implementation of CHR (2012) eq. (7), where the estimator's sampling
distribution and the exogeneity-error term A*gamma are independent
and must be added (in the linear model this is the familiar V +
A*Omega*A' interval reported by plausexog). As omega -> 0 the LTZ
interval converges to the baseline gamma = 0 confidence interval,
never below it. The prior-only spread of the point APEs (no sampling
noise) is also displayed, as a sensitivity band, and returned in
e(lo_prior_vec)/e(hi_prior_vec).
Standard errors are two-step: the Murphy-Topel sandwich for the probit
coefficients (Murphy & Topel 1985) plus the direct dependence of the
effect on the estimated first stage, computed in Mata; the results header
labels them "SE: two-step". At gamma = 0 the point estimate matches
cfprobit + margins, dydx() to machine precision, and the SE differs from
that benchmark by the direct term only, about 1% (see Methods and
formulas). With firststage(biprobit) (v0.19) the main equation is
instead the recursive bivariate probit fit jointly with the 0/1
treatment, and the SE is the MLE delta method; see the Options and
Methods sections for when to prefer it.
Options
+-------+
----+ Model +------------------------------------------------------------
estimator(cfprobit) fixes the main-equation estimator to cfprobit (probit
with control function). Currently the only supported value.
Reserved for forward compatibility with future alternative estimators
(e.g. ivprobit).
firststage(type) controls the first-stage regression for the endogenous
variable. Supported types:
linear -- OLS regression (default). Endogenous d is treated as
continuous. With a 0/1 d the result is a descriptive fitted
contrast, not a causal estimate, and the results header says so
(see Input requirements and limitations).
probit -- Probit regression. Endogenous d must be binary {0, 1}.
The control function is the generalized residual (d -
Phi(Wpi))*phi(Wpi) / [Phi*(1-Phi)].
fprobit -- Fractional probit QMLE (Stata's fracreg probit).
Endogenous d may take any value in [0, 1].
poisson -- Poisson regression for count-valued endogenous d. The
control function is the raw residual d - exp(Wpi).
biprobit -- (v0.19) Recursive bivariate probit instead of a control
function. Endogenous d must be binary {0, 1} and the only
endogenous regressor. At every gamma apexog fits biprobit
(depvar = indepvars d, offset(z'gamma)) (d = iv indepvars) by
maximum likelihood and reports the average-structural-function
discrete change mean(Phi(eta|d=1) - Phi(eta|d=0)) from the
outcome equation, with a delta-method SE from the joint-MLE e(V)
(robust or cluster, as requested). There is no generated
regressor and hence no Murphy-Topel step. This is the exact
estimator when the structural errors are jointly normal, where
the generalized-residual control function of probit is only an
approximation; see Methods and formulas. Since version 0.22.0 it
also accepts an AIE target: the interaction of the treatment with
an exogenous moderator, the moderator among the controls and the
treatment alone in the clause; see AIE with the bivariate probit.
gunits(structural) is accepted and identical to the default for
this engine (sigma_tilde = 1).
Which one for a binary treatment? probit reproduces cfprobit exactly and
relies on Wooldridge's sufficiency assumption D(eps | z, d) = D(eps |
GR); biprobit relies on joint normality of the outcome and treatment
errors. Neither set of assumptions nests the other (Wooldridge 2014).
Under joint normality the two-step APE is biased, and increasingly so in
the error correlation (the large-N table under Methods), so when that is
the maintained model prefer biprobit. The results header prints a note
whenever a generalized-residual first stage is in use. A linear first
stage is not a third route to a causal estimate for a binary treatment: a
0/1 variable cannot have the normal linear first stage the
control-function model assumes, so that fit is a descriptive contrast
(the header prints a note, v0.21.2).
Phase-1 (v0.10) shortcut: the type can also be declared in the
endogenous-variable clause itself via the standard Stata
factor-variable prefix:
(c.d = z) -- treats d as continuous -> default firststage(linear)
(i.d = z) -- treats d as binary -> default firststage(probit)
The firststage() option still overrides the prefix. The prefix is
stripped before passing d to the main probit (binary-ness is then
auto-detected from the values, so the discrete-change APE is used). The
i. prefix keeps its probit (control-function) default; the recursive
bivariate probit must be requested explicitly with firststage(biprobit).
aie(X Z) switches the sensitivity target from the APE to the Average
Interaction Effect (AIE) for the interaction of X and Z, in the style
of ginteff (Radean 2023). apexog adds the interaction term X * Z to
the regressor list automatically -- do NOT also write c.X##c.Z or
i.X##i.Z in the varlist. Both X and Z must appear among the
exogenous OR endogenous regressors. EITHER OR BOTH may be endogenous
-- this is the canonical cfprobit use case (interaction of an
endogenous treatment with an exogenous or endogenous moderator).
Each interactor's type (continuous vs binary) is auto-detected and
the appropriate AIE formula is used:
continuous-by-continuous -- cross-partial:
AIE = mean(phi(eta) * (b_XZ - eta * a * b))
with a_i = b_X + b_XZ * Z_i, b_i = b_Z + b_XZ * X_i.
continuous-by-binary (say X cts, Z binary) -- firstdiff in Z of the
slope in X:
AIE = mean( phi(eta|Z=1)*(b_X + b_XZ) - phi(eta|Z=0)*b_X )
binary-by-binary -- 2nd discrete difference of Phi:
AIE = mean( Phi(eta|1,1) - Phi(eta|1,0) - Phi(eta|0,1) +
Phi(eta|0,0) )
When an interactor is endogenous, the X * d tempvar is
automatically EXCLUDED from that endog's first-stage regression
(otherwise the first stage would be circular). Its control function then
covers the product as well, so the product needs no instrument of its own
(Wooldridge 2015, pp. 428-429, 437). List the instruments interacted with the
moderator in that endog's clause all the same, as in (d = z c.z#c.X):
the control function is right only if the first stage lets the instrument's
effect on d differ with the moderator, and leaving them out biases the
AIE when it does. The Murphy-Topel
correction propagates first-stage uncertainty into the AIE delta-method
SE in all three cases. With firststage(biprobit) the product enters
the outcome equation of the joint fit only, and the AIE must involve the
0/1 treatment and an exogenous moderator (v0.22.0; see
AIE with the bivariate probit). Multi-level factor (3+ unique non-{0,1} values
> )
interactors are not supported in v0.9.
+-----+
----+ UCI +--------------------------------------------------------------
gmin(numlist) and gmax(numlist) -- define the assumed range for gamma in
each instrument. Both must be specified for uci; each takes a
numlist with one value per instrument (in the order the instruments
appear in the parenthesized clause).
grid(#) -- number of evenly-spaced grid points per instrument. Total
fits per UCI run is grid^k where k is the number of instruments (the
CHR curse of dimensionality). If grid^k exceeds c(max_matsize), uci
stops with an actionable error: coarsen grid(), use fewer
instruments, or switch to ltz (which draws from the prior and needs
no grid).
+-----+
----+ LTZ +--------------------------------------------------------------
mu(numlist) and omega(numlist) -- Gaussian prior on gamma: gamma_k ~
N(mu_k, omega_k). Both must be specified for ltz; omega is the
variance (not the standard deviation), and must be positive.
iterations(#) -- number of simulation draws. Default 1000.
seed(#) -- sets the random-number seed via set seed before drawing the
gamma samples. Use this for reproducibility.
distribution(type params) -- non-Gaussian prior on gamma for ltz,
mutually exclusive with mu()/omega(). type is one of normal,
uniform, chi2, t, gamma, poisson, or special; params lists the
parameters for EACH instrument in turn: two per instrument for
normal (mean, sd), uniform (min, max), and gamma (shape, scale); one
per instrument for chi2 (df), t (df), and poisson (mean); and, for
special, the name of a variable per instrument whose observed values
are sampled with replacement as the empirical prior. The conventions
mirror plausexog. Examples with one instrument: distribution(uniform
-0.1 0.1), distribution(t 5), distribution(special mygammas).
gunits() rescales the draws themselves, so every type works with
gunits(pr) and gunits(structural). The delta sweep (graphomega())
requires the Gaussian prior.
graphomega(numlist) [graphmu(numlist) graphdelta(numlist)] -- the DELTA
SWEEP: after the main LTZ results, rerun the simulation for each
prior variance in graphomega() (a single value per step, broadcast to
all instruments; Gaussian priors only) and report the convolved CI
and prior-only band per step -- the CHR (2012) Figures 1-2 "bounds as
a function of the prior width" display, for the FIRST target.
Results are stored in e(sweep) (columns: delta mu lb ub lb_prior
ub_prior); with graph, the sweep plot replaces the LTZ histogram.
graphmu() sets per-step prior means (default zeros); graphdelta()
relabels the x-axis (default: the omega values). gunits(pr) and
gunits(structural) apply to sweep values too. Each step costs a full
set of iterations() draws.
+-----------+
----+ Inference +--------------------------------------------------------
gunits(latent|pr|structural) -- units in which the user-supplied gamma
quantities (gmin()/gmax(), mu()/omega(), distribution() draws, and
sweep values) are expressed. Internally the violation always enters
as an offset on the PROBIT-INDEX scale; this option tells apexog
which of the three elicitation scales your numbers live on, and it
converts them after the baseline fit. Getting the scale right
matters: Simulations show that feeding a structural-units prior to
the index unrescaled is a scale miscalibration whose wide-prior LTZ
coverage is 2*Phi(z*sigma_tilde)-1 (about 0.88 instead of 0.95 at an
endogeneity correlation of 0.6).
gunits(latent) (default; synonym index) -- gamma is a coefficient in
the PROBIT-INDEX latent equation: the scale on which the probit
normalizes the error sd CONDITIONAL on the control functions to
1. This is the scale the offset uses internally, so no
conversion is applied. Note this is NOT the structural-latent
scale (see structural below); the two differ by the factor
sigma_tilde.
gunits(pr) -- gamma values are PROBABILITY POINTS: the instrument's
direct effect on Pr(y=1) per unit of Z. Internally apexog
divides every gamma quantity by m_phi = mean(normalden(eta_hat))
from the baseline (gamma = 0) fit -- the average dPr/dindex
slope, the same factor that maps the latent coefficient into the
APE (omega(), a variance, is divided by m_phi^2; for non-Gaussian
distribution() priors the draw itself is rescaled, which handles
chi2/t/gamma/poisson/special whose parameters are not scale
parameters). This puts apexog's gamma on the same scale as
plausexog's when the outcome is binary and plausexog is run as a
linear probability model, so the two commands can be compared for
the same elicited violation. Probability-scale elicitation is
also IMMUNE to the index-vs-structural units gap described under
structural.
gunits(structural) -- gamma values are on the STRUCTURAL latent
scale: the researcher reasons about y* = xb + gamma*z + eps with
the TOTAL error variance normalized to 1 (the scale on which
simulation DGPs and textbook latent-variable models are usually
written). The probit index instead normalizes the error sd
CONDITIONAL on the control functions, so index units = structural
units / sigma_tilde with sigma_tilde = sd(eps | CF) < 1 whenever
there is real endogeneity. apexog estimates sigma_tilde from the
baseline fit's control-function coefficient(s) as sigma_tilde =
(1 + b_cf' Var(chat) b_cf)^(-1/2) -- for a single control
function with a unit-variance first-stage residual this is (1 +
theta_cf^2)^(-1/2) -- and divides every gamma quantity by it
(omega() by sigma_tilde^2; non-Gaussian draws are rescaled
draw-by-draw). cfinteract control-function product terms are
ignored in sigma_tilde.
Linear first stage only. The sigma_tilde conversion (and the
always-on header line "1 structural-latent unit of gamma =
1/sigma_tilde latent-index units") is derived for, and exact
with, a LINEAR first stage, where the control function estimates
the structural first-stage error. With firststage(probit),
fprobit, or poisson it does NOT apply: in Monte Carlo
simulations (n = 5000, R = 1000 per cell, gamma_true entered in
structural units) the structural gamma enters the probit index
essentially UNSCALED -- refitting at the raw structural gamma
gives Wald coverage of the true APE 0.936 against 0.590 for the
refit at gamma/sqrt(1 - rho^2) (binary d, probit first stage,
gamma_true = 0.2) and 0.949 against 0.877 (fractional d, fprobit
first stage), and the interpolated zero-bias offset lies within
5% of the structural gamma in all three generalized-residual
designs (binary, fractional, and count d). So do not use
gunits(structural) with those first stages: elicit on the index
scale (the default) or on the probability scale (gunits(pr)),
which is immune to the two latent scales. apexog still accepts
the combination for backward compatibility but prints a warning
line in the results header; nothing else changes. e(stilde) is
then the linear-first-stage formula evaluated on a generalized
residual (0.92, 0.92, 0.98 at gamma_true = 0 in those designs),
NOT a conversion factor, and should be read as such. For a 0/1
treatment firststage(biprobit) has sigma_tilde = 1 by
construction, consistent with this evidence.
For all three settings the conversion is first-order (exact as gamma
-> 0; m_phi and sigma_tilde are held at their baseline values).
All gamma values displayed and stored (e(grid), graphs) are in
PROBIT-INDEX (latent) units; a header note records any
conversion, and both conversion factors are always reported in
the header and returned in e(mphi) and e(stilde). Both are
computed from the gamma = 0 baseline fit, which is misspecified
whenever the true violation is nonzero, so they describe that fit
rather than being structural constants: in the Monte Carlo
simulations the mean e(stilde) moves with the true violation
(linear first stage 0.80, 0.91, 1.00 at gamma_true = 0, 0.2, 0.5
against a true sqrt(1 - rho^2) of 0.80; Poisson first stage 0.98,
0.93, 0.61): the omitted z'gamma term is partly absorbed by the
control-function coefficient through the first stage.
Limits of the structural conversion (v0.21.2). Dividing by the
baseline sigma_tilde is exact only at gamma = 0. The exact
index-scale value g of a structural value g_s solves g_s = g *
sigma_tilde(g), with sigma_tilde(g) the factor implied by the
refit at g. With one continuous endogenous regressor, one
instrument and a linear first stage the control-function
coefficient of that refit is theta_cf(0) + g/pi_z, so
sigma_tilde(g) = (1 + sigma_v^2*(theta_cf(0) + g/pi_z)^2)^(-1/2),
with pi_z the first-stage coefficient of the instrument and
sigma_v the first-stage residual sd. The map g -> g *
sigma_tilde(g) is bounded: a structural value below
|pi_z|/sigma_v in absolute value has exactly one index-scale
counterpart, and a larger one has none or two. apexog does not
solve this equation; it divides by the baseline factor. With
gunits(structural) the header says so, reports the limit
|pi_z|/sigma_v when it is defined (also stored in e(gs_max)), and
prints a warning when the uci box reaches it or ltz prior draws
fall at or beyond it; results are unchanged. For a 0/1 regressor
with a linear first stage the conversion has no model behind it:
the header prints a warning instead, and e(gs_max) is missing.
The baseline division also errs differently for positive and
negative violations: in simulations with a structural N(0,
0.30^2) prior (endogeneity correlation 0.6, limit 0.8) the
resulting LTZ intervals covered 0.942 overall, but 57 of the 58
misses were at positive violations. For statements that do not
rest on this approximation, elicit on the index scale or with
gunits(pr).
Exact probability scale of the refits (v0.20). Whatever the input
scale, apexog also reports, at every refit, the EXACT
probability-scale value of each instrument's violation, computed
from the model refitted at that violation over the estimation
sample, holding the treatment, the control functions and the
other instruments' offsets at their observed values: for a 0/1
instrument the average change in Pr(y=1) when it switches from 0
to 1, for any other instrument the average derivative
mean(phi(eta))*gamma. The first-order value m_phi*gamma used by
gunits(pr) approximates it; the two agree for small violations
and can differ by several percent for a large violation of a 0/1
instrument on an outcome near 0 or 1 (about 10% in an application
with a 0/1 instrument and an outcome near 1). With a linear
first stage, as many instruments as endogenous regressors and a
continuous instrument they coincide exactly, because the offset
then lies in the span of the regressors and control functions and
the refit leaves the fitted index unchanged. The UCI output
prints the exact range beside each gamma range and stores the
values in e(grid_pr); with gunits(pr) and graph the x-axis is the
exact scale. The LTZ output prints the exact mean and sd of the
draws and stores e(gamma_sim) (latent draws) and e(gamma_pr_sim).
The input conversion itself is unchanged (first order).
level(#) -- confidence level (both methods; for ltz it is the percentile
level of the convolved draws), given as a fraction in (0, 1) or, as
in other Stata commands, as a percent in [1, 100): level(.9) and
level(90) are equivalent. e(level) always stores the fraction.
Default 0.95.
vce(vcetype) -- variance-covariance estimator:
vce(robust) -- heteroskedasticity-consistent (default). The
Murphy-Topel correction is applied to account for the generated
regressor, and the effect's direct dependence on the first-stage
estimate is included (see Methods and formulas).
vce(cluster clustvar) -- cluster-robust on clustvar, which may be
numeric or string; the usual abbreviations such as vce(cl id) are
accepted. The cluster correction is propagated through both the
first-stage VCE and the Murphy-Topel meat (cluster-summed
scores). The number of clusters is stored in e(N_clust) and the
variable name in e(clustvar).
For bootstrap inference, wrap apexog in Stata's bootstrap prefix:
. bootstrap, reps(500): apexog uci promoted tenure manager (training
= subsidy), gmin(-0.3) gmax(0.3)
Examples
The examples below run on this small simulated dataset (a binary
promotion outcome, two continuous and one binary endogenous treatment,
two instruments, and a few exogenous controls/moderators). Paste it in
to follow along:
. clear
. set seed 8675309
. set obs 4000
. gen double tenure = rnormal() // exogenous control (cts)
. gen double experience = rnormal() // exogenous moderator (cts)
. gen byte manager = runiform() < 0.5 // exogenous moderator (binary)
. gen double subsidy = rnormal() // instrument
. gen double grant = rnormal() // second instrument
. gen double a1 = rnormal() // UNOBSERVED (drives training/certified)
. gen double a2 = rnormal() // UNOBSERVED (drives coaching)
. gen double e = 0.4*a1 + 0.4*a2 + sqrt(0.68)*rnormal()
. gen double training = 0.7*subsidy + 0.3*tenure + a1 // endogenous (cts)
. gen double coaching = 0.6*grant + 0.3*experience + a2 // endogenous
(cts)
. gen byte certified = 0.9*subsidy + 0.3*tenure + a1 > 0.4 // endogenous
(binary)
. gen double ystar = -0.3 + 0.5*training + 0.3*coaching + 0.3*tenure ///
+ 0.2*experience + 0.3*manager + 0.4*training*manager ///
+ 0.25*tenure*experience + e
. gen byte promoted = ystar > 0 // binary outcome
. gen int team = ceil(_n/20) // 200 clusters of 20
UCI for the APE of a continuous treatment, gamma in [-0.3, 0.3]:
. apexog uci promoted tenure manager (training = subsidy), gmin(-0.3)
gmax(0.3)
UCI with a binary endogenous treatment and probit first stage:
. apexog uci promoted tenure manager (certified = subsidy),
firststage(probit) gmin(-0.1) gmax(0.1) grid(11)
Same treatment with the recursive bivariate probit (exact under joint
normality, where the probit first stage above is only an approximation):
. apexog uci promoted tenure manager (certified = subsidy),
firststage(biprobit) gmin(-0.1) gmax(0.1) grid(11)
. apexog ltz promoted tenure manager (certified = subsidy),
firststage(biprobit) mu(0) omega(0.0025) iterations(1000) seed(12345)
LTZ with a tight Gaussian prior centered at 0:
. apexog ltz promoted tenure manager (training = subsidy),
mu(0) omega(0.0025) iterations(2000) seed(12345)
Same prior elicited on the other two gamma scales (see gunits()):
. apexog ltz promoted tenure manager (training = subsidy),
mu(0) omega(0.0025) iterations(2000) seed(12345) gunits(structural) //
structural-latent units, /sigma_tilde
. apexog ltz promoted tenure manager (training = subsidy),
mu(0) omega(1.5e-06) iterations(2000) seed(12345) gunits(pr) //
probability points, /m_phi
Cluster-robust SEs:
. apexog uci promoted tenure manager (training = subsidy), gmin(-0.5)
gmax(0.5)
vce(cluster team)
Visualize the UCI:
. apexog uci promoted tenure manager (training = subsidy), gmin(-0.5)
gmax(0.5) grid(21) graph
Phase-1 syntax with i. prefix and target() narrowing (v0.10):
. apexog uci promoted tenure manager (i.certified = subsidy), gmin(-0.1)
gmax(0.1) // = firststage(probit)
. apexog uci promoted tenure (training coaching = subsidy grant), gmin(0
0) gmax(0 0) target(training) // only training's APE
Phase-2 syntax: target(c.X#i.d) for AIE with prefix-driven type (v0.11).
When the treatment is one of the interactors, its clause also lists the
instrument interacted with the moderator, and the violation is put on
subsidy alone:
. apexog uci promoted tenure experience (training = subsidy), gmin(-0.3)
gmax(0.3) target(c.tenure#c.experience) // cts-by-cts AIE
. apexog uci promoted tenure (i.certified = subsidy c.subsidy#c.tenure),
gmin(-0.3 0) gmax(0.3 0) target(c.tenure#i.certified) //
cts-by-binary (firstdiff)
. apexog uci promoted manager (i.certified = subsidy
c.subsidy#i.manager), gmin(-0.3 0) gmax(0.3 0)
target(i.manager#i.certified) // binary-by-binary
Sensitivity of the Average Interaction Effect for two exogenous
moderators under plausible exclusion-restriction violations:
. apexog uci promoted tenure experience (training = subsidy), gmin(-0.3)
gmax(0.3) grid(11) aie(tenure experience)
. apexog ltz promoted tenure experience (training = subsidy), mu(0)
omega(0.0025) iterations(2000) aie(tenure experience)
Canonical case (v0.13): an ENDOGENOUS treatment interacted with a
moderator. training*manager is itself endogenous, so declare it as a
SECOND endogenous regressor and instrument it (here with subsidy and
subsidy*manager), exactly as in cfprobit / plausexog. cfinteract is
auto-on; the AIE is reported on the probability scale:
. apexog uci promoted tenure manager (c.training c.training#c.manager =
subsidy c.subsidy#i.manager),
target(c.training#i.manager) gmin(-0.3 -0.3) gmax(0.3 0.3) grid(11)
Note: with the control-function engine the treatment may instead stand
alone in its clause, as in (c.training = subsidy c.subsidy#i.manager)
with target(c.training#i.manager) (or the older aie(training manager)).
The treatment's control function then covers its product with the
moderator, which enters the main probit without a first stage of its own
(Wooldridge 2015, pp. 428-429, 437). In both forms list the instruments
interacted with the moderator: in the two-endog form they instrument the
product (the command stops if there are fewer instruments than endogenous
regressors), in the single-clause form they let the treatment's first
stage differ with the moderator, which the control function needs.
Without them the single-clause AIE is biased whenever the instrument's
effect on the treatment varies with the moderator. With
firststage(biprobit) the single-clause form is the only one: the
treatment is modelled jointly with the outcome, and the product needs no
first stage of its own.
A binary treatment interacted with a moderator: the recursive bivariate
probit (v0.22.0). The moderator is a control, the treatment stands alone
in the clause, and the interacted instrument may carry its own violation:
. apexog uci promoted tenure manager (certified = subsidy
c.subsidy#i.manager), firststage(biprobit)
target(i.certified#i.manager) gmin(-0.1 0) gmax(0.1 0) grid(11)
Moderator type. For an endogenous-treatment interaction, the moderator
type is set by the prefix in target(): target(c.d#c.W) gives the
cts-by-cts cross-partial, target(c.d#i.W) the cts-by-binary first
difference (validated to machine precision against the manual
decomposition for a binary exogenous moderator). For a binary endogenous
treatment this path gives a descriptive contrast only (the header says
so); use firststage(biprobit) as in the example above.
cfinteract scope. cfinteract adds the pairwise products of the control
functions. For two endogenous regressors (the canonical
endogenous-interaction AIE) this reproduces cfprobit's cfinteract
exactly. With three or more control functions, cfprobit's ## expansion
also includes the three-way and higher products, which apexog does not
add; for exact cfprobit equivalence use at most two endogenous
regressors.
Input requirements and limitations
apexog checks its inputs up front and stops with an explicit message
(return code 198) rather than failing deep inside a fit or, worse,
returning a silently wrong answer:
- depvar must be coded 0/1 on the estimation sample (Stata's probit
would treat any nonzero value as 1, but the two-step variance
needs the 0/1 coding); recode first, e.g. gen byte y01 = (y !=
0).
- depvar, the controls, the endogenous regressors, and the
instruments must be disjoint. An instrument that merely
duplicates a control (e.g. the main effect of a ## term) is
dropped by the full-rank cleaning with a note.
- gmin() may not exceed gmax(); grid() must be at least 2; omega()
must be positive; iterations() must be at least 10.
- firststage(probit) needs a 0/1 endogenous regressor,
firststage(fprobit) one in [0,1], and firststage(poisson) a
nonnegative one.
- firststage(biprobit) needs a 0/1 endogenous regressor that is the
ONLY endogenous regressor. An AIE target must interact it with
an exogenous moderator (v0.22.0). Several endogenous regressors,
the endogenous-interaction clause (c.d c.d#c.m = ...), an AIE of
two exogenous variables, a c. prefix on the treatment in
target(), or estimator(biprobit) stop with an explicit message.
- Nonlinear first stages are approximations. With
firststage(probit), fprobit, or poisson the control function is
Wooldridge's (2014, 2015) generalized residual. It is consistent
for the APE under his sufficiency assumption D(eps | z, d) =
D(eps | GR), which does NOT hold under joint normality of the
structural errors; there the two-step APE is biased, increasingly
so in the endogeneity correlation (-2.7%, -11.6%, -50.6% at error
correlations 0.3, 0.5, 0.8 in the large-N check under Methods and
formulas). apexog reproduces cfprobit exactly, so this is a
property of the estimator, not of the implementation. For a 0/1
treatment under joint normality use firststage(biprobit); the
results header carries the same note whenever one of these first
stages is used.
- gunits(structural) is a linear-first-stage conversion. The
sigma_tilde rescaling behind gunits(structural) (and the "1
structural-latent unit of gamma = 1/sigma_tilde latent-index
units" header line) is derived for a linear first stage. With
firststage(probit), fprobit, or poisson Monte Carlo simulations
put the correct offset at the UNSCALED structural gamma (Wald
coverage at the true violation 0.936 vs 0.590 for binary d and
0.949 vs 0.877 for fractional d, raw gamma vs gamma/sqrt(1 -
rho^2); zero-bias offset within 5% of the structural gamma), so
the option should not be used with those first stages. apexog
accepts the combination but prints a warning line in the results
header (results unchanged), and e(stilde) is then the linear
formula evaluated on a generalized residual, not a conversion
factor. Elicit on the index scale or with gunits(pr) instead;
see gunits().
- gunits(structural) uses the baseline sigma_tilde. The conversion
is exact only at gamma = 0, and with one continuous endogenous
regressor, one instrument and a linear first stage a structural
value at or beyond |pi_z|/sigma_v in absolute value has no unique
index-scale counterpart. apexog accepts such values but prints
the limit and a warning in the results header (results
unchanged). With a 0/1 regressor and a linear first stage the
conversion is not derived at all, and the header warns of that
instead; see gunits().
- A 0/1 endogenous regressor with a linear first stage is a
descriptive fit. The control-function model assumes a linear
first stage with a normal error independent of the instruments,
which a binary treatment cannot satisfy. apexog accepts the
combination ((d = z) with a 0/1 d defaults to it; (i.d = z)
selects the probit first stage) and reports the fitted discrete
change with its two-step standard error, but the results header
notes that the effect is a descriptive fitted contrast without a
causal interpretation or a causal coverage claim. When a causal
reading is intended use firststage(biprobit) (joint normality) or
firststage(probit) (control-function sufficiency). For a 0/1
treatment inside an interaction use firststage(biprobit) with the
treatment alone in the clause and the moderator among the
controls (v0.22.0); the header note says so.
- A first stage that drops observations (perfect prediction in a
probit first stage) or leaves the control function undefined
stops the command. Perfect prediction or a collinear control
function in the MAIN probit returns missing bounds with a warning
instead.
- Weights, the svy prefix, and vce(bootstrap) are not supported; wrap
apexog in the bootstrap prefix for bootstrap inference.
- Variable names are unabbreviated before use, so abbreviations work;
names longer than 27 characters are truncated in
e(lb_endog)/e(ub_endog) and in matrix column labels (Stata's
32-character name limit).
- Options that belong to the other method (gmin()/gmax() with ltz;
mu()/omega()/distribution()/seed() with uci) are ignored with a
note.
Stored results
apexog is an estimation command: it posts e(b) (the baseline, gamma = 0,
target estimates -- one APE per endogenous regressor, or the AIE), e(V)
(their full Murphy-Topel delta-method covariance, cross-target terms
included), and e(sample). test, lincom, estimates store, ... if
e(sample), and replay all work. In addition it stores (common to both
methods):
Scalars
e(N) sample size
e(level) confidence level
e(baseline_ape) APE (or AIE if aie()) at gamma = 0
e(baseline_se) two-step SE at gamma = 0: Murphy-Topel parameter
covariance plus the direct first-stage term (MLE
delta-method SE with firststage(biprobit))
e(mphi) mean(normalden(eta_hat)) at the baseline fit:
average dPr/dindex slope; the
latent-to-probability conversion factor used by
gunits(pr)
e(stilde) sigma_tilde = (1 + b_cf' Var(chat) b_cf)^(-1/2) at
the gamma = 0 baseline fit. With a linear first
stage this is the
probit-index-to-structural-latent scale ratio,
the conversion factor used by gunits(structural);
with a probit, fprobit, or poisson first stage it
is the same formula evaluated on a generalized
residual and NOT a conversion factor (see
gunits()); = 1 with firststage(biprobit). A
baseline-fit quantity: it moves with the true
violation
e(gs_max) |pi_z|/sigma_v: a structural-latent gamma below it
in absolute value has a unique index-scale
counterpart (v0.21.2; one continuous endogenous
regressor with one instrument and a linear first
stage, missing otherwise); see gunits()
e(rho) (with firststage(biprobit)) estimated correlation
of the outcome and treatment errors at the
baseline fit
e(lb_endog) lower bound of the APE interval (per endog; a name
longer than 27 characters is truncated)
e(ub_endog) upper bound of the APE interval (per endog)
e(lb_aie) / e(ub_aie)
lower/upper bound of the AIE interval (with
aie())
e(N_clust) number of clusters (with vce(cluster))
Macros (additional in aie() mode)
e(target) ape (default) or aie
e(aie_vars) the two variables in aie(X Z), space-separated
e(aie_spec) the target() interaction spec, e.g. c.X#i.d (AIE
via target())
e(target_list) the endogenous regressors whose APE is reported
(APE mode)
Macros
e(cmd) apexog
e(cmdline) the full command as typed
e(method) uci or ltz
e(gunits) latent, pr, or structural (units of the
user-supplied gamma values)
e(estimator) cfprobit, or biprobit with firststage(biprobit)
e(firststage) linear, probit, fprobit, poisson, or biprobit
e(vce) Murphy-Topel for the two-step control-function
estimator (the header labels its standard error
"two-step"; the stored string is unchanged), or
MLE with firststage(biprobit)
e(depvar) name of dependent variable
e(endog) names of the endogenous regressors
e(exog) names of exogenous regressors
e(instruments) names of instruments (after full-rank cleaning)
e(clustvar) cluster variable (with vce(cluster))
Matrices (both methods; J = number of targets)
e(b) / e(V) baseline (gamma = 0) target estimates and their
Murphy-Topel (biprobit: MLE delta-method)
covariance
e(baseline_ape_vec) / e(baseline_se_vec)
J x 1 baseline estimates and SEs (rows labelled
by target)
For method = uci, also:
Scalars
e(baseline_lo) / e(baseline_hi)
baseline (gamma=0) CI bounds
Matrices
e(grid) (grid^k) x (k+3J) matrix with columns (g1, ..., gk)
followed by (ape, lo, hi) for each target
e(grid_pr) (grid^k) x k exact probability-scale value of each
instrument's violation at each row of e(grid)
(columns gpr1, ..., gprk; see gunits())
e(baseline_lo_vec) / e(baseline_hi_vec)
J x 1 baseline CI bounds
For method = ltz, also:
Scalars
e(iterations) number of simulation draws
Matrices (J = number of targets)
e(ape_sim) iterations x J per-draw point APEs/AIEs (prior
only)
e(se_sim) iterations x J per-draw Murphy-Topel SEs
e(ape_sim_cnv) iterations x J convolved draws APE_i + SE_i*eps_i
(basis of the headline CI)
e(gamma_sim) iterations x k the gamma draws, one column per
instrument (latent-index units, after any
gunits() conversion)
e(gamma_pr_sim) iterations x k exact probability-scale value of
each draw at its refit (see gunits())
e(lo_pct_vec) / e(hi_pct_vec)
J x 1 convolved percentile bounds (=
e(lb_*)/e(ub_*))
e(lo_prior_vec) / e(hi_prior_vec)
J x 1 prior-only percentile bounds (sensitivity
band)
e(sweep) (with graphomega()) S x 6 delta-sweep matrix:
delta, mu, lb, ub, lb_prior, ub_prior (first
target)
Methods and formulas
Factor-variable instruments. Factor instruments (e.g.
dummy##c.eldisadv) are expanded and then cleaned to full rank: base
levels (0b.), the moderator main effect, and bare-vs-factor duplicates
that are collinear with the controls are dropped (data-based, via
_rmcoll), and each surviving instrument is materialised as a plain
variable. This keeps the first-stage design matrix full rank so the
Murphy-Topel VCE is well-defined. The reported instrument count (and
hence the required number of gmin()/gmax()/mu()/omega() values, unless a
single value is broadcast) is the cleaned, full-rank count;
e(instruments) lists the retained terms.
Following Conley, Hansen, and Rossi (2012), the main equation is
augmented with a possible violation gamma of the exclusion restriction:
Pr(y_i = 1 | y_e, x, z) = Phi(x_i' beta_1 + y_e,i * beta_d + chat_i *
beta_chat + z_i' gamma)
where chat is the control function from the first-stage regression of y_e
on (x, z) (an OLS residual for linear first stage, a generalized residual
for probit/fprobit/poisson).
For each value of gamma, apexog re-fits the probit with offset(z * gamma)
and computes:
APE = mean(phi(eta_hat)) * beta_d_hat (continuous d)
APE = mean(Phi(eta_hat | d=1) - Phi(eta_hat | d=0)) (binary d)
Standard errors use the Murphy-Topel two-step sandwich:
V_beta_MT = H_beta^(-1) * sum_i s_total_i s_total_i' * H_beta^(-1)
s_total_i = s_main_i + J_2pi * psi_pi_i
where s_main_i is the main-equation probit score, J_2pi is the
cross-Hessian d(s_main)/dpi, and psi_pi_i is the first-stage influence
function. The cross-Hessian propagates the uncertainty in the
first-stage parameters into beta's variance.
The variance of the effect (version 0.21.0). The APE or AIE depends on
the first-stage estimate twice: through the probit coefficients (the
Murphy-Topel channel above) and directly, because the control function
chat_i(pi_hat) sits in the index at which the effect is evaluated. Its
influence function therefore has two terms,
l_i = J_beta' psi_beta_i + J_pi' psi_pi_i, psi_beta_i = H_beta^(-1)
s_total_i
J_pi = mean_i [ dq_i/d(eta_i) * d(eta_i)/d(chat_i) * d(chat_i)/d(pi)
]
where J_beta is the delta-method gradient of the effect in the probit
coefficients and J_pi its direct gradient in the first-stage parameters
(d(eta)/d(chat) = the control-function coefficient, plus the cfinteract
product terms). SE = sqrt(sum_i l_i^2), with l_i summed within clusters
under vce(cluster); e(V) is the same outer product for all targets.
Versions through 0.20.1 used only the first term, SE = sqrt(J_beta'
V_beta_MT J_beta), as does cfprobit followed by margins (which treats the
stored control function as a fixed regressor); so at gamma = 0 apexog's
SE now differs from that benchmark by the second term, about 1% of the SE
in the validation designs (up to 3% under strong endogeneity), in either
direction. Point estimates are unchanged. The two-term formula was
checked against a formula-free oracle: with one instrument and a linear
first stage the fitted probit index does not depend on pi_hat, so the APE
equals mean(phi) * (b_d + b_z/pi_z) from a plain probit of y on the
controls, d and z, whose stacked delta-method variance the two-term
formula reproduces to machine precision. firststage(biprobit) is a joint
MLE and is not affected. Since version 0.21.2 the results header labels
this standard error "SE: two-step"; earlier versions printed
"Murphy-Topel", the name of its first term, and e(vce) still stores that
string.
Fractional-probit first stage (version 0.21.1). The first-stage weight
A_i is minus the derivative of the control function in the first-stage
index, d(chat_i)/d(W_i'pi) = -A_i; it is also the weight of the
first-stage Hessian. For firststage(probit), A_i = chat_i*(W_i'pi +
chat_i), an identity that needs a 0/1 regressor. For firststage(fprobit)
with a fractional regressor the derivative has one more term, A_i =
chat_i*(W_i'pi + chat_i) + d_i(1 - d_i)*[phi/(Phi(1 - Phi))]^2, which
version 0.21.1 uses; versions through 0.21.0 used the probit identity
there. Point estimates are unchanged, and the mean fprobit standard
error moves by at most about 3%, in either direction, in the validation
design (the two places the weight enters largely offset each other).
With the corrected weight the first-stage influence functions reproduce
the robust variance of fracreg exactly.
For cluster-robust SEs, the meat is replaced by the sum of OUTER products
of cluster-summed scores:
meat_cluster = sum_c (sum_{i in c} s_total_i) (sum_{i in c}
s_total_i)'
Nonlinear first stages: the generalized-residual control function is an
approximation. For firststage(probit), fprobit, and poisson the control
function is Wooldridge's (2014, 2015) generalized residual GR (for a 0/1
treatment GR = (d - Phi(Wpi)) phi(Wpi) / [Phi(Wpi) (1 - Phi(Wpi))]).
Adding GR to the probit for depvar identifies the APE under Wooldridge's
sufficiency assumption
D(eps | z, d) = D(eps | GR)
(Wooldridge 2015, eq. 53 and the text around it on p. 442; Wooldridge
2014, the discussion following his eq. 66). That assumption is NOT
implied by joint normality of the structural errors (eps, v):
conditioning on the binary d rather than on v leaves Var(eps | d, z)
heteroskedastic and eps | d, z non-normal, so the probit in (x, d, GR) is
misspecified there. Wooldridge (2014) is explicit that with a binary
endogenous regressor the control-function approach uses "different
parametric assumptions than those used in the bivariate probit model --
and neither set subsumes the other", and that the model should be viewed
"only as an approximation"; Wooldridge (2015, p. 442) adds that under the
bivariate-probit assumptions "there is no known CF method that
consistently estimates the parameters"; [R] cfprobit (Example 2) says
that with a probit first stage one has "moved away from a structural
model" and defers to Wooldridge (2015) for when the APEs are "valid, or
approximately valid". Because apexog reproduces cfprobit exactly, the
property is inherited. Its size is not academic. In the
bivariate-normal design of the validation suite (y* = -0.2 + 0.6 d + 0.5
x + z'gamma + eps, d = 1[0.8 z + 0.4 x + v > 0], x, z, v standard normal,
corr(eps, v) = rho, gamma = 0, N = 400,000; true discrete-change APE
0.21065):
rho = 0.3: GR-CF two-step APE 0.20488 (bias -2.7%) recursive
bivariate probit 0.21071 (+0.0%)
rho = 0.5: GR-CF two-step APE 0.18632 (bias -11.6%) recursive
bivariate probit 0.20982 (-0.4%)
rho = 0.8: GR-CF two-step APE 0.10411 (bias -50.6%) recursive
bivariate probit 0.21083 (+0.1%)
The Murphy-Topel SE (about 0.003 here) is correctly sized for the
two-step estimator, so each bias is many standard errors; the validation
suite reproduces the rho = 0.8 row with both engines. The results header
therefore prints a note whenever a generalized-residual first stage is
used. For a 0/1 treatment whose error is plausibly jointly normal with
the outcome's, use firststage(biprobit); for fractional and count
treatments no exact analog is shipped and the same caveat applies.
Relatedly, the sigma_tilde conversion behind gunits(structural) is
derived for a linear first stage and should not be applied with these
first stages (simulation evidence under Gamma scale below and gunits()).
Recursive bivariate probit engine (firststage(biprobit)). With one 0/1
endogenous regressor d and (eps, v) bivariate normal with correlation
rho, the structural model with a possible exclusion-restriction violation
is the recursive bivariate probit
y* = x'beta_1 + d beta_d + z'gamma + eps, d* = z'pi_z + x'pi_x + v, y
= 1[y* > 0], d = 1[d* > 0].
At each gamma apexog fits biprobit (y = x d, offset(z'gamma)) (d = z x)
by maximum likelihood (robust or cluster-robust e(V), as requested) and
takes
APE = mean( Phi(x'beta_1 + beta_d + z'gamma) - Phi(x'beta_1 +
z'gamma) )
from the outcome equation: because eps is standard normal, Phi(.) is the
average structural function itself and nothing has to be averaged out.
The delta-method SE uses the closed-form Jacobian d/dbeta_1 = mean((phi_1
- phi_0) x), d/dbeta_d = mean(phi_1), d/dbeta_0 = mean(phi_1 - phi_0)
(zero for the treatment equation and athrho) against the joint-MLE e(V);
there is no generated regressor and hence no Murphy-Topel step. At gamma
= 0 the point estimate and SE equal margins, dydx(d) predict(pmarg1)
after biprobit with i.d. The UCI and LTZ machinery is unchanged:
gmin()/gmax(), mu()/omega(), distribution(), gunits(pr), the delta sweep,
and the graphs work exactly as for the control-function engine. Fits
after the baseline are warm-started from the baseline estimates. e(rho)
returns the estimated error correlation at the baseline fit.
AIE with the bivariate probit (version 0.22.0). With
firststage(biprobit) and a target such as target(i.d#i.m) or
target(i.d#c.m), where m is an exogenous control, apexog fits
biprobit (depvar = indepvars d*m d, offset(z'gamma)) (d = iv
indepvars)
The product d*m is a regressor of the outcome equation only. It is a
function of the treatment and an exogenous variable, and the treatment is
modelled jointly with the outcome, so the product needs no first stage or
control function of its own (with the control-function engine it does,
and that construction has no structural interpretation for a 0/1
treatment). The instruments may include the product of an instrument and
the moderator, which then carries its own violation. The target is the
interaction contrast of the average structural function under joint
normality:
binary m: AIE = mean( Phi(eta|1,1) - Phi(eta|1,0) - Phi(eta|0,1) +
Phi(eta|0,0) )
continuous m: AIE = mean( phi(eta|d=1)*(b_m + b_dm) -
phi(eta|d=0)*b_m )
with eta the outcome index at the counterfactual values of d and m. It
is not the conditional-on-control-function object of the control-function
engine. Identification of the interaction rests on joint normality of
the outcome and treatment errors and the (plausibly violated) exclusion
restriction, and on one error correlation and one treatment equation for
every value of the moderator. Under that restriction the interaction is
also identified from treatment variation the instrument does not
generate, so it can be far more precise than the instrumental-variable
contrast, and can differ from it; when the estimated correlation is near
zero it is close to the AIE of a probit that treats the treatment as
exogenous. Fitting biprobit separately for each value of a binary
moderator relaxes the restriction. The delta-method SE uses the
joint-MLE e(V) with a Jacobian built from the counterfactual design rows,
zero for the treatment equation and athrho. Validation: the AIE and its
SE equal margins r.d#r.m, predict(pmarg1) (binary m) and margins r.d,
dydx(m) predict(pmarg1) (continuous m) after biprobit written with factor
variables, at gamma = 0, at a nonzero violation, with the violation on
the interacted instrument and with vce(cluster), to 1e-10 or better. In
a simulation with bivariate-normal errors (correlation 0.5, n = 2,000,
300 replications per cell) the Wald interval at the true violation
covered the sample AIE 0.953 (binary m, no violation), 0.933 (binary m,
violation 0.1) and 0.967 (continuous m, violation 0.1), Monte Carlo SE
about 0.013. An AIE of two exogenous variables and a continuous
treatment are not supported with this engine.
Gamma scale with biprobit. The outcome-equation error of the recursive
bivariate probit has unit variance, so the probit-index and
structural-latent scales coincide: sigma_tilde = 1, e(stilde) = 1, and
gunits(structural) is accepted as identical to the default. The
probability-point scale (gunits(pr)) uses m_phi from the outcome equation
as usual.
LTZ interval construction. CHR (2012) eq. (7) approximates the
estimator's distribution as the INDEPENDENT sum of its sampling
distribution and the exogeneity-error term: betahat ~ N(beta, V) +
A*gamma, gamma ~ F. apexog implements the simulation form of this on the
APE/AIE scale: each draw refits the probit at gamma_i (giving the
bias-adjusted point estimate APE_i, the nonlinear analog of betahat -
A*gamma_i, with Murphy-Topel SE_i), and the sampling-noise term is then
convolved in:
APE*_i = APE_i + SE_i * eps_i, eps_i ~ N(0,1) independent of gamma_i
The reported level(#) interval is the percentile interval of {APE*_i}.
Because the noise term is symmetric, this equals CHR's pivot construction
[APE_0 - c_(1-a/2), APE_0 - c_(a/2)] with c_p the percentiles of the
simulated deviation distribution, and in the linear model it reproduces
plausexog's analytic V + A*Omega*A' interval (checked in the package's
validation suite). The prior-only percentile spread of the point APEs
{APE_i} is reported separately as a sensitivity band; it answers "how
does the bias-adjusted estimate move as gamma varies over the prior", not
"what is a confidence interval for the APE". For multiple targets the
eps draws are independent across targets, which is exact for the
per-target marginal intervals reported.
Gamma scale. The violation enters as an offset in the PROBIT-INDEX
latent equation: Pr(y=1) = Phi(... + z'gamma), where the probit
normalizes the error sd CONDITIONAL on the control functions to 1. Three
elicitation scales are supported, linked by two baseline-fit conversion
factors that are always reported in the header:
(i) probit-index units (the default, gunits(latent)): the scale of
the fitted probit coefficients. No conversion.
(ii) probability points (gunits(pr)): the instrument's direct effect
on Pr(y=1). Linked to index units by the average link slope
m_phi = mean(normalden(eta_hat)): gamma_index = gamma_pr / m_phi
(variances by m_phi^2). This makes apexog and plausexog (run as
an LPM on the binary outcome) comparable on a common violation
axis.
(iii) structural-latent units (gunits(structural)): the scale of y* =
xb + gamma*z + eps with TOTAL error variance 1 -- the scale
simulation DGPs and textbook latent-variable models are usually
written on. Linked to index units by sigma_tilde = sd(eps | CF):
gamma_index = gamma_structural / sigma_tilde (variances by
sigma_tilde^2), with sigma_tilde estimated from the
control-function coefficient(s) as sigma_tilde = (1 + b_cf'
Var(chat) b_cf)^(-1/2). This link is derived for a LINEAR first
stage, whose residual estimates the structural first-stage error;
it does not carry over to the generalized-residual first stages
(see the scope paragraph below).
Confusing scales (ii) and (iii) with (i) is not innocuous. Because
sigma_tilde < 1 under endogeneity, a structural-units prior fed to the
index unrescaled is uniformly too narrow by the factor sigma_tilde; for a
wide Gaussian prior the LTZ coverage of a nominal 1-alpha interval is
then 2*Phi(z*sigma_tilde)-1 rather than 1-alpha (about 0.88 instead of
0.95 when the endogeneity correlation is 0.6). Probability-scale
elicitation (gunits(pr)) is immune to this gap because the pr -> index
conversion already carries the correct scale. All conversions are local:
m_phi and sigma_tilde are evaluated at gamma = 0 and the mappings are
exact in the limit gamma -> 0. Both factors are stored in e(mphi) and
e(stilde). The exact probability-scale value of each refit's violation
(the average discrete change for a 0/1 instrument, the average derivative
otherwise) is reported alongside and stored in e(grid_pr) and
e(gamma_pr_sim); see gunits().
Scope of the sigma_tilde conversion. The derivation of (iii) uses a
linear first stage, whose residual estimates the structural first-stage
error v, so that sd(eps | CF) = sqrt(1 - rho^2). Monte Carlo simulations
(n = 5000, R = 1000 per cell, gamma_true = 0, 0.2, 0.5 entered in the
structural latent index, UCI box [-0.3, 0.3] on the index scale) confirm
it for the linear first stage -- the Wald interval from the refit at the
index-scale offset gamma_true/sqrt(1 - rho^2) covers the
conditional-on-CF APE 0.952 and 0.939 at gamma_true = 0.2 and 0.5, the
refit at the raw structural gamma only 0.536 and 0.014 -- and reject it
for the generalized-residual first stages: with a binary d and a probit
first stage (bivariate-normal design, rho = 0.5) the refit at the raw
gamma covers 0.936 against 0.590 for the refit at gamma/sqrt(1 - rho^2)
at gamma_true = 0.2; with a fractional d and an fprobit first stage (rho
= 0.4) 0.949 against 0.877; and interpolating the bias between the two
offsets puts the zero-bias offset at 0.195 and 0.518 (binary d), 0.200
and 0.524 (fractional d), and 0.206 and 0.516 (count d, Poisson first
stage, against the structural slope APE) for gamma_true = 0.2 and 0.5,
within 5% of the structural gamma in every case. So for those engines
the structural gamma enters the probit index essentially unscaled:
neither sqrt(1 - rho^2) nor e(stilde) (0.92, 0.92, 0.98 at gamma_true = 0
in those designs) is the model-implied factor, and for binary and
fractional d dividing by it moves the offset the wrong way (the coverage
losses 0.936 -> 0.590 and 0.949 -> 0.877 above). gunits(structural)
should therefore be used with a linear first stage only; with
firststage(probit), fprobit, or poisson apexog accepts it unchanged but
prints a warning line in the header. Consistently, the
firststage(biprobit) engine has sigma_tilde = 1. Note also that m_phi
and sigma_tilde are properties of the gamma = 0 baseline fit, which is
misspecified when the true violation is nonzero: in the same simulations
the mean e(stilde) is 0.80, 0.91, 1.00 with the linear first stage (true
sqrt(1 - rho^2) = 0.80) and 0.98, 0.93, 0.61 with the Poisson first stage
at gamma_true = 0, 0.2, 0.5: the omitted z'gamma term is partly absorbed
by the control-function coefficient through the first stage. Dividing by
the baseline factor is therefore an approximation even with a linear
first stage, and a structural value at or beyond |pi_z|/sigma_v has no
unique index-scale counterpart (v0.21.2: header line and warning,
e(gs_max)); see gunits().
Average Interaction Effect (with aie(X Z)). Three cases based on the
auto-detected types of X and Z:
cts x cts -- cross-partial averaged over the sample:
AIE = mean( phi(eta) * (b_XZ - eta * a * b) ),
a_i = b_X + b_XZ*Z_i, b_i = b_Z + b_XZ*X_i.
cts x bin (e.g. Z binary) -- firstdiff in Z of the X-derivative:
AIE = mean( phi(eta|Z=1)*(b_X+b_XZ) - phi(eta|Z=0)*b_X )
bin x bin -- 2nd discrete difference of Phi:
AIE = mean( Phi(eta|1,1) - Phi(eta|1,0) - Phi(eta|0,1) +
Phi(eta|0,0) )
The Jacobian wrt the full beta-vector (with special corrections for
b_X, b_Z, and b_XZ, derived per case) is formed in
closed form and passed through the same V_beta_MT. The delta-method
SE then incorporates the generated-regressor uncertainty from the first
stage. The point estimates are verified against hand-coded analytic
references to machine precision in all three cases, and the standard errors
against a two-step influence function whose derivatives are all taken
numerically.
Binary-by-binary standard errors (fixed in version 0.22.0). In the
second difference the two interactors and their product enter each
counterfactual index at the values j, k and j*k, so their Jacobian
entries are mean(phi_11 - phi_10), mean(phi_11 - phi_01) and
mean(phi_11). Versions through 0.21.2 used j - X_i, k - Z_i and j*k -
X_i*Z_i instead, which is wrong for every observation with X_i = 1 or Z_i
= 1. The point estimate was unaffected; the standard error of a
binary-by-binary AIE with the control-function engine was wrong (in the
validation data the corrected SE is 13% larger with a probit first stage
and 3% larger with linear first stages). The continuous-by-continuous
and continuous-by-binary cases were and are correct.
References
Conley, T. G., C. B. Hansen, and P. E. Rossi. 2012. Plausibly
Exogenous. Review of Economics and Statistics 94: 260-272.
Murphy, K. M., and R. H. Topel. 1985. Estimation and Inference in
Two-Step Econometric Models. Journal of Business & Economic
Statistics 3: 370-379.
Wooldridge, J. M. 2014. Quasi-maximum likelihood estimation and testing
for nonlinear models with endogenous explanatory variables. Journal
of Econometrics 182: 226-234. [Section 6, discussion following eq.
(66): with a binary endogenous regressor the control-function and
bivariate-probit assumptions differ and "neither set subsumes the
other"; the CF model is "only an approximation".]
Wooldridge, J. M. 2015. Control function methods in applied
econometrics. Journal of Human Resources 50: 420-445. [p. 442: the
sufficiency assumption D(u | z, y2) = D(u | r2) (his eq. 53) under
which the generalized-residual probit identifies the APE; "under the
standard bivariate probit assumptions, there is no known CF method
that consistently estimates the parameters".]
Clarke, D. 2020. plausexog: Stata module for plausibly exogenous 2SLS.
Statistical Software Components S458310, Boston College Department of
Economics. [This package targets the structural coefficient; apexog
adapts the same framework to target the APE in a cfprobit model.]
Radean, M. 2023. ginteff: A generalized command for computing
interaction effects. Stata Journal 23: 301-335. [apexog's aie()
option targets the same AIE quantity as ginteff, but adds
Conley-Hansen-Rossi sensitivity bounds and a Murphy-Topel correction
for the generated regressor.]
Author
Jesper N. Wulff, Department of Economics and Business Economics, Aarhus
University. jwulff@econ.au.dk
License
apexog is distributed under the MIT License. Copyright (c) 2026 Jesper
N. Wulff. See LICENSE for the full text.
Also see
Manual: [R] cfprobit, [R] cfregress, [R] biprobit, [R] ivprobit, [R]
margins