Diagnostics tests
diagnostics.Rd
Auxiliary function (i.e. not intended for the average user) called by the arx
, getsm
, getsv
, isat
, getsFun
and blocksFun
functions. The diagnostics
function undertakes tests for autocorrelation, ARCH and non-normality in a residual series, and user-defined diagnostics provided via the user.fun
argument (see details). The autocorrelation and ARCH tests are conducted as Ljung and Box (1979) tests for autocorrelation in the residuals and squared residuals, respectively, whereas the test for non-normality is that of Jarque and Bera (1980).
Arguments
- x
a
list
, for example the estimation result ofols
. The tests for serial correlation, ARCH and normality look for an entry in the list namedstd.residuals
orresiduals
- ar.LjungB
a two element vector or
NULL
. In the former case, the first element contains the AR-order, the second element the significance level. IfNULL
, then a test for autocorrelation is not conducted- arch.LjungB
a two element vector or
NULL
. In the former case, the first element contains the ARCH-order, the second element the significance level. IfNULL
, then a test for ARCH is not conducted- normality.JarqueB
NULL
(the default) or a value between 0 and 1. In the latter case, a test for non-normality is conducted using a significance level equal tonormality.JarqueB
. IfNULL
, then no test for non-normality is conducted- verbose
logical. If
TRUE
, then adata.frame
with the results of the diagnostics is returned. IfFALSE
, then the return-value is alogical
that indicates whether the model passes the diagnostics (TRUE
if it does, otherwiseFALSE
)- user.fun
NULL
or alist
with at least one entry,name
(must be of classcharacter
), which should contain the name of the user-defined function. See details- ...
further arguments (ignored) to accommodate deleted arguments from past versions of the functions
Details
The argument user.fun
enables the user to specify additional diagnostics. To do this, the argument should be a list
with at least one entry, name
(of class character
), that contains the name of the user-defined function. The call to this function is executed with do.call
, whose default value on envir
is parent.frame()
. Usually, this will be the global environment (.GlobalEnv
), but it can be changed by adding an entry named envir
to the list that indicates where the user-defined function resides. If the verbose
argument is set to FALSE
, then an entry named pval
must be provided. This entry should contain the chosen significance level or levels, i.e. either a scalar or a vector of length equal to the number of p-values returned by the user-defined diagnostics function (see examples). The user can also specify whether a rejection of the tests should cause the diagnostics to fail (default behaviour) or whether a rejection is desirable. For that purpose, a named entry is.reject.bad
can be added that stores a logical vector of length equal to the number of tests conducted in the user diagnostics function. The first entry of the vector governs the diagnostic decision for the first row that the user diagnostics function returns, the second entry the decision for the second row etc. Additional entries in the list
are passed on as arguments to the user-defined function.
The user-defined function should refer to the named items of the estimation result x
(see examples), and the value returned by the user-defined function should be a matrix of dimension m x 3. Here, m is the number of diagnostic tests performed by the user-defined function. For example, if only a single test is performed, then m = 1 and so the returned value should be a 1 x 3 matrix (or a vector of length 3). The three columns of the m x 3 matrix should contain, in the following order, 1) the value(s) of the test-statistic(s) (or NA
), 2) the degree(s) of freedom(s) (or NA
) of the tests, and 3) the p-value(s) of the test(s). When checking whether the model passes the diagnostics or not, the p-value(s) is(are) checked against the value(s) in the entry named pval
in the list
provided to user.fun
. By default, a calculated p-value below the corresponding element in pval
causes the diagnostics to fail. If a named entry is.reject.bad
exists, this decision rule is only applied to tests whose corresponding entry is TRUE
while the decision rule is reversed for those with entry FALSE
. For these tests, the diagnostics fail if the hypothesis cannot be rejected.
Value
- verbose=TRUE
a
data.frame
that contains the diagnostics results- verbose=FALSE
a
logical
(of length one) indicating whether the residuals and/or model passes ALL the diagnostics (TRUE
if it does,FALSE
otherwise)
References
C. Jarque and A. Bera (1980): 'Efficient Tests for Normality, Homoscedasticity and Serial Independence'. Economics Letters 6, pp. 255-259
G. Ljung and G. Box (1979): 'On a Measure of Lack of Fit in Time Series Models'. Biometrika 66, pp. 265-270
Author
Genaro Sucarrat, http://www.sucarrat.net/
Jonas Kurle, https://www.jonaskurle.com/
Examples
##generate some data:
set.seed(123)
vY <- rnorm(20) #the regressand
mX <- matrix(rnorm(3*20), 20, 3) #the regressors
est <- ols(vY,mX)
##return a data-frame with autocorrelation and ARCH diagnostics (default),
##and check whether they pass (the default p-value is 0.025):
diagnostics(est)
#> Chi-sq df p-value
#> Ljung-Box AR(1) 0.003510917 1 0.95275060
#> Ljung-Box ARCH(1) 3.412392622 1 0.06470856
diagnostics(est, verbose=FALSE)
#> [1] TRUE
##add the Jarque-Bera normality test to the diagnostics (w/p-value=0.05):
diagnostics(est, normality.JarqueB=0.05)
#> Chi-sq df p-value
#> Ljung-Box AR(1) 0.003510917 1 0.95275060
#> Ljung-Box ARCH(1) 3.412392622 1 0.06470856
#> Jarque-Bera 0.353445573 2 0.83801206
diagnostics(est, normality.JarqueB=0.05, verbose=FALSE)
#> [1] TRUE
##user-defined Shapiro-Wilks test for non-normality of the residuals:
SWtest <- function(x, ...){
tmp <- shapiro.test(x$residuals)
return( c(tmp$statistic, NA, tmp$p.value) )
}
diagnostics(est, user.fun=list(name="SWtest", pval=0.05))
#> Error in SWtest(x = list(n = 20L, k = 3L, df = 17L, qr = structure(c(3.62487403917307, 0.0601331004340281, 0.283045545091906, 0.201080429668508, 0.172430617200659, 0.465310874947587, -0.231121698420629, -0.0423112958351247, 0.313979720319216, -0.345891997217083, -0.11764939053554, 0.0814018583276303, -0.246939797458238, -0.242252138431096, -0.226650932627968, -0.189976326531111, -0.152810179761157, 0.0170796860546485, 0.0844064263843262, 0.104961164691719, 0.377135609304277, 4.18306927046561, 0.246481761888288, -0.558307619735788, -0.322902857194065, 0.176391268783772, 0.142058567357394, 0.11993269430476, -0.248602857415755, 0.0883916806405081, -0.0372719911907566, -0.00928731556492584, 0.0591247587530225, -0.279228199896485, 0.0988330348762853, -0.324924264454731, 0.400488511923555, -0.143137669256186, -0.0463148198853255, -0.0723974652165301, 1.00869972564444, -0.779701632797945, 4.08092759871367, 0.185233890940201, 0.218726987192663, -0.117012636548216, -0.0720265999983978, 0.000732010244829912, -0.281377313521943, -0.454773113442127, 0.131633750893663, 0.555479233370269, -0.212765088722502, 0.18241513524346, 0.202733446261662, -0.252210034688066, 0.116969103898599, 0.286731683955082, -0.0578301919878286, 0.0162954407447317), dim = c(20L, 3L)), rank = 3L, qraux = c(1.29458229291478, 1.03780248045971, 1.06579109048657), pivot = 1:3, coefficients = c(-0.142573185558897, -0.0782492112997779, 0.117145620304408), xtxinv = structure(c(0.0820440800165264, -0.00927737771326456, -0.0178734769745561, -0.00927737771326456, 0.059235331340333, 0.0111922037450993, -0.0178734769745561, 0.0111922037450993, 0.0600457426091443), dim = c(3L, 3L)), fit = c(0.251076403262785, -0.0114982515325492, 0.206263203434632, -0.185120394226588, -0.130963882193103, 0.363916650190558, -0.0354147346027191, 0.0208577323998841, 0.209275747972232, 0.0679216184743613, -0.138146487047055, -0.226205977935575, -0.0064484741874254, -0.31537010122381, -0.180066226592616, -0.0967030692174864, 0.00885497047022835, -0.17992034864234, 0.0551694833330762, 0.0210771903782191), residuals = c(-0.811552049814997, -0.218679237950731, 1.35244511071449, 0.255628785651164, 0.26025161735405, 1.35114833669272, 0.496330940591921, -1.28591896700642, -0.896128599865758, -0.513583588574319, 1.36222828448652, 0.586019804992939, 0.407219924781478, 0.426052817168929, -0.375774908161459, 1.88361620602056, 0.488995507759011, -1.7866968079873, 0.646186418230609, -0.493868598106153), residuals2 = c(0.658616729558924, 0.0478206091107123, 1.82910777749553, 0.0653460760534889, 0.0677309043353987, 1.82560182774751, 0.246344402588861, 1.65358758970685, 0.803046467497365, 0.263768102452876, 1.85566589905508, 0.343419211843963, 0.165828067139032, 0.181521003017581, 0.141206781603753, 3.54801001158331, 0.239116606608493, 3.192285483672, 0.417556887105704, 0.243906192195337), rss = 17.7894866303718, sigma2 = 1.04644039002187, vcov = structure(c(0.0858542390914793, -0.00970822275264876, -0.0187035282163014, -0.00970822275264876, 0.0619862432308527, 0.0117119740522259, -0.0187035282163014, 0.0117119740522259, 0.0628342903150657), dim = c(3L, 3L)), logl = -27.3327136641223)): could not find function "SWtest"
diagnostics(est, user.fun=list(name="SWtest", pval=0.05), verbose=FALSE)
#> Error in SWtest(x = list(n = 20L, k = 3L, df = 17L, qr = structure(c(3.62487403917307, 0.0601331004340281, 0.283045545091906, 0.201080429668508, 0.172430617200659, 0.465310874947587, -0.231121698420629, -0.0423112958351247, 0.313979720319216, -0.345891997217083, -0.11764939053554, 0.0814018583276303, -0.246939797458238, -0.242252138431096, -0.226650932627968, -0.189976326531111, -0.152810179761157, 0.0170796860546485, 0.0844064263843262, 0.104961164691719, 0.377135609304277, 4.18306927046561, 0.246481761888288, -0.558307619735788, -0.322902857194065, 0.176391268783772, 0.142058567357394, 0.11993269430476, -0.248602857415755, 0.0883916806405081, -0.0372719911907566, -0.00928731556492584, 0.0591247587530225, -0.279228199896485, 0.0988330348762853, -0.324924264454731, 0.400488511923555, -0.143137669256186, -0.0463148198853255, -0.0723974652165301, 1.00869972564444, -0.779701632797945, 4.08092759871367, 0.185233890940201, 0.218726987192663, -0.117012636548216, -0.0720265999983978, 0.000732010244829912, -0.281377313521943, -0.454773113442127, 0.131633750893663, 0.555479233370269, -0.212765088722502, 0.18241513524346, 0.202733446261662, -0.252210034688066, 0.116969103898599, 0.286731683955082, -0.0578301919878286, 0.0162954407447317), dim = c(20L, 3L)), rank = 3L, qraux = c(1.29458229291478, 1.03780248045971, 1.06579109048657), pivot = 1:3, coefficients = c(-0.142573185558897, -0.0782492112997779, 0.117145620304408), xtxinv = structure(c(0.0820440800165264, -0.00927737771326456, -0.0178734769745561, -0.00927737771326456, 0.059235331340333, 0.0111922037450993, -0.0178734769745561, 0.0111922037450993, 0.0600457426091443), dim = c(3L, 3L)), fit = c(0.251076403262785, -0.0114982515325492, 0.206263203434632, -0.185120394226588, -0.130963882193103, 0.363916650190558, -0.0354147346027191, 0.0208577323998841, 0.209275747972232, 0.0679216184743613, -0.138146487047055, -0.226205977935575, -0.0064484741874254, -0.31537010122381, -0.180066226592616, -0.0967030692174864, 0.00885497047022835, -0.17992034864234, 0.0551694833330762, 0.0210771903782191), residuals = c(-0.811552049814997, -0.218679237950731, 1.35244511071449, 0.255628785651164, 0.26025161735405, 1.35114833669272, 0.496330940591921, -1.28591896700642, -0.896128599865758, -0.513583588574319, 1.36222828448652, 0.586019804992939, 0.407219924781478, 0.426052817168929, -0.375774908161459, 1.88361620602056, 0.488995507759011, -1.7866968079873, 0.646186418230609, -0.493868598106153), residuals2 = c(0.658616729558924, 0.0478206091107123, 1.82910777749553, 0.0653460760534889, 0.0677309043353987, 1.82560182774751, 0.246344402588861, 1.65358758970685, 0.803046467497365, 0.263768102452876, 1.85566589905508, 0.343419211843963, 0.165828067139032, 0.181521003017581, 0.141206781603753, 3.54801001158331, 0.239116606608493, 3.192285483672, 0.417556887105704, 0.243906192195337), rss = 17.7894866303718, sigma2 = 1.04644039002187, vcov = structure(c(0.0858542390914793, -0.00970822275264876, -0.0187035282163014, -0.00970822275264876, 0.0619862432308527, 0.0117119740522259, -0.0187035282163014, 0.0117119740522259, 0.0628342903150657), dim = c(3L, 3L)), logl = -27.3327136641223)): could not find function "SWtest"
##user-defined test but diagnostics fail if do not reject (illustration only)
diagnostics(est, user.fun=list(name="SWtest", pval=0.05, is.reject.bad = FALSE))
#> Error in SWtest(x = list(n = 20L, k = 3L, df = 17L, qr = structure(c(3.62487403917307, 0.0601331004340281, 0.283045545091906, 0.201080429668508, 0.172430617200659, 0.465310874947587, -0.231121698420629, -0.0423112958351247, 0.313979720319216, -0.345891997217083, -0.11764939053554, 0.0814018583276303, -0.246939797458238, -0.242252138431096, -0.226650932627968, -0.189976326531111, -0.152810179761157, 0.0170796860546485, 0.0844064263843262, 0.104961164691719, 0.377135609304277, 4.18306927046561, 0.246481761888288, -0.558307619735788, -0.322902857194065, 0.176391268783772, 0.142058567357394, 0.11993269430476, -0.248602857415755, 0.0883916806405081, -0.0372719911907566, -0.00928731556492584, 0.0591247587530225, -0.279228199896485, 0.0988330348762853, -0.324924264454731, 0.400488511923555, -0.143137669256186, -0.0463148198853255, -0.0723974652165301, 1.00869972564444, -0.779701632797945, 4.08092759871367, 0.185233890940201, 0.218726987192663, -0.117012636548216, -0.0720265999983978, 0.000732010244829912, -0.281377313521943, -0.454773113442127, 0.131633750893663, 0.555479233370269, -0.212765088722502, 0.18241513524346, 0.202733446261662, -0.252210034688066, 0.116969103898599, 0.286731683955082, -0.0578301919878286, 0.0162954407447317), dim = c(20L, 3L)), rank = 3L, qraux = c(1.29458229291478, 1.03780248045971, 1.06579109048657), pivot = 1:3, coefficients = c(-0.142573185558897, -0.0782492112997779, 0.117145620304408), xtxinv = structure(c(0.0820440800165264, -0.00927737771326456, -0.0178734769745561, -0.00927737771326456, 0.059235331340333, 0.0111922037450993, -0.0178734769745561, 0.0111922037450993, 0.0600457426091443), dim = c(3L, 3L)), fit = c(0.251076403262785, -0.0114982515325492, 0.206263203434632, -0.185120394226588, -0.130963882193103, 0.363916650190558, -0.0354147346027191, 0.0208577323998841, 0.209275747972232, 0.0679216184743613, -0.138146487047055, -0.226205977935575, -0.0064484741874254, -0.31537010122381, -0.180066226592616, -0.0967030692174864, 0.00885497047022835, -0.17992034864234, 0.0551694833330762, 0.0210771903782191), residuals = c(-0.811552049814997, -0.218679237950731, 1.35244511071449, 0.255628785651164, 0.26025161735405, 1.35114833669272, 0.496330940591921, -1.28591896700642, -0.896128599865758, -0.513583588574319, 1.36222828448652, 0.586019804992939, 0.407219924781478, 0.426052817168929, -0.375774908161459, 1.88361620602056, 0.488995507759011, -1.7866968079873, 0.646186418230609, -0.493868598106153), residuals2 = c(0.658616729558924, 0.0478206091107123, 1.82910777749553, 0.0653460760534889, 0.0677309043353987, 1.82560182774751, 0.246344402588861, 1.65358758970685, 0.803046467497365, 0.263768102452876, 1.85566589905508, 0.343419211843963, 0.165828067139032, 0.181521003017581, 0.141206781603753, 3.54801001158331, 0.239116606608493, 3.192285483672, 0.417556887105704, 0.243906192195337), rss = 17.7894866303718, sigma2 = 1.04644039002187, vcov = structure(c(0.0858542390914793, -0.00970822275264876, -0.0187035282163014, -0.00970822275264876, 0.0619862432308527, 0.0117119740522259, -0.0187035282163014, 0.0117119740522259, 0.0628342903150657), dim = c(3L, 3L)), logl = -27.3327136641223)): could not find function "SWtest"
diagnostics(est, user.fun=list(name="SWtest", pval=0.05, is.reject.bad = FALSE),
verbose=FALSE)
#> Error in SWtest(x = list(n = 20L, k = 3L, df = 17L, qr = structure(c(3.62487403917307, 0.0601331004340281, 0.283045545091906, 0.201080429668508, 0.172430617200659, 0.465310874947587, -0.231121698420629, -0.0423112958351247, 0.313979720319216, -0.345891997217083, -0.11764939053554, 0.0814018583276303, -0.246939797458238, -0.242252138431096, -0.226650932627968, -0.189976326531111, -0.152810179761157, 0.0170796860546485, 0.0844064263843262, 0.104961164691719, 0.377135609304277, 4.18306927046561, 0.246481761888288, -0.558307619735788, -0.322902857194065, 0.176391268783772, 0.142058567357394, 0.11993269430476, -0.248602857415755, 0.0883916806405081, -0.0372719911907566, -0.00928731556492584, 0.0591247587530225, -0.279228199896485, 0.0988330348762853, -0.324924264454731, 0.400488511923555, -0.143137669256186, -0.0463148198853255, -0.0723974652165301, 1.00869972564444, -0.779701632797945, 4.08092759871367, 0.185233890940201, 0.218726987192663, -0.117012636548216, -0.0720265999983978, 0.000732010244829912, -0.281377313521943, -0.454773113442127, 0.131633750893663, 0.555479233370269, -0.212765088722502, 0.18241513524346, 0.202733446261662, -0.252210034688066, 0.116969103898599, 0.286731683955082, -0.0578301919878286, 0.0162954407447317), dim = c(20L, 3L)), rank = 3L, qraux = c(1.29458229291478, 1.03780248045971, 1.06579109048657), pivot = 1:3, coefficients = c(-0.142573185558897, -0.0782492112997779, 0.117145620304408), xtxinv = structure(c(0.0820440800165264, -0.00927737771326456, -0.0178734769745561, -0.00927737771326456, 0.059235331340333, 0.0111922037450993, -0.0178734769745561, 0.0111922037450993, 0.0600457426091443), dim = c(3L, 3L)), fit = c(0.251076403262785, -0.0114982515325492, 0.206263203434632, -0.185120394226588, -0.130963882193103, 0.363916650190558, -0.0354147346027191, 0.0208577323998841, 0.209275747972232, 0.0679216184743613, -0.138146487047055, -0.226205977935575, -0.0064484741874254, -0.31537010122381, -0.180066226592616, -0.0967030692174864, 0.00885497047022835, -0.17992034864234, 0.0551694833330762, 0.0210771903782191), residuals = c(-0.811552049814997, -0.218679237950731, 1.35244511071449, 0.255628785651164, 0.26025161735405, 1.35114833669272, 0.496330940591921, -1.28591896700642, -0.896128599865758, -0.513583588574319, 1.36222828448652, 0.586019804992939, 0.407219924781478, 0.426052817168929, -0.375774908161459, 1.88361620602056, 0.488995507759011, -1.7866968079873, 0.646186418230609, -0.493868598106153), residuals2 = c(0.658616729558924, 0.0478206091107123, 1.82910777749553, 0.0653460760534889, 0.0677309043353987, 1.82560182774751, 0.246344402588861, 1.65358758970685, 0.803046467497365, 0.263768102452876, 1.85566589905508, 0.343419211843963, 0.165828067139032, 0.181521003017581, 0.141206781603753, 3.54801001158331, 0.239116606608493, 3.192285483672, 0.417556887105704, 0.243906192195337), rss = 17.7894866303718, sigma2 = 1.04644039002187, vcov = structure(c(0.0858542390914793, -0.00970822275264876, -0.0187035282163014, -0.00970822275264876, 0.0619862432308527, 0.0117119740522259, -0.0187035282163014, 0.0117119740522259, 0.0628342903150657), dim = c(3L, 3L)), logl = -27.3327136641223)): could not find function "SWtest"