*! version 1.1 19dec2020
help lmtest

Title

lmtest -- Lagrange-multiplier test after constrained maximum-likelihood estimation

Syntax

lmtest [,options]

options

notest suppress output

nocnsreport suppress display of constraints

noomitted do not consider omitted variables as constraints

df(#) override the automatic degrees-of-freedom calculation

forcevce perform test even if vcetype is not oim or opg

Description

lmtest performs a Lagrange-multiplier (LM) test (Silvey, 1959), also referred to as score test,
of the restrictions that were previously imposed on the most recently estimated model by specifying the option constraints().
lmtest complements test and lrtest that implement the Wald test and the likelihood-ratio test, respectively,
which - together with the Lagrange-multiplier test - represent the three canonical approaches to testing hypotheses after maximum-likelihood (ML) estimation (cf. Greene, 2012, p. 564).
lmtest requires that the preceding estimation command allows the option constraints() and the maximize_options iterate() and from(),
and also requires that the constraints are saved in e(Cns) and the score vector is saved in e(gradient).
Unlike test, the syntax of lmtest does not involve specifying the restrictions to be tested.
The restrictions are rather specified by the option constraints() in the command syntax used for estimating the model.
This corresponds to the logic of the Lagrange-multiplier test to estimate only the restricted version of a model.
The LM-test statistic reads simply as score*inv(Info)*score', with the estimated score vector (score) and the estimated inverse information matrix (inv(Info)) being evaluated at the restricted maximum.
lmtest calculates the estimated score vector and the coefficient variance-covariance matrix, which serves as estimator for inv(Info),
at the restricted maximum by making use of the maximize_options iterate(0) and from(e(b)).
For determining the number of degrees-of-freedom, lmtest considers all restrictions that are specified in e(Cns), except for base-level coefficients being restricted to the value of zero.
indepvars that are automatically omitted due to collinearity may hence distort the result of the LM test.
Specifying the option df(#) allows manually providing the appropriate number of degrees-of-freedom.
Alternatively, one may specify the option noomitted to prevent lmtest from interpreting omitted variables as exclusion restrictions to be tested; see example 3.

Options

notest prevents lmtest from displaying any output on the screen.

nocnsreport prevents lmtest from displaying the imposed constraints.

df(#) makes lmtest use an user-specified number of degrees-of-freedoms in calculating the p-value for the LM test.
The default is to use the rank of e(Cns), adjusted for the number of base-levels, as degrees-of-freedom.
Specifying df(#) may be advisable if variables omitted due to collinearity inflate the rank of e(Cns) and in turn inflate the number of degrees-of-freedom.

noomitted makes lmtest not to consider omitted varaibles as exclusion restrictions to be tested.
Since some estimation commands, mlogit for instance (see example 1), label exclusion restictions specified by constraints() as omitted variables in e(Cns),
the default is to consider omitted variables as exclusion restrictions that are to be tested.
Unlike omitted variables, base-levels are never considered as testable exclusion restrictions, irrespective of whether or not noomitted is specified.

forcevce makes lmtest carry out the LM test even if vcetype is neither oim nor opg.
Since lmtest estimates the inverse information matrix as e(V), vcetypes other than oim and opg are most likely inappropriate.
With forcevce lmtest estimates the inverse information matrix as e(V_modelbased) and issues a warning.
If vcetype is oim or opg, specifying forcevce has no effect.

Example 1

(see mlogit examples)

Load data

. webuse sysdsn1

Define constraints

. constraint 1 [Uninsure]

. constraint 2 [Prepaid]: 2.site 3.site

Estimate constrained multinomial logistic regression model

. mlogit insure age male nonwhite i.site, constraint(1/2)

LM test of the constraints

. lmtest

Example 2

(see oprobit examples)

Load data

. webuse fullauto

Define constraints (equal distance between cutoff values)

. constraint 1 - [/]cut1 + 2*[/]cut2 - [/]cut3 = 0

. constraint 2 - [/]cut2 + 2*[/]cut3 - [/]cut4 = 0

Estimate constrained ordered probit estimation

. oprobit rep77 foreign length mpg, constraints(1 2)

LM test of the constraints

. lmtest

Example 3

(see streg examples, adjustment to automatically omitted variables)

Load data

. webuse catheter

Generate collinear regressor

. gen male = 1 - female

stset data

. stset time, fail(infect)

Define constraint

. constraint 1 female = male + 2

Estimate constrained survival model

. streg age female male, distribution(lognormal) frailty(invgauss) shared(patient) constraints(1)

LM test with manually adjusted degrees-of-freedom

. lmtest, df(1)

LM test with omitted varaibles not being considered as exclusion restrictions

. lmtest, noomitted

Saved results

lmtest saves the following in r():

Scalars

r(p) p-value

r(chi2) test statistic (chi-squared)

r(df) test constraints degrees of freedom

r(rank) rank of e(Cns) adjusted for the number of base-levels (only saved if df(#) is specified)

Macros

r(modelbased) modelbased if e(V_modelbased) used as estimate of the inverse information matrix

References

Silvey, S. D. (1959). The Lagrangian Multiplier Test. Annals of Mathematical Statistics 30, 389-407.

Greene, W. H. (2012). Econometric Analysis, Pearson, 7th ed.

Also see

Manual: [R] test, [R] lrtest, [SEM] estat scoretests, [R] constraint, [R] Maximize

Help: [R] test, [R] lrtest, [SEM] estat scoretests, [R] constraint, [R] Maximize

Author

Harald Tauchmann

Friedrich-Alexander-Universität Erlangen-Nürnberg (FAU)

Nürnberg,
Germany

E-mail: harald.tauchmann@fau.de

Disclaimer

This software is provided "as is" without warranty of any kind, either expressed or implied. The entire risk as to the quality and
performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or
correction. In no event will the copyright holders or their employers, or any other party who may modify and/or redistribute this software,
be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to
use the program.

Acknowledgements

I would like to thank Michael Oberfichtner for many valuable comments and suggestions.