Skip to content

R package · heteroscedasticity diagnostics

Is the error variance of your model constant?

heteroTests gathers the tests of that question for linear models in R: the classical auxiliary-regression tests, tests on ordered observations, group-wise tests of equal variance, resampling and scalable variants, with plots and remedies, behind one calling convention and one result type.

Get started Browse the reference

One convention

Every test takes (model, data, ...) and returns a base-R htest object, which prints, subsets and composes like the result of lmtest::bptest(). What every test returns lists its fields.

Checked against references

Where an established implementation exists, the test reproduces it and the test suite asserts the agreement: lmtest, car, stats, vartest and plm. Simulated size and power are in inst/validation/.

From diagnosis to remedy

runHeteroTests() runs a battery of tests by name, fitWLS() fits weighted least squares with a choice of variance function, and performVarianceFormTest() asks whether that function had the right shape.

What it looks like

library(heteroTests)

model <- lm(stations ~ mag + depth, data = quakes)
performKoenkerTest(model, quakes)
#>
#>         Koenker studentized Breusch-Pagan test
#>
#> data:  stations ~ mag + depth
#> X-squared = 111.31, df = 2, p-value < 2.2e-16

# Several tests at once, chosen by name; listDiagnostics() returns the names.
runHeteroTests(model, quakes, tests = c("white", "koenker"))

# A remedy, and a test of the variance function it assumed.
wls <- fitWLS(model)
performVarianceFormTest(wls)

What it provides

  • Does the variance depend on the regressors? White (performWhiteTest()), the classical Breusch–Pagan test (performBPTest()) and Koenker's studentized form of it (performKoenkerTest()), Harvey (performHarveyTest()), Park (performParkTest()), Glejser (performGlejserTest()) and the Cook–Weisberg score test (performCookWeisbergTest()).
  • Does the variance change with the fitted values or along an ordering? Goldfeld–Quandt (performGQTest()), Szroeter (performSzroeterTest()), Harrison–McCabe (performHarrisonMcCabeTest()), Spearman's rank correlation, the spread–level test and Davidian–Carroll.
  • Do groups have equal variances? Levene, Brown–Forsythe, Bartlett, Fligner–Killeen, Hartley's F-max and O'Brien on the residuals of a model, and Box's M for equal covariance matrices (performBoxMTest()).
  • Does the variance of a time series depend on its past? Engle's ARCH LM test (performArchLMTest()) and McLeod–Li (performMcLeodLiTest()).
  • When the asymptotic reference distribution is in doubt: a null-imposed wild bootstrap (performWildBootstrapTest()), a bootstrap White test, a rank-permutation test and a quantile-regression test.
  • Panel and spatial data: performSpatialHeteroTest() asks whether the squared residuals cluster in space, and runPanelTests() runs the Breusch–Pagan test for a random effect and Pesaran's test of cross-sectional dependence.
  • Scalability: streaming implementations of the White, Breusch–Pagan and Koenker tests accumulate the auxiliary cross-products in chunks; the results are exact and memory-bounded, and runHeteroTests() adopts them automatically for large inputs.
  • The shape of the variance: performVarianceFormTest() tests whether an exponential or a power variance function describes the heteroscedasticity, where the other tests only establish that the variance is not constant.
  • Model checks that are not tests of the variance: Ramsey's RESET, variance inflation factors, influential observations and the correlations of the absolute residuals with chosen variables, listed apart in the reference.
  • Remediation and guidance: weighted least squares (fitWLS()), robust fits (fitRobust()), variance-stabilising transforms (autoTransform()) and a recommendation engine (generateHeteroRecommendations()).
  • Ecosystem integration: broom tidiers, ggplot2 theming and autoplot(), and helpers for tidymodels and grouped pipelines.

Installation

Install the released version from CRAN, or the development version from GitHub:

install.packages("heteroTests")

# install.packages("remotes")
remotes::install_github("DiogoRibeiro7/heteroTests")

heteroTests needs R 4.1 or later. Getting started walks through a first analysis, and the user guide holds the long-form articles.

Citation and licence

If you use heteroTests in research, cite the CRAN release, doi:10.32614/CRAN.package.heteroTests, as citation("heteroTests") does. Releases are also archived on Zenodo. heteroTests is released under the Apache License 2.0.