Print and summarise the results of runHeteroTests()¶

Source: R/suite_summary.R · Help: ?summary.hetero_test_suite

print() shows a hetero_test_suite compactly: the model and the number of observations, on one line when it fits the console, then one row per test with its statistic, degrees of freedom, p-value and significance codes, and a note for each test that did not run as asked. summary() returns an object of class summary.hetero_test_suite, which prints as the summary of an lm does (summary.lm()): the call, the number of observations, the table of tests, the legend of the significance codes and the notes; and coef() of it returns the table, as coef(summary(fit)) does for an lm.

The hetero_grouped_suite of a grouped run has the same methods, with one table for all the groups, a row for each test in each group.

Usage¶

## S3 method for class 'hetero_test_suite'
print(
  x,
  digits = max(3L, getOption("digits") - 3L),
  signif.stars = getOption("show.signif.stars"),
  ...
)

## S3 method for class 'hetero_test_suite'
summary(object, ...)

## S3 method for class 'summary.hetero_test_suite'
print(
  x,
  digits = max(3L, getOption("digits") - 3L),
  signif.stars = getOption("show.signif.stars"),
  ...
)

## S3 method for class 'hetero_grouped_suite'
print(
  x,
  digits = max(3L, getOption("digits") - 3L),
  signif.stars = getOption("show.signif.stars"),
  ...
)

## S3 method for class 'hetero_grouped_suite'
summary(object, ...)

## S3 method for class 'summary.hetero_grouped_suite'
print(
  x,
  digits = max(3L, getOption("digits") - 3L),
  signif.stars = getOption("show.signif.stars"),
  ...
)

## S3 method for class 'summary.hetero_test_suite'
coef(object, ...)

## S3 method for class 'summary.hetero_grouped_suite'
coef(object, ...)

Arguments¶

x: A hetero_test_suite or hetero_grouped_suite, as runHeteroTests() returns, or its summary.
digits: The number of significant digits to print, as in print.summary.lm().
signif.stars: Logical: show the significance codes?
...: Passed on to printCoefmat() by the print methods, replacing the arguments they pass (Details); unused by the summary and coef() methods.
object: A hetero_test_suite or hetero_grouped_suite for summary(), or its summary for coef().

Value¶

The print methods return x, invisibly. coef() of a summary returns its tests.

summary() of a hetero_test_suite returns a list of class summary.hetero_test_suite with:

call: The call of the model, as summary.lm() keeps it, or NULL when its call is not recorded or the model was fitted by runHeteroTests() itself, whose call names the runner's variables rather than yours (stats::lm(formula = model, data = prep$data)): the fit of a formula, the refit of a model within each group, and the fit to the data of a survey design (runSurveyHeteroTests()). The runner records those in the suite, as attr(, "model_origin") ("formula", "group" or "survey"; see hetero_test_suite); a model you fitted is shown by its call, whatever its form.
formula: The formula of the model, or NULL.
model_class: The class of the model, such as "lm".
nobs: The number of observations, stats::nobs() of the model.
na.action: The na.action of the model, as summary.lm() keeps it: the observations dropped for missing values, or NULL.
weights: How the model is weighted, as text: the weights argument of its call ("1/hp"); the variance function of a fitWLS() fit; or, for prior weights its call does not record, their range; NULL for an unweighted model.
offset: The offset of the model, as text, or NULL.
family: The family and link of a glm, as text, or NULL.
tests: A numeric matrix with one row per test, named as the suite is, and the columns Statistic, df, df2 (only when a test has second degrees of freedom) and p-value, as coef(summary(fit)) holds those of the coefficients of an lm; coef(summary(s)) returns it. A failed test has NA in every column.
method: A character vector, named as the suite is: the method of each result, the name of the test that ran.
diagnostic: A character vector: the registry name of the test that ran, attr(, "diagnostic"), which differs from the name asked for when a fallback ran in its place.
status: A character vector: "ok"; "fallback" when another test ran in its place; "error" when it failed; or "other" for a result that is not an htest.
notes: A character vector of the notes, as summary() prints them.

summary() of a hetero_grouped_suite returns a list of class summary.hetero_grouped_suite with:

formula, model_class: As above, for the model of the first group.
keys: The grouping keys, one row per group, attr(, "group_keys") of the suite.
nobs: An integer vector: the number of observations of each group.
tests: A data frame with one row per test in each group: the grouping keys, test (the name asked for), Statistic, df, df2 (only when a test has second degrees of freedom), p-value and status, as above; coef(summary(g)) returns it.
groups: A list with the summary.hetero_test_suite of each group.
notes: A character vector of the notes of every group, each starting with the label of its group.

Details¶

The table is printed by printCoefmat(), so its format is that of summary.lm(): digits sets the significant digits, the p-values are formatted by format.pval(), and the significance codes and their legend are shown when signif.stars is TRUE (by default getOption("show.signif.stars")) and a p-value is below 0.1. The print methods pass printCoefmat() cs.ind = integer(), tst.ind = 1, zap.ind = integer(), P.values = TRUE, has.Pvalue = TRUE and na.print = "NA"; an argument of the same name given in ... replaces the value passed, so that print(s, na.print = "-") prints a failed test with dashes and print(s, P.values = FALSE) leaves the p-values out.

The rows are named as the suite is, by the names asked for in tests. The df column holds the degrees of freedom of the statistic: the parameter of the test named df, df1 or num df (as var.test() and anova() name it), or the first one when they have no names. The second degrees of freedom of an F statistic, named df2 or denom df, are a column of their own, df2, when a test has them. A parameter of another name, such as the number of replicates B of a resampling test or the number of observations n of Szroeter's test, is not a degree of freedom, and the notes give it.

The notes say which test did not run as asked: one whose fallback ran under its name, saying which test ran in its place and why; one that was refused or failed, with its message and, for a failure of a particular kind, that kind (attr(, "extras")$issue, such as "rank_deficiency"); one computed by a streaming implementation; a parameter that is not a degree of freedom; and a result that is not a test, as a diagnostic added with registerDiagnostic() may return. A test "refused" its input when it stopped before computing anything, with one of the refusals of the package: of the model or of data by the model context (the issues "model_context" and "data_rows"), of a glm that is not a least-squares fit or a model of another class, of a survey::svyglm() fit, of zero weights, of a weighted fit by a test that refits without its weights, of an aliased coefficient, or of too few observations. These are recognised by their messages, since the runner records the message and the issue and not the class of the condition; a test that stopped otherwise "failed". print() gives each note on one line, cut to the width of the console; summary() gives it whole. Without groups, runHeteroTests() stops when a test fails and no fallback runs, so a failed test is returned only by a grouped run, which records the failure and goes on. Whether a result was read from a cache is not shown: a result read from it is identical() to the one computed (see cachedTest()).

Several tests of one model are not independent evidence: they are computed from the same residuals, most of them from regressions of their squares on overlapping sets of regressors. A small p-value from one and a large one from another describe the alternatives each test is built to detect; they are not two votes, and summary() says so.

Neither method changes the results: generics::tidy(), generics::glance(), generics::augment() and ggplot2::autoplot() read them as before.

Earlier versions¶

Up to 0.15.0 a suite had no print or summary method: print() showed the list, each test and then the attributes of the suite, the fitted model among them, and summary() gave the summary of a list.

Examples¶

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
s <- runHeteroTests(m, mtcars, tests = c("white", "koenker", "cook_weisberg"))
s
summary(s)
coef(summary(s))
print(summary(s), signif.stars = FALSE)

# White's test needs 20 observations: the runner falls back on the
# Breusch-Pagan test, and the note says so.
small <- mtcars[1:18, ]
runHeteroTests(lm(mpg ~ wt, data = small), small)

if (requireNamespace("dplyr", quietly = TRUE)) {
  by_am <- dplyr::group_by(mtcars, am)
  g <- runHeteroTests(mpg ~ wt, by_am, tests = "koenker")
  print(g)
  print(summary(g)$tests)
}