*! version 0.0.2 29sep2025

help for gweakivtest

A robust test for weak instruments for 2SLS with multiple endogenous regressors

Syntax

gweakivtest [, criterion(crit) target(targetname) retain(varname) alpha(#) tau(#) points(#) verbosity(#)]

criterion(crit) bias criterion to use, either rel or abs; default is abs

target(targetname) target to use, either beta (entire parameter vector) or the coefficient corresponding to one of the endogenous variables; default is beta

retain(varname) which endogenous variable to retain for Sanderson-Windmeijer (reduced rank) setting; omit for Stock-Yogo setting (default)

alpha(#) significance level; default is alpha(0.05)

tau(#) bias tolerance; default is tau(0.1)

points(#) number of starting points for the optimization step; default is points(1000)

verbosity(#) level of run information displayed onscreen during execution; default is verbosity(0)

noplugin requests that the secondary Mata-only implementation of the command is used

procs(#) number of processors to run plugin code across; default is number of processors on machine

Description

gweakivtest implements the robust weak instruments test of Lewis
and Mertens (2025). It is a postestimation command for ivreg2 and
ivregress.

gweakivtest tests the null hypothesis of weak instruments for
two-stage least squares (2SLS) models with multiple endogenous regressors,
generalizing existing bias-based tests for instrument strength in 2SLS models.
Specifically, it (1) generalizes the bias-based tests for weak instrument of
Stock and Yogo (2005) (developed under uniformly weak instruments) and Sanderson
and Windmeijer (2016) (developed under a rank-deficient first-stage) to be
robust to heteroskedasticity, autocorrelation and clustering (indeed, any form
of covariance matrix), and (2) extends the Montiel Olea and Pflueger (2013)
robust test for models with a single endogenous regressor (as implemented in
weakivtest) to multiple endogenous regressors. Like that of Montiel Olea
and Pflueger (2013), the test is based on a Nagar (1959) approximation of the
bias of the 2SLS estimator.

The test rejects the null hypothesis when the generalized test
statistic exceeds a critical value, which depends on the asymptotic covariance
matrix of reduced-form and first-stage OLS coefficients, the desired
significance level, alpha, and the desired bias tolerance threshold, tau.
In models with a single endogenous regressor, the test-statistic and critical
values are equivalent to Montiel Olea and Pflueger (2013), except in models
with one or two instruments. With one instrument, the critical values are based
on the median bias, since the mean bias does not exist. With two instruments,
the Nagar approximation of the bias relied upon by both tests is potentially
poor, suggesting a more conservative bound on the bias is preferable.

Relative to all three papers, the test gives the option of testing for
bias in a single coefficient, instead of the whole parameter vector. This can be
controlled via the optional argument target().

Note that the test is not appropriate (and therefore gweakivtest
does not work) for estimation methods other than 2SLS. Note also that the test
only extends the bias-based test of Stock and Yogo (2005), not their size-based
test.

Weighted 2SLS is supported, with the same weights used throughout the
test as were specified in the original 2SLS regression. Small sample (degrees
of freedom) adjustments are made consistently with the original 2SLS regression,
i.e. if that regression included the small option.

This implementation of the Lewis and Mertens (2025) test is a port
of the original Matlab code written by the paper authors. The Stock and Yogo
(2005) test for instrument strength is available in ivreg2 and in the
ivregress postestimation command estat firststage. The Montiel-Olea
and Pflueger (2013) test for instrument strength is implemented in
weakivtest.

Note: You must install avar by typing "ssc install avar" before running gweakivtest.

Options

criterion(crit) specifies the bias criterion to use, either abs (absolute) or rel
(relative); the default is abs.

target(targetname) specifies the target for the bias criterion, either beta (meaning the full vector of coefficients on all endogenous variables) or the name of a single endogenous variable; the
default is beta.

retain(varname) specifies which endogenous variable to retain for
Sanderson-Windmeijer setting; omit for Stock-Yogo setting (default).

alpha(#) specifies the significance level for the test, expressed as a
decimal; the default is alpha(0.05).

tau(#) specifies bias tolerance threshold, expressed
as a decimal; the default is tau(0.1).

points(#) specifies the number of starting points for the optimization
step in computing the critical values; the default is points(1000).

verbosity(#) sets the level of runtime information displayed on screen
during execution. A value of 0 means no information; 1 means high-level
progress information is displayed; 2 adds information about progress of
top-level iterations; 3 displays line-by-line information about top-level
iterations; 4 reports detailed low-level information (for debugging). The
default is verbosity(0).

noplugin requests that the Mata-only implementation of the command is used
and not the default compiled plugin; see technical details below.

procs(#) specifies the number of processors to run plugin code across;
the default is number of processors on the machine. Ignored if option
noplugin specified.

Technical details

There are two main parts to the code underlying the gweakivtest
command: calculating the test statistic, and calculating the critical value.
The former is not too computationally burdensome and is therefore implemented
in Stata's matrix language, Mata. The latter, however, is much more
computationally intensive and efficiency can be increased significantly using
sparse matrices (which Mata doesn't have), so the primary implementation is as
a plugin written in C++.

Plugins are compiled code, so are platform-specific. We have provided
versions for Windows, Linux and Mac (Apple and Intel silicon). The Windows
version has been tested relatively extensively, while the versions for Linux and
Mac less so. Plugins can be somewhat fragile and have a tendency to bring Stata
down with relatively little provocation. Apologies in advance if this happens to
you, and please let us know!

To guard against problems with the plugin, we have included a secondary
implementation of the critical value calculation entirely in Mata. This can be
selected using the noplugin option. For relatively small problems, it
tends to run quickly and terminate with moderately helpful error messages rather
than bringing Stata down. But it cannot handle even medium-sized cases due to
memory requirements without sparse matrices, and will likely cause Stata to
seize up. So you know whether this is likely to happen, the command issues a
warning if the memory requirement is likely to be excessive and reports an
estimated execution time.

The Mata-native implementation also has a second limitation. A key
part of the algorithm involves solving a constrained optimization problem. Mata
doesn't include routines for constrained optimization, so constraints have had
to be imposed via a transformation of variables. This seems to work reasonably
well but, in testing, we did find a number of instances where convergence is not
achieved or the solution deviates slightly from the one found by the plugin.
Convergence issues are flagged in the returned values but, for this reason, we
prefer to rely on the results from the plugin.

Examples

Setup

. webuse mroz

Run 2SLS using ivregress

. ivregress 2sls lwage city (exper educ = age kidslt6 kidsge6 motheduc fatheduc) if inlf == 1, vce(robust)

Perform Lewis-Mertens weak IV test

. gweakivtest

Stored results

gweakivtest stores the following in r():

Scalars

r(alpha) specified significance level alpha

r(tau) specified relative bias threshold

r(gmin) Stock-Yogo (or Sanderson-Windmeijer) test statistic

r(gmin_generalized) Lewis-Mertens test statistic

r(sybb_cv) Stock-Yogo (or Sanderson-Windmeijer) bias-based critical value

r(sybbn_cv) Stock-Yogo (or Sanderson-Windmeijer) bias-based critical value under Nagar approximation

r(lmc_cv) Lewis-Mertens conservative critical value

r(lmc_converged) Calculation of Lewis-Mertens conservative critical value successfully converged

r(lms_cv) Lewis-Mertens sharp critical value

r(lms_converged) Calculation of Lewis-Mertens sharp critical value successfully converged

Matrices

r(W) Covariance matrix of first-stage and reduced form coefficients

r(Sig) Covariance matrix of first-stage and reduced form residuals

References

Lewis, D. J., and K. Mertens, 2025. "A robust test for weak instruments with multiple endogenous regressors." Review of Economic Studies, forthcoming

Montiel Olea, J. L. and C. E. Pflueger, 2013. "A robust test for weak instruments." Journal of Business and Economic Statistics, 31, 358-369.

Sanderson, E. and F. Windmeijer, (2016). "A weak instrument F-test in linear IV models with multiple endogenous variables." Journal of Econometrics, 190(2), 212–221.

Stock, J. and M. Yogo, 2005. "Testing for weak instruments in linear IV regression." In Identification and Inference for Econometric Models: Essays in Honor of Thomas Rothenberg, Chapter 5, 80-108.

Authors

Daniel J. Lewis, University College London, London WC1H 0AX, United Kingdom
(daniel.lewis920@gmail.com)

Karel Mertens, Federal Reserve Bank of Dallas and CEPR, Dallas TX 75201, USA
(mertens.karel@gmail.com)

Jonathan Shaw, Institute for Fiscal Studies, London NW1 4DF, United Kingdom
(jon@jonshaw.net)

Also see

ivregress, ivregress_postestimation,
ivreg2 (if installed), avar (if installed),
weakivtest (if installed)