help for causalrep iv

Title

causalrep iv -- Quantifying the internal validity and representativeness of the
IV estimand

Syntax

causalrep iv
indepvars
[if] [in],
treatment(varname) instrument(varname) [options]

Required
treatment(varname) specify a treatment variable coded 0 for untreated observations
and 1 for treated observations

instrument(varname) specify an instrumental variable coded 0 for observations not
encouraged and 1 for observations encouraged to be treated

Optional
outcome(varname) specify an outcome variable; if omitted, no outcome regression
is estimated

ivmodel(string) specify the model for the instrument propensity score; regress (linear
probability model), logit, and probit are allowed; in principle, only regress
is supported by theory; default is regress

fsmodel(string) specify the model for the conditional mean of treatment, estimated separately
for observations encouraged and not encouraged to be treated; regress (linear probability model),
logit, and probit are allowed; default is logit

cate(varname) specify a variable that stores the values of the conditional
(local) average treatment effect (CATE) function; cate() requires outcome() to be specified

pstolerance(#) set tolerance for overlap assumption; the default value is 1e-5;
causalrep iv will exit with an error if an observation has an estimated instrument propensity score
smaller than that specified by pstolerance() or larger than one minus that specified by pstolerance()

osample(newvar) create an indicator variable newvar that identifies observations
that violate the overlap assumption

noisily display the outcome-regression results when outcome() is specified

vce(vcetype) specify the variance estimator for the IV outcome regression; vcetype
may be unadjusted, robust, cluster clustvar, bootstrap, jackknife,
or hac kernel; vce() is relevant only when outcome() is specified; default
is robust

Description

causalrep iv estimates the measure of internal validity (MIV) and the measure of
representativeness (MR) of the IV estimand, as proposed by Poirier and Słoczyński (2026). Under
instrument validity, monotonicity, and when the instrument propensity score lies in the linear
span of the included controls, this estimand can be written as a weighted average of conditional
(local) average treatment effects, with weights proportional to the conditional variance of
the instrument.

When the CATE function is unrestricted and the weights are nonnegative, the MIV equals the
inverse maximum weight. It is the largest possible share of the complier subpopulation for
which the IV estimand can be represented as an average treatment effect. By contrast, the MR
is the largest possible share of the entire population for which such a representation is
possible. It is equal to the product of the MIV and the proportion of compliers.

When negative estimated weights are detected, the value reported as MIV when the CATE function
is unrestricted is the inverse maximum weight. If any population weights are negative, the
unrestricted-CATE MIV and MR are zero. See Poirier and Słoczyński (2026) for details.

If outcome() is omitted, the command estimates the MIV and MR using only the instrument,
the treatment, and control variables. If outcome() is specified, the command also
estimates the IV coefficient and posts its coefficient vector and variance–covariance matrix.

If cate() is specified, the command additionally estimates the MIV and MR given the
supplied CATE function. The supplied CATE values are treated as fixed, and their estimation
uncertainty is not incorporated. They are required to be nonmissing for every observation in
the estimation sample.

The command assumes the monotonicity direction in which encouragement weakly increases
treatment. If the average estimated conditional first stage is negative, the command issues
a warning. When cate() is specified, the command returns an error if any estimated
conditional complier share is negative.

outcome() is required when cate() is specified because the CATE-based calculation
compares the supplied CATE values with the estimated IV coefficient.

If the IV estimate lies outside the range of the supplied CATE values, the CATE-based MIV is
zero. If the IV estimate equals the mean of the supplied CATE values weighted by the estimated
conditional complier shares, the CATE-based MIV is one. The CATE-based MIV can be positive even
when the unrestricted-CATE measure is zero.

This is a companion software package for Poirier and Słoczyński (2026). Please cite this paper
if you use causalrep iv in your work.

References

Poirier, Alexandre, and Tymon Słoczyński (2026). "Quantifying the Internal Validity
of Weighted Estimands." arXiv preprint arXiv:2404.14603. Available at https://arxiv.org/abs/2404.14603.

Examples

Load data from Angrist (1990):

. use https://tslocz.github.io/sipp.dta, clear

Drop incomplete observations:

. drop if kwage==. | educ==. | rsncode==999

Estimate the MIV of the IV estimand:

. causalrep iv i.age_5, t(nvstat) i(rsncode)

Generate the outcome variable:

. generate double lwage = ln(kwage)

Estimate the conditional LATE using teffects ra:

. teffects ra (lwage i.age_5) (rsncode)

. predict double rf, te

. teffects ra (nvstat i.age_5) (rsncode)

. predict double fs, te

. generate double cate = rf/fs

Attempt to estimate the MIV of the IV estimand using the estimated conditional LATE values:

. causalrep iv i.age_5, t(nvstat) i(rsncode) o(lwage) cate(cate)

Because some estimated conditional first stages are negative, restrict attention to covariate cells with nonnegative estimated first stages:

. causalrep iv i.age_5 if fs>=0, t(nvstat) i(rsncode) o(lwage) cate(cate)

Display stored estimation results:

. ereturn list

Stored results

causalrep iv stores the following in e():

Always stored

e(N) number of observations

e(miv) estimate of the inverse maximum weight; this is the MIV when the conditional LATE function is unrestricted and the weights are nonnegative

e(mr) product of the estimate of the inverse maximum weight and the proportion of compliers; this is the MR when the conditional LATE function is unrestricted and the weights are nonnegative

e(cmdline) command line

e(cmd) causalrep

e(subcmd) iv

e(sample) marks estimation sample

Only when outcome() is specified

e(iv) estimated coefficient on the treatment variable in the IV regression

e(depvar) name of dependent (outcome) variable

e(b) estimated coefficient vector, as obtained by ivregress

e(V) estimated variance–covariance matrix, as obtained by ivregress

e(df_r) residual degrees of freedom, as obtained by ivregress

Only when cate() is specified

e(late) estimate of the LATE based on the supplied conditional LATE values

e(miv_cate) estimate of the MIV based on the supplied conditional LATE values

e(mr_cate) estimate of the MR based on the supplied conditional LATE values

License

This package is licensed under the MIT License. See the LICENSE
file included with the distribution.

Authors

Alexandre Poirier, Georgetown University

Email: alexandre.poirier@georgetown.edu

Tymon Słoczyński, Brandeis University

Email: tslocz@brandeis.edu