*! version 1.0.11 9sept2014
help weakiv10

Title

weakiv10 - Weak-instrument-robust tests and confidence intervals
for instrumental-variable (IV) estimation of linear, probit and tobit models

Note

weakiv10 is an older version of weakiv suitable for Stata 10
without many of the extensions available in the latter.
Users with Stata 11 or later are recommended to install and use weakiv.

Syntax

Standalone estimation (specifying model to be estimated):

weakiv10
iv_cmd
depvar [varlist1]
(varlist2=varlist_iv) [weight]
[if exp] [in range]
[, model_options
test_options ci_options graph_options misc_options]

Obtaining model from previous call to ivregress, ivreg2, ivreg2h,
xtivreg, xtivreg2, ivprobit, or ivtobit:

weakiv10
[, test_options ci_options graph_options misc_options]

Replay syntax:

weakiv10
[, graph_options misc_options]

iv_cmd/model_options

iv_cmd
ivregress, ivreg2, ivreg2h, xtivreg, xtivreg2, ivprobit, or ivtobit

<misc>
options supported by ivregress, ivreg2, ivreg2h, xtivreg, xtivreg2, ivprobit or ivtobit

test_options

null(#)
null hypothesis for test of coefficient on single endogenous variable in IV model

kwt(#)
weight on K test statistic in K-J test (see also kjlevel(.) option below)

lm
use LM instead of default Wald/Minimum Distance tests (linear models only)

small
makes small-sample adjustment

2-endogenous-regressor usage
null1(#)
value under the null hypothesis for test of coefficient on endogenous regressor 1

null2(#)
value under the null hypothesis for test of coefficient on endogenous regressor 2

strong(varname)
name of strongly-identified endogenous regressor (if only 1 of the 2 is weakly identified)

ci_options

points(#)
number of grid points for confidence-interval estimation

gridmult(#)
multiplier of Wald confidence-interval for grid

gridlimits(numlist)
lower and upper limits for grid for confidence-interval estimation

grid(numlist)
explicit list of grid points for confidence-interval estimation

usegrid
force grid-based confidence-interval estimation in homoskedastic linear IV

level(numlist)
default confidence level(s) for confidence intervals and sets (max 3)

arlevel(#)
optional confidence level for AR confidence intervals

jlevel(#)
optional confidence level for J confidence intervals

kjlevel(#)
(usage 1) optional overall confidence level for K-J confidence intervals and tests

kjlevel(#k #j)
(usage 2) optional separate confidence levels for K and J in K-J confidence intervals and tests

noci
supress reporting/calculation of confidence intervals

2-endogenous-regressor usage
points1(#)
number of grid points on axis 1 (x)

points2(#)
number of grid points on axis 2 (y)

grid1(numlist)
explicit list of grid points for axis 1 (x)

grid2(numlist)
explicit list of grid points for axis 2 (y)

gridlimits1(numlist)
upper/lower limits of grid axis 1 (x)

gridlimits2(numlist)
upper/lower limits of grid axis 2 (y)

graph_options

graph(namelist)
graph test rejection probabilities and confidence intervals (ar, clr, k, j, kj, wald)

graphxrange(numlist)
lower and upper limits of x axis for graph of test statistics
(option unavailable for 2-endogenous regressor case)

graphopt(string)
graph options to pass to graph command
(applies to combined contour/surface graph in 2-endogenous regressor case)

2-endogenous-regressor usage
contouropt(string)
graph options to pass to contour graph command

surfaceopt(string)
graph options to pass to surface graph command

contouronly
do contour plot (confidence set) only; suppress surface plot

surfaceonly
do surface plot (rejection probability surface) only; supress contour plot

misc_options

estadd[(prefix)]
add main weakiv10 results (scalars and macros) to model estimated by IV for Wald tests;
estimation results obtained from previous call to
ivregress, ivreg2, ivreg2h, ivprobit or ivtobit
remain in memory with weakiv10 results added;
prefix is an optional prefix added to names of scalars and macros
(not available with replay syntax)

estusewald(name)
obtain IV model from stored previous estimation by
ivregress, ivreg2, ivreg2h, ivprobit and ivtobit

eststorewald(name)
store IV model used for Wald tests
(estimated by ivregress, ivreg2, ivreg2h, ivprobit or ivtobit)
under name

displaywald
display model estimated by IV for Wald tests
(not available with replay syntax)

Contents

Description

Tests, confidence intervals, rejection probabilities

Summary interpretations of weakiv10 output: 1 endogenous regressor

Summary interpretations of weakiv10 output: 2 endogenous regressors

Options

Model options

Test options

Confidence interval estimation

Graphing options

Miscellaneous options

Estimation and testing examples

Confidence interval and grid examples

Graphing examples

estadd option and other miscellaneous examples

Saved results

Acknowledgements

References

Citation of weakiv10

Description

weakiv10 performs a set of tests of the coefficient(s) on the endogenous variable(s)
in an instrumental variables (IV) model,
and constructs confidence sets for these coefficients.
These tests and confidences are robust to weak instruments
in the sense that identification of the coefficients is not assumed.
This is in contrast to the traditional IV/GMM estimation methods,
where the validity of tests on estimated coefficients requires the assumption that they are identified.

weakiv10 can be used to estimate linear (including panel fixed effects and first diffences),
probit and tobit IV models with one or two endogenous regressors.
weakiv10 supports a range of variance-covariance estimators for linear IV models
including heteroskedastic-, autocorrelation-, and one- and two-way cluster-robust VCEs.
weakiv10 also provides graphics options that allow the plotting of
confidence intervals and rejection probabilities (one endogenous regressor),
and confidence regions and rejection surfaces (two endogenous regressors).

weakiv10 can be used either as a standalone estimator
where the user provides the specification of the model,
or after previous IV estimation by ivregress, ivreg2, ivreg2h,
xtivreg, xtivreg2, ivprobit, or ivtobit.

When used as a standalone estimator,
weakiv10 works by calling ivregress, ivreg2, ivreg2h,
xtivreg, xtivreg2, ivprobit, or ivtobit
depending what the user has specified as iv_cmd.
weakiv10 passes all user-specified model estimation options
to the estimation command:
variable lists, VCE specification, estimation method, etc.

When used with a model previously estimated by
ivregress, ivreg2, ivreg2h,
xtivreg, xtivreg2, ivprobit, or ivtobit,
weakiv10 obtains the model specification from the previous estimation.
This is either the model currently in memory,
or the stored model provided by the user in usemodel(name).

weakiv10 also supports Stata replay syntax.
If the weakiv10 results are the current estimation in memory,
weakiv10 with no model specified will replay them.
This can be used to tweak the graph options
without weakiv10 having to recalculate the full set of estimation results (see below).

For linear IV estimation including panel fixed effects and first differences,
weakiv10 supports all the variance-covariance estimation options available
with ivregress, ivreg2, ivreg2h, xtivreg and xtivreg2.
When used with ivreg2h
(IV estimation using heteroskedasticity-based instruments)
the gen option of ivreg2h is required
in order to generate the new instruments;
see ivreg2h.
For IV probit and IV tobit estimation,
weakiv10 supports only variance-covariance estimation options that assume
homoskedasticity (that is, all variance-covariance options except
vce(robust) and vce(cluster clustvar)).
For IV probit estimation,
weakiv10 supports only estimation using Newey's (1987) two-step estimator,
and the twostep option is required;
see help ivprobit.
Weights that are supported by each IV command are also supported by weakiv10.

weakiv10 requires avar (Baum and Schaffer 2013) to be installed.
The graphing options for the 2-endogenous-regressor case require Stata 12 or higher
for the contour plots of confidence regions,
and require version 1.06 or higher of (helpb surface} (Mander 2005)
for the 3-D plots of rejection surfaces.
weakiv10 will prompt the user for installation of
avar and surface if necessary.
avar is an essential component and weakiv10 will not run without it.
Neither graph contour nor surface is an essential component;
weakiv10 will run but will not provide the corresponding graphs.

Tests, confidence intervals, rejection probabilities

weakiv10 calculates minimum distance (MD) or Lagrange multiplier (LM)
versions of weak-instrument-robust tests of the coefficient
on the endogenous variable beta in an instrumental variables (IV) estimation.
In an exactly-identified model where the number of instruments
equals the number of endogenous regressors,
it reports the Anderson-Rubin (AR) test statistic.
When the IV model contains more instruments than endogenous regressors
(the model is overidentified),
weakiv10 also conducts the conditional likelihood ratio (CLR) test,
the Lagrange multiplier K test, the J overidentification test,
and a combination of the K and overidentification tests (K-J).
The default behavior of weakiv10 is to report MD versions of these tests;
for linear models, these are equivalent to Wald-type tests.
weakiv10 can optionally report instead LM-type versions of
the AR, K, J and K-J tests.
In the current implementation of weakiv10,
the CLR test is available for the 1-endog-regressor case only.
For reference, weakiv10 also reports a Wald test
using the relevant traditional IV parameter and VCE estimators.

The AR test is a joint test of the structural parameter
(beta=b0, where beta is the coefficient on the endogenous regressor)
and the exogeneity of the instruments
(E(Zu)=0, where Z are the instruments
and u is the disturbance in the structural equation).
The AR statistic can be decomposed into the K statistic
(which tests only H0:beta=b0,
assuming the exogeneity conditions E(Zu)=0 are satisfied)
and the J statistic
(which tests only H0:E(Zu)=0,
assuming that beta=b0 is true).
This J statistic is evaluated at the null hypothesis,
as opposed to the Hansen J statistic from GMM estimation,
which is evaluated at the parameter estimate.

The CLR test is a related approach to testing H0:beta=b0.
It has good power properties,
and in particular is the most powerful test for the linear model under homoskedasticity
(within a class of invariant similar tests).
An important advantage of the CLR test over the K test is that
the K test can lose power in some regions of the parameter space
when the objective function has a local extremum or inflection point;
the CLR test does not suffer from this problem.

The K-J test combines the K and J statistics to jointly test
the structural parameter and the overidentifying restrictions.
It is more efficient than the AR test and allows different weights or test levels
to be put on the parameter and overidentification hypotheses.
Unlike the K test when used on its own,
the K-J test does not suffer from the problem of spurious power losses.
To perform the K-J test, the researcher specifies
the significance levels alpha_K and alpha_J for
the K and J statistics.
Because the K and J tests are independent,
the null of the K-J test is rejected
if either p_K<alpha_K
or p_J<alpha_J,
where p_K and p_J are the K and J p-values, respectively.
The overall size of the K-J test is given by (1-(1-alpha_K)*(1-alpha_J)).

The default behavior of weakiv10 is for the user to choose
the overall size of the K-J test
and the weights kwt and (1-kwt) to put on
the K and J components, respectively.
Alternatively, the user may specify
the separate significance levels alpha_K and alpha_J,
from which the overall K-J test size and weights are calculated.
The p-value function for the K-J test is
p=min(p1,p2), where
p1=(p_K/kwt)*(1-(1-kwt)*p_K) and
p2=(p_J/(1-kwt))*(1-kwt*p_J).
For large L% (e.g., 95%),
this is approximately equivalent to
rejecting the null at the (100-L)% significance level if
K is greater than the kwt*(100-L)% critical value or
J is greater than the (1-kwt)*(100-L)% critical value.
For example, if kwt=0.8 and (100-L)=5%,
then the text rejects if the p-value for the K test is below 4%
or the p-value for the J test is below 1%
(because (1-(1-0.04)*(1-0.01))=0.0496 which is approximately 0.05).

For the single-endogenous-regressor case,
weakiv10 also inverts these tests to obtain and report
weak-instrument-robust confidence intervals and
(with the graph(.) option),
the corresponding rejection probabilities.
In a graph of rejection probabilities,
an L% confidence interval is readily visualized
as the range of values for b0
such that the rejection probability for the statistic
lies below a horizontal line drawn at L%.
In the case of estimation of the linear model under the assumption of homoskedasticity and independence,
weakiv10 uses a closed-form solution for these confidence intervals.
In all other specifications,
weakiv10 estimates confidence intervals by grid search.

For the 2-endogenous-regressors case,
weakiv10 uses a grid search and graphical methods
to report the corresponding confidence regions
and rejection probabilities.
In this case, the rejection probabilities form a 3-D rejection surface
where beta1, the coefficient on endogenous regressor 1, is plotted against the x-axis,
beta2, the coefficient on endogenous regressor 2, is plotted against the y-axis,
and the rejection probability is plotted against the z-axis (vertical axis).
An L% confidence region is the set of values
for b1 and b2 such that
the null hypothesis H0:beta1=b1 and beta2=b2 cannot be rejected.
In a 3-D graph of the rejection probability surface,
an L% confidence region is readily visualized
as the range of values for b1 and b2
such that the rejection surface lies below a horizontal plane drawn at L%.

A special case arises when there are 2 endogenous regressors,
but one coefficient is weakly identified and one is strongly identified.
weakiv10 supports this via the strong(.) option;
the option is available for linear models only.
By convention, the weakly-identified endogenous coefficient is #1
and the strongly-identified endogenous coefficient is #2.
Testing in this case follows the method of Kleibergen (2004);
see Mikusheva (2013) for a concise description.
For a given hypothesized value for the weakly-identified coefficient,
the method first estimates the strongly-identified coefficient
using an efficient estimator
(2SLS in the i.i.d. case or 2-step efficient GMM in the non-i.i.d. case),
and then calculates the test statistic
using the same expressions as for the 2-endogenous-regressor case,
the hypothesized value for the weakly-identified coefficient,
but the estimated value for the strongly-identified coefficient.
To obtain confidence intervals and rejection probabilities,
the procedure is repeated for each hypothesized value
of the weakly-identified coefficient.
Testing, graphing and other options follow the syntax
for the 1-endogenous-regressor case.

The default tests implemented by weakiv10 are the Magnusson (2010) minimum-distance (MD) versions of
the weak-identification-robust tests introduced by
Anderson and Rubin (1949),
Kleibergen (2002, 2005) and Moreira (2003).
For the linear models supported by weakiv10,
including the panel data fixed effects and first differences models,
the MD versions are equivalent to Wald versions of these tests.
When the lm options is specified,
weakiv10 reports the Kleibergen (2002, 2005) LM versions
of the AR, K, J and K-J tests for linear models
(and the Kleibergen (2005) GMM generalization of Moreira's CLR statistic
for non-iid linear models only).
In the construction of the LM versions of the tests,
any exogenous regressors are first partialled out.
For further discussion of these tests,
see Finlay and Magnusson (2009),
Magnusson (2010),
Kleibergen (2002, 2005),
Moreira (2003),
Chernozhukov and Hansen (2005, 2008),
and the references therein.

Summary interpretations of weakiv10 output: 1 endogenous regressor

The following summarizes what the various statistics assume and test
in the single-endogenous-regressor case, and how to interpret the results.
The interpretations are similar for the 2-endogenous-regressor case
when only one coefficient is weakly identified.
The structural parameter, beta, is the coefficient on the endogenous regressor;
b0 is a hypothesized value for beta;
the excluded instruments are Z;
the assumption that the instruments are exogenous is E(Zu)=0.
Roughly speaking,
a well-specified model is one in which
H0:beta=b0 cannot be rejected for a narrow range of hypothesized values b0
(i.e., beta is precisely estimated}
and the assumption of instrument exogeneity
cannot be rejected for a wide range of hypothesized values b0
(i.e., the exogeneity assumption is generally satisified).

An L% confidence interval is
the range of b0 such that the rejection probability (=1-pvalue) is below L%.
Users can use the graph(.) option to plot rejection probabilities.
The confidence intervals reported by weakiv10 can, in overdidentified models,
be empty, disjoint (composed of unconnected segments), open-ended,
or cover the entire range of possible values for beta.
An empty confidence interval (null set) means there is no possible value b0
that is consistent with the model;
this is an indication of misspecification when L% is fairly high.
Disjoint confidence intervals arise when the plot of the rejection probability
dips below L% in more than one range;
an example is when the K statistic has inflection points or local minima
that cause spurious power losses
(inspection of a graph of the K rejection probability is a way of detecting this).
Open-ended confidence intervals commonly arise when the grid
does not extend far enough to capture the point where the rejection probability
crosses above the L% line.
Interpretation of an L% confidence interval that covers
the entire grid range of possible values for beta
depends on the null hypothesis tested:
if the null hypothesis is H0:beta=b0,
it suggests the parameter beta is poorly identified or unidentified;
if the null hypothesis is H0:E(Zu)=0,
it suggests the exogeneity conditions are generally satisfied.

Summary of specific tests:

CLR
The null hypothesis is H0:beta=b0.
The exogeneity conditions E(Zu)=0 are assumed to be satisfied.
An L% confidence interval is the set of all values b0 such that
the null hypothesis beta=b0 cannot be rejected at the (100-L)% significance level.

K
The null hypothesis is H0:beta=b0.
The exogeneity conditions E(Zu)=0 are assumed to be satisfied.
An L% confidence interval is the set of all values b0 such that
the null hypothesis beta=b0 cannot be rejected at the (100-L)% significance level.

J
The null hypothesis is H0:E(Zu)=0.
The structural parameter is assumed to be beta=b0.
An L% confidence interval is the set of all values b0 such that
the null hypothesis E(Zu)=0 cannot be rejected at the (100-L)% significance level.
Note the differences in the null hypothesis
and interpretation of confidence intervals
vs. the CLR and K statistics.

K-J
(usage 1, specifying overall test level and weights on K and J)
The null hypothesis is
H0:beta=b0 and H0:E(Zu)=0.
For a test at significance (100-L)%
with weights on the K and J tests
of kwt and (1-kwt), respectively,
the null is rejected if
either
(a) K is greater than the critical value for
a test at the kwt*(100-L)% significance level,
or
(b) J is greater than the critical value for
a test at the (1-kwt)*(100-L)% significance level.
(This is interpretation is an approximation;
see the text above for the exact definition.)
An L% confidence interval is the set of all values b0 such that
the composite null hypothesis cannot be rejected at the (100-L)% significance level.

K-J
(usage 2, specifying test levels separately for K and J)
The null hypothesis is
H0:beta=b0 and H0:E(Zu)=0.
For a test at significance alpha_K for the K test
and alpha_J for the J test,
the null is rejected if
either
(a) K is greater than the critical value for
a test at the alpha_K significance level,
or
(b) J is greater than the critical value for
a test at the alpha_J significance level.
The significance level for the overall test is
(1-(1-alpha_K)*(1-alpha_J)).
An L% confidence interval is the set of all values b0 such that
the composite null hypothesis cannot be rejected at the (100-L)% significance level.

AR
The null hypothesis is
H0:beta=b0 and H0:E(Zu)=0.
For a test at significance (100-L)%
the null is rejected if
either (a) H0:beta<>b0,
or (b) H0:E(Zu)<>b0.
An L% confidence interval is the set of all values b0 such that
the composite null hypothesis cannot be rejected at the (100-L)% significance level.

Wald
The null hypothesis is
H0:beta=b0.
Identification of beta in the IV estimation is assumed to be strong.
An L% confidence interval is the set of all values b0 such that
the null hypothesis cannot be rejected at the (100-L)% significance level.

Summary interpretations of weakiv10 output: 2 endogenous regressors

The following summarizes what the various statistics assume and test
in the two-endogenous-regressors case, and how to interpret the results.
The structural parameters, beta1 and beta2,
are the coefficients on the endogenous regressors;
b1 and b2 are hypothesized values for beta1 and beta2, respectively.
Roughly speaking,
a well-specified model is one in which
H0:beta1=b1 and beta2=b2 cannot be rejected
for a narrow range of hypothesized values b1 and b2
(i.e., beta1 and beta2 are precisely estimated}
and the assumption of instrument exogeneity
cannot be rejected for a wide range of hypothesized values b1 and b2
(i.e., the exogeneity assumption is generally satisified).

An 2-dimensional confidence set is a straightforward extension
of a 1-dimensional confidence interval.
An L% confidence set is
the range of b1 and b2 such that
the rejection probability (=1-pvalue) is below L%.
weakiv10 uses graphical methods to report confidence sets and rejection probabilities;
these are specified using the graph(.) option.
A confidence set is graphed in x-y space as a contour plot
using Stata 12's graph twoway contour.
Up to 3 confidence levels can be specified using the levels(.) option;
these will be plotted as lower/higher contours in the contour plot.
The rejection probability is graphed in x-y-z space using Mander's (2005) surface;
the contours plotted by contour are the contours of this surface.
The confidence sets plotted by weakiv10 can, in overdidentified models,
be empty, disjoint (composed of unconnected regions), open-ended, etc.
An empty confidence set (null set) means
there is no possible combination of values b1 and b2
that is consistent with the model;
this is an indication of misspecification when L% is fairly high.
Disjoint confidence regions arise when the rejection probability surface
dips below L% in more than one range.
Open-ended confidence regions commonly arise when the grid
does not extend far enough to capture the point where the rejection probability
crosses above the L% plane.

Options

Model options (when used for standalone estimation)

iv_cmd specifies the IV estimator to use:
ivregress, ivreg2, ivreg2h,
xtivreg, xtivreg2, ivprobit or ivtobit.
This option is valid only when weakiv10
is used for standalone estimation and the details of the model
are also provided; see Syntax above.

Testing

null(#) specifies the null hypothesis for the coefficient on the
endogenous variable in the IV model. The default is
null(0).
The null1(#) and null2(#) options can be used
to specify the null for the 2-endog-regressor case;
the default null is 0 for both coefficients.

kwt(#) is the weight put on the K test statistic in the K-J test.
The default is kwt(0.8).
It may not be used with the kjlevel(#k #j) option; see below.

lm specifies that LM tests instead of
the default Wald/Minimum Distance tests are reported (linear models only).

strong(varname) specifies that,
in a 2-endogenous-regressor estimation,
the endogenous regressor varname is strongly identified (linear models only).
Tests and graphs are reported for the weakly-identified regressor only.

small specifies that small-sample adjustments be made when test
statistics are calculated for linear IV estimation.
When used in standalone estimation by weakiv10,
the default is not to employ small-sample adjustments.
When used after estimation by ivregress, ivreg2 or ivreg2h,
the default is given by whatever small-sample
adjustment option was chosen in the IV command.
Small-sample adjustments are always made for IV probit and IV tobit estimation.
The default small-sample adjustment is N/(N-L)
where L is the number of exogenous variables (regressors and instruments);
for the fixed effects estimator, L includes the number of fixed effects;
if a cluster-robust VCE is used, the small-sample adjustment is
N_clust/(N_clust-1)*(N-1)/(N-L),
where N_clust is the number of clusters.

Confidence interval estimation

noci requests that confidence intervals not be estimated/reported.
Grid-based test inversion can be time-intensive,
so this option can save time if a grid search is not required,
either because confidence intervals are not needed
or because a closed-form solution for confidence intervals is available
(the linear model with homoskedastic errors only).

points(#) specifies the number of equally spaced values over
which to calculate the confidence sets.
In the single endogenous regressor case,
the default is points(100) and the maximum number of points is points(800).
In the 2-endog regressor case,
the defaults are points1(10) and points2(10),
and can either be set separately or set simultaneously by points(#);
the total number of values in the grid over which the search takes place
will be points1(#)*points2(#).
Increasing the number of grid points will increase the time required to
estimate the confidence intervals, but a greater number of grid points will
improve precision.

Note: The default grid is centered around the point estimate
with a width equal to twice the Wald confidence interval.
With weak instruments,
this is often too small of a grid to estimate the confidence intervals and sets.

gridmult(#) is a way of specifying a grid to calculate confidence sets.
This option specifies that the grid be # times the size
of the Wald confidence interval. The default is gridmult(2).

gridlimits(numlist) is another way of specifying
the grid to calculate the confidence sets.
The user provides the lower and upper limits in numlist.
This option is not compatible with gridmult(#)
and will override it if it is also specified.
For the 2-endogenous regressor case,
the limits are specified separately for the two regressors using
the gridlimits1(numlist) and gridlimits2(numlist) options.

grid(numlist) allows the user to list explicitly
the numeric values of the grid points over which to calculate the confidence sets.
This option is not compatible with any other grid options
and will override them if they are also specified.

usegrid forces grid-based test inversion for confidence-interval
estimation under the homoskedastic linear IV model. The default is to use the
analytic solution. Under the other models, grid-based estimation is the only
method.

level(#) specifies the default confidence level,
as a percentage, for confidence intervals.
The default is level(95) or as set by set level.
Changing level(#) also changes the level of significance
used to determine this result: [100-level(#)]%.
Up to 3 levels can be provided as level(numlist);
this option is useful for graphing,
when multiple confidence intervals or confidence sets
corresponding to different confidence levels
can be represented in the same graph.
If more than one level is provided, the first is used for tests.
The option can also be used to tweak graphs when weakiv10's replay syntax is used.

arlevel(#) optionally specifies the confidence level, as a percentage,
for the AR confidence interval if different from the default confidence level.

jlevel(#) optionally specifies the confidence level, as a percentage,
for the J confidence interval if different from the default confidence level.

kjlevel(#) (usage 1) optionally specifies the overall confidence level, as a percentage,
for the K-J confidence interval if different from the default confidence level.

kjlevel(#k #j) (usage 2) optionally specifies the separate confidence levels,
as percentages, for the K and J tests in the construction of
the K-J test and confidence intervals.
The overall test level will be (1-(1-#k/100)*(1-#j/100)).
Note that this implicitly specifies the weight on the K and J tests
and may not be used with the kwt(#) option.

Graphing

graph(string) specifies the test rejection probabilities
to plot vs. the hypothesized value for the structural parameter.
Options available are ar, k, j, clr (1-endog-regressor case only),
kj, wald and all.
Fo exactly-identified models only ar and wald are available.
They may be specified in lower or upper case.
For the 1-endogenous-regressor case,
colors for the different rejection probabilities are preassigned
and do not change with the order or list of tests specified.
Default colors can be overridden with the graphopt(string) option.

graphxrange(numlist) allows the user to specify
the range of the x-axis in graph of rejection probabilities.
It is equivalent to adding "if x>=ll & x<=ul" in a Stata graph command,
where ll and ul are the lower and upper limits for the x-axis, respectively.
(NB: This option is not available for the 2-endogenous-regressor case.)
This option does not affect the limits of the grid search;
to specify these, use the gridlimits(numlist) option.

graphopt(string) allows the user to specify additional graphing options,
such as titles, subtitle, colors, etc.
For the 1-endogenous-regressor case the internal graph command is scatter,
and weakiv10 will pass the full contents of graphopt(string) to it.
For the 2-endogenous-regressor case the internal graph command is graph combine
(to combine the contour and surface plots),
and weakiv10 will pass the full contents of graphopt(string) to it.

contouropt(string) allows the user to specify additional graphing options
to the internal call to Stata's graph contour or graph contourline commands.
The default is to produce contour line graphs using graph contourline;
to request shaded contour graphs using graph contour,
specify contouropt(contourshade ...).

surfaceopt(string) allows the user to specify additional graphing options
to the internal call to Mander's (2005) surface command.

contouronly (2-endogenous-regressor case only)
specifies that only the contour plot (confidence set) is graphed;
the surface plot is not provided.

surfaceonly (2-endogenous-regressor case only)
specifies that only the surface plot (surface of rejection probabilities) is graphed;
the contour plot is not provided.

Miscellaneous options

estadd[(prefix)] causes weakiv10) to mimic the behavior of estadd (Jann 2009).
When it is omitted, weakiv10 works like most eclass commands in Stata
and leaves behind in memory the full set of weakiv10 saved results and nothing else.
When estadd is specified,
weakiv10 leaves behind in memory the results of command used to estimate the IV model
(ivregress, ivreg2, ivreg2h, ivprobit or ivtobit)
but with weakiv10 results added to the estimation results (macros and scalars).
prefix is optional; when included,
the added results have the same names as used by weakiv10
but with prefix added.

eststorewald(name)
stores the IV model estimated by
ivregress, ivreg2, ivreg2h, ivprobit or ivtobit
under name.

estusewald(name)}
obtains the IV model from a stored previous estimation by
ivregress, ivreg2, ivreg2h, ivprobit or ivtobit.

displaywald
displays the model estimated by IV for Wald tests prior to reporting weakiv10 results.

Estimation and testing examples

Setup

. clear

. use http://www.stata.com/data/jwooldridge/eacsap/mroz.dta

. gen byte poshours=(hours>0)

Following estimation by ivregress: test significance of educ in the lwage equation (homoskedastic VCE).
Graph Wald, AR and CLR tests.

. ivregress 2sls lwage exper expersq (educ = fatheduc motheduc)

. weakiv10, graph(wald ar clr)

Use as a standalone estimation command (robust VCE, LM versions of tests).
Graph AR, K, J and KJ tests.

. weakiv10 ivregress 2sls lwage exper expersq (educ = fatheduc motheduc), robust lm graph(ar k j kj)

Limited dependent variable estimation (standalone IV tobit and following estimation by ivprobit.

. weakiv10 ivtobit hours nwifeinc exper expersq age kidslt6 kidsge6 (educ = fatheduc motheduc), ll

. ivprobit poshours nwifeinc exper expersq age kidslt6 kidsge6 (educ = fatheduc motheduc), twostep

. weakiv10

Two endogenous regressors. Only tests of null hypotheses reported; no grid used.

. weakiv10 ivreg2 lwage (educ exper = fatheduc motheduc kidslt6 kidsge6), robust null1(0.1) null2(0.05)

Two endogenous regressors, both assumed weakly identified. Graph Wald and K tests; robust VCE.

. weakiv10 ivreg2 lwage exper expersq (educ hours = fatheduc motheduc kidslt6 kidsge6), rob graph(wald k)

Two endogenous regressors. Same as above except one assumed strongly identified.

. weakiv10 ivreg2 lwage exper expersq (educ hours = fatheduc motheduc kidslt6 kidsge6), rob strong(educ) graph(wald k)

Time-series setup

. clear

. use http://fmwww.bc.edu/ec-p/data/wooldridge/phillips.dta

. tsset year, yearly

Following estimation by ivreg2. Test null that coefficient on unem=-0.5; use weight of 0.75 on K in K-J test;
request small-sample adjustment.

. ivreg2 cinf (unem = l(1/3).unem), robust bw(3)

. weakiv10, null(-0.5) kwt(0.75) small

Panel data setup

. clear

. webuse abdata

First-differences estimation using xtivreg; fixed effects estimation using xtivreg2 and cluster-robust SEs.

. weakiv10 xtivreg ys k (n=l2.n l3.n), fd

. weakiv10 xtivreg2 ys k (n=l2.n l3.n), fe cluster(id)

Confidence interval and grid examples

As a standalone estimator using ivreg2. Estimate the confidence sets over a grid of 500 points.
Use a wider grid (width=3x the Wald confidence interval, centered around the IV point estimate)
to remove the open-ended confidence intervals for K test.

. weakiv10 ivreg2 cinf (unem = l(1/3).unem), robust bw(3) points(500) gridmult(3)

As above, but instead specify the lower and upper limits of the grid.

. weakiv10 ivreg2 cinf (unem = l(1/3).unem), robust bw(3) points(500) gridlimits(-2 1)

Two different uses of kjlevel(.) option.
(1) Specify an overall K-J test level of exactly 90%, equal weights on K in K-J,
and hence test levels for K in K-J of appx. 95% each.
(2) Specify test levels of exactly 95% for K in K-J,
and hence equal weights and an overall K-J test level of appx. 90%.
In both cases also specify a test level of 90% for the AR test.

. use http://www.stata.com/data/jwooldridge/eacsap/mroz.dta

. weakiv10 ivregress 2sls lwage exper expersq (educ = fatheduc motheduc), robust kjlevel(90) kwt(0.5) arlevel(90)

. di _col(5) %5.2f e(kj_level) _col(15) %5.2f e(kjk_level) _col(25) %5.2f e(kjj_level)

. weakiv10 ivregress 2sls lwage exper expersq (educ = fatheduc motheduc), robust kjlevel(95 95) arlevel(90)

. di _col(5) %5.2f e(kj_level) _col(15) %5.2f e(kjk_level) _col(25) %5.2f e(kjj_level)

Graphing examples

Setup

. clear

. use http://www.stata.com/data/jwooldridge/eacsap/mroz.dta

As a standalone estimation command. Graph the rejection probabilities of all 6 tests (robust VCE),
then use replay syntax to tweak graph options without having to reestimate.
Confidence intervals correspond to x-axis range where rejection probabilities are below 95% line.

. weakiv10 ivregress 2sls lwage exper expersq (educ = fatheduc motheduc), robust graph(all)

. weakiv10, graph(ar clr wald) graphxrange(-0.05 0.15) graphopt(title("AR, CLR, Wald"))

Time-series setup

. clear

. use http://fmwww.bc.edu/ec-p/data/wooldridge/phillips.dta

. tsset year, yearly

As a standalone estimation command. Illustrates empty confidence interval, K spurious loss of power,
J test misspecification and relation to AR and K-J tests.

. weakiv10 ivreg2 cinf (unem = l(1/3).unem), robust bw(3) graph(ar k) graphopt(title("AR - empty, K - spurious power loss"))

. weakiv10 ivreg2 cinf (unem = l(1/2).unem), robust bw(3) graph(ar k j kj) points(800) gridlimits(-1 1) graphopt(title("J suggests misspecification"))

Two endogenous regressors.

. clear

. use http://www.stata.com/data/jwooldridge/eacsap/mroz.dta

. weakiv10 ivreg2 lwage (educ exper = fatheduc motheduc kidslt6 kidsge6), graph(wald ar)

Two endogenous regressors; estimate using robust VCE, grid of 25x25=625 points

. weakiv10 ivreg2 lwage (educ exper = fatheduc motheduc kidslt6 kidsge6), robust points(25) graph(k)

Refine appearance of surface graph using replay syntax; note that with replay the levels in the graph do not have to correspond to tests reported in table

. weakiv10, graph(k) surfaceopt(xlabel(0 0.1 0.2) ylabel(-0.02 0.06)) level(95 90)

As above but shaded contour graph instead of contour line graph and 3 confidence levels (95%, 90%, 80%).

. weakiv10, graph(k) surfaceopt(xlabel(0 0.1 0.2) ylabel(-0.02 0.06)) level(95 90 80) contouropt(contourshade)

estadd and other miscellaneous examples

With estimation by ivregress. Illustrates behavior of estadd.

. ivregress 2sls cinf (unem = l(1/3).unem), vce(hac bartlett 2)

. weakiv10, estadd

. ereturn list

. weakiv10 ivregress 2sls cinf (unem = l(1/3).unem), vce(hac bartlett 2) estadd(myprefix_)

. ereturn list

As a standalone estimation command. Illustrates behavior of displaywald.

. weakiv10 ivreg2 cinf (unem = l(1/3).unem), rob bw(3) display

Saved results

weakiv10 saves the following in e():

Scalars

e(null) null hypothesis

e(null1) null hypothesis for 1st endogenous regressor (2 endog case only)

e(null2) null hypothesis for 2nd endogenous regressor (2 endog case only)

e(clr_p) CLR test p-value

e(clr_stat) CLR test statistic

e(ar_p) AR test p-value

e(ar_chi2) AR test statistic

e(k_p) K test p-value

e(k_chi2) K test statistic

e(j_p) J test p-value

e(j_chi2) J test statistic

e(kj_r) K-J test p-value

e(kwt) weight on K in K-J test

e(rk) rk statistic

e(wald_p) Wald test p-value

e(wald_chi2) Wald test statistic

e(points) number of points in grid used to estimate confidence sets

e(points1) number of points in 1st (x) axis of grid (2 endog case only)

e(points1) number of points in 2nd (y) axis of grid (2 endog case only)

e(overid) degree of overidentification

e(small) =1 if small-sample adjustments used, =0 otherwise

e(alpha) default significance level for tests

e(N) sample size

e(N_clust) number of clusters (if cluster-robust VCE used)

e(ar_level) level in percent used for AR confidence interval

e(k_level) level in percent used for K confidence interval

e(j_level) level in percent used for J confidence interval

e(kj_level) level in percent for K-J confidence interval

e(kjk_level) level in percent for K test in K-J confidence interval

e(kjk_level) level in percent for J test in K-J confidence interval

e(clr_level) level in percent used for CLR confidence interval

e(wald_level) level in percent used for Wald confidence interval

Macros

e(clr_cset) confidence set based on CLR test

e(ar_cset) confidence set based on AR test

e(k_cset) confidence set based on K test

e(kj_cset) confidence set based on K-J test

e(inexog) list of exogenous regressors

e(exexog) list of excluded instruments

e(endo) endogenous variable(s)

e(wald_cset) confidence set based on Wald test

e(grid) range of grid used to estimate confidence sets

e(model) linear, ivprobit or ivtobit

e(level) default confidence level in percent used for tests of null = 100*(1-alpha)

e(levellist) confidence level(s) plotted in graphs

Matrices

e(citable) table with test statistics, p-values, and rejection
indicators for every grid point over which hypotheses were tested

Acknowledgements

weakiv10 builds on and extends the command rivest by Finlay and Magnusson (2009).
The main differences and extensions are:
(a) extension to the 2-endogenous-regressor case;
(b) graphics options that allow the plotting of confidence intervals and rejection probabilities (1-endog-regressor),
and confidence regions and rejection surfaces (2-endog-regressors);
(c) support for a wider range of variance-covariance estimators in linear IV estimation;
including HAC (heteroskedastic-and autocorrelation-robust) and two-way clustering VCEs;
(d) support for LM versions of the tests;
(e) specification of models directly in the command line as well as obtaining specification from
a previously-estimated or stored model (weakiv10 is an eclass command);
(f) minor changes in terminology and syntax.

The code in weakiv10 for the closed-form solutions for confidence intervals
in the i.i.d. case (homosekdasticity and independence)
derives from condivreg by Mikusheva and Poi.

References

Anderson, T. W. and Rubin, H. 1949.
Estimation of the Parameters of Single Equation in a Complete
System of Stochastic Equations.
Annals of Mathematical Statistics 20:46–63.

Baum, C.F. and Schaffer, M.E. 2013.
AVAR: module to perform asymptotic covariance estimation for iid and
non-iid data robust to heteroskedasticity, autocorrelation, 1- and 2-way
clustering, and common cross-panel autocorrelated disturbances.
http://ideas.repec.org/c/boc/bocode/s457689.html.

Chernozhukov, V. and Hansen, C. 2005.
The Reduced Form:
A Simple Approach to Inference with Weak Instruments.
Working paper, University of Chicago, Graduate School of Business.
http://dx.doi.org/10.2139/ssrn.937943.

Chernozhukov, V. and Hansen, C. 2008.
The Reduced Form:
A Simple Approach to Inference with Weak Instruments.
Economics Letters 100(1):68-71.

Finlay, K. and Magnusson, L.M. 2009.
Implementing weak-instrument robust tests for
a general class of instrumental-variables models.
Stata Journal 9(3):398-421.
http://www.stata-journal.com/article.html?article=st0171.

Jann, B. 2009.
ESTOUT: Stata module to make regression tables.
http://ideas.repec.org/c/boc/bocode/s439301.html.

Kleibergen, F. 2002.
Pivotal Statistics for Testing Structural Parameters in Instrumental Variables Regression.
Econometrica, 70:1781-1803.

Kleibergen, F. 2004.
Testing Subsets of Structural Parameters in the Instrumental Variables Regression Model.
Review of Economics and Statistics, 86:418-423.

Kleibergen, F. 2005.
Testing Parameters in GMM Without Assuming that They Are Identified.
Econometrica, 73:1103-1123.

Mander, A. 2005.
SURFACE: Stata module to draw a 3D wireform surface plot.
http://ideas.repec.org/c/boc/bocode/s448501.html.

Magnusson, L.M. 2010.
Inference in limited dependent variable models robust to weak identification.
Econometrics Journal, 13:S56-S79.

Mikusheva, A. 2003.
Survey on statistical inferences in weakly-identified instrumental variables models.
Applied Econometrics, 29:117-131.
http://econpapers.repec.org/article/risapltrx/0206.htm.

Moreira, M. 2003.
A Conditional Likelihood Ratio Test for Structural Models.
Econometrica, 71:1027-1048.

Mikusheva, A. and Poi, B. 2006.
Tests and confidence sets with correct size when instruments are potentially weak.
Stata Journal 6(3):335-347.
http://www.stata-journal.com/article.html?article=st0033_2.

Citation of weakiv10

weakiv10 is not an official Stata command. It is a free contribution
to the research community, like a paper. Please cite it as such:

Finlay, K., Magnusson, L.M., Schaffer, M.E. 2013.
weakiv10: Weak-instrument-robust tests and confidence intervals
for instrumental-variable (IV) estimation of linear, probit and tobit models.
http://ideas.repec.org/c/boc/bocode/xxxxx.html

Authors

Keith Finlay, Tulane University, USA
kfinlay@gmail.com

Leandro Magnusson, University of Western Australia
leandro.magnusson@uwa.edu.au

Mark E Schaffer, Heriot-Watt University, UK
m.e.schaffer@hw.ac.uk

Also see

Article: Stata Journal, volume 11, number 2: st0171_1,

Stata Journal, volume 9, number 3: st0171

Manual: [R] ivregress,

[R] ivprobit,

[R] ivtobit,

[R] xtivreg,

[R] test

Help: condivreg, ivreg2, ivreg2h, xtivreg2