Package 'heteroTests'

Description

Maintains a registry of diagnostic functions that can be called by runHeteroTests() and runDiagnostics(). Users can register custom diagnostics via registerDiagnostic().

Usage

.diagnostic_registry

Format

An object of class environment of length 16.

Description

These functions extend the package with more specialized tests for heteroscedasticity such as a studentized Breusch-Pagan test, a bootstrap version of White's test and the Szroeter ordered test.

Description

Fits a GAM using mgcv and compares its residuals to the input linear model.

Usage

analyzeMLResiduals(model, data = NULL)

Arguments

Value

A list with the GAM model, residuals and RMSE reduction.

See Also

compareModelDiagnostics

Examples

data(mtcars)
 analyzeMLResiduals(mpg ~ wt + qsec, mtcars)

Description

Fits several remedial models for heteroscedasticity and compares their performance using AIC and residual RMSE. Currently evaluates weighted least squares and robust regression against the original model.

Usage

autoCompareRemediations(model, data = NULL)

Arguments

Value

A list with components metrics, models, and best indicating the recommended method.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, mtcars)
autoCompareRemediations(m)

Description

Generates a bar chart of diagnostic p-values, highlighting tests below the conventional 5% threshold.

Usage

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

Arguments

Value

A ggplot object.

Description

Chooses between no transformation, log, square root and Box–Cox based on the Breusch-Pagan test statistic.

Usage

autoTransform(model)

Arguments

Value

A list with elements model (the transformed fit) and method indicating the chosen transformation.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
autoTransform(m)

Description

These helpers provide reusable bootstrap and power-estimation routines for the heteroscedasticity testing framework. They support the robust implementations introduced in robust_implementations.R but are written generically so additional tests can reuse them.

Description

Avoids recomputing expensive diagnostics by hashing their inputs and reusing stored results.

Usage

cachedTest(test_name, model, data, ..., use_cache = TRUE)

Arguments

Details

The cache key is created by hashing the test name, model coefficients, residuals, data, and additional arguments. When the key already exists in the cache environment the stored result is returned immediately; otherwise the diagnostic is executed and its output stored for future calls. Set use_cache = FALSE to force recomputation when the underlying model has changed.

Value

The diagnostic result, either retrieved from cache or freshly computed.

See Also

clearTestCache() resets the cache between analysis sessions.

Description

Ensures that data is a data.frame. Used internally for input validation across the package.

Usage

checkData(data)

Arguments

Value

Invisible data if valid, otherwise an error is thrown.

Description

Checks that model is of class lm or glm.

Usage

checkModel(model)

Arguments

Value

Invisible model if valid, otherwise an error is thrown.

Description

Extends checkModel() with additional soft checks that flag potential numerical issues before computationally expensive diagnostics are executed. The helper mirrors the warnings used throughout the package and retains the original return semantics for backward compatibility.

Usage

checkModelEnhanced(model, data = NULL)

Arguments

Details

The function warns when residual degrees of freedom fall below six, when a near-perfect fit is detected (R$^2 > 0.999$), or when variance inflation factors (VIFs) exceed 10. The latter threshold follows the regression diagnostics literature (Belsley et al., 1980).

Value

Invisibly returns model after issuing any relevant warnings.

References

Belsley, D. A., Kuh, E., & Welsch, R. E. (1980). Regression Diagnostics: Identifying Influential Data and Sources of Collinearity. Wiley.

See Also

checkModel(), performVIFDiagnostic(), validateTestInputs()

Examples

data(mtcars)
fit <- stats::lm(mpg ~ wt + hp, data = mtcars)
checkModelEnhanced(fit)

Description

Removes memoised outputs stored by runHeteroTests when called with use_cache = TRUE. Useful for deterministic test runs or after mutating the underlying data/model so cached summaries should be invalidated.

Usage

clearAnalysisCache()

See Also

runHeteroTests, clearTestCache

Description

Removes all objects from the internal cache environment so that subsequent diagnostic calls recompute their statistics.

Usage

clearTestCache()

See Also

cachedTest() for invoking diagnostics with memoisation.

Description

Runs runDiagnostics for multiple models and collects test statistics. Diagnostics that cannot be computed (for example, due to validation failures) emit warnings and fill the corresponding entries with NA_real_. The original error messages are preserved on the returned data frame via the diagnostic_errors attribute.

Usage

compareModelDiagnostics(models, data = NULL, tests = c("white", "breusch_pagan"))

Arguments

Value

A data frame of statistics, one row per model. Failed diagnostics are represented by NA_real_ entries and the underlying error messages can be retrieved from the diagnostic_errors attribute.

See Also

analyzeMLResiduals

Examples

data(mtcars)
 m1 <- lm(mpg ~ wt + qsec, mtcars)
 m2 <- lm(mpg ~ wt + hp, mtcars)
 compareModelDiagnostics(list(m1, m2))

Description

Runs selected diagnostics for a single model and returns a tidy data frame of test statistics and p-values.

Usage

compareTestResults(model, data = NULL, tests = c("white", "breusch_pagan"))

Arguments

Value

Data frame with columns test, statistic, and p.value.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, mtcars)
compareTestResults(m)

Description

This dataset contains two predictors with correlation and a response including a quadratic term. It is useful for testing diagnostics beyond heteroscedasticity.

Usage

data(diagnostic_data)

Format

A data frame with 150 rows and 3 variables:

x1

first predictor

x2

second predictor, correlated with x1

y

response

Source

Simulated via set.seed(123).

Examples

data(diagnostic_data)
head(diagnostic_data)

Description

Provides convenient access to example datasets hosted online. Currently supports the 'tips' dataset used in various tutorials.

Usage

downloadTeachingData(
  name = "tips",
  destfile = tempfile(fileext = ".csv"),
  quiet = FALSE
)

Arguments

Value

Path to the downloaded dataset on success, or NULL invisibly if the download fails or no internet connection is available.

Examples

# Online example (requires internet)
if (curl::has_internet()) {
  data_path <- downloadTeachingData(quiet = TRUE)
  if (!is.null(data_path)) {
    # Use downloaded data
  }
}


# Offline example using built-in data
data(mtcars)
model <- lm(mpg ~ wt + hp, data = mtcars)
result <- performWhiteTest(model, mtcars)
print(result)

Description

Provides a simple interface to MASS::rlm for robust estimation.

Usage

fitRobust(model, data = NULL, ...)

Arguments

Value

An object of class rlm.

Examples

data(mtcars)
m <- fitRobust(mpg ~ wt + qsec, mtcars)
summary(m)

Description

Refit a model by feasible generalised least squares, weighting each observation by the inverse of an estimated error variance.

Usage

fitWLS(model)

Arguments

Details

The variance is modelled, not read off the residuals directly. A single squared residual is a one-degree-of-freedom estimate of $\sigma_i^2$ and far too noisy to invert: weighting by $1/e_i^2$ hands almost all of the weight to whichever observations the initial fit happened to reproduce most closely. This function instead regresses $\log e_i^2$ on the model's own design matrix and takes $\hat\sigma_i^2 = \exp(\hat g_i)$ from the fitted values, the standard feasible-GLS recipe; weights are $1/\hat\sigma_i^2$.

The log scale keeps the fitted variances positive without constraining the auxiliary regression, and residuals that are numerically zero are floored before the logarithm, with a warning.

Weights estimated this way are consistent under a correctly specified variance model, so standard errors from the returned fit are usable. They were not before 0.9.0, when the weights were the raw inverse squared residuals: the weighted residual sum of squares then collapsed towards $n$ regardless of the data, and nominal 95% intervals covered the truth about 10% of the time.

If the variance model cannot be fitted, or yields no usable variation, the function falls back to equal weights, which reduces the result to the original OLS fit.

Value

A new lm object fitted with weights. The estimated variances are attached as the "variance_model" attribute.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
wls <- fitWLS(m)
summary(wls)

Description

Creates a standalone report summarizing heteroscedasticity tests and diagnostic plots for a fitted model.

Usage

generateDiagnosticReport(
  model,
  data = NULL,
  output_format = "html",
  output_file = NULL,
  include_remediation = TRUE,
  include_theory = FALSE
)

Arguments

Value

Invisibly returns the path to the generated report.

Examples

if (requireNamespace("rmarkdown", quietly = TRUE) &&
    rmarkdown::pandoc_available()) {
  model <- lm(mpg ~ wt + hp, data = mtcars)
  generateDiagnosticReport(
    model, mtcars,
    output_file = file.path(tempdir(), "diagnostic_report.html")
  )
}

Description

These helpers assemble an end-to-end recommendation workflow that profiles the input dataset, selects appropriate heteroscedasticity diagnostics, interprets results with qualitative confidence labels, and suggests remediation strategies with decision-tree style guidance.

Usage

analyseDatasetCharacteristics(data, response = NULL)

suggestDiagnosticsForProfile(profile)

interpretHeteroTestResults(test_results, alpha = 0.05)

recommendRemediationStrategies(test_results, model, data, profile = NULL)

warnDiagnosticAssumptions(profile, interpretations, model, data, test_results)

buildDiagnosticDecisionTree(profile, recommendations)

composeDiagnosticNarrative(profile, interpretations, remediation,
  assumption_warnings, decision_tree)

generateHeteroRecommendations(model, data = NULL, test_results = NULL,
  alpha = 0.05, include_report = TRUE)

Arguments

Details

The recommendation engine analyses dataset characteristics such as sample size, missingness, and predictor skewness to propose diagnostics tailored to the context. It automatically interprets test outcomes, attaches qualitative confidence labels, warns when assumptions are at risk, and suggests remediation strategies matched to detected variance patterns. The generated decision tree and narrative target non-specialist audiences who need actionable guidance.

Value

analyseDatasetCharacteristics() returns a list describing dataset size, missingness, skewness, and risk factors. suggestDiagnosticsForProfile() returns a data frame of recommended diagnostics with rationales. interpretHeteroTestResults() yields a tidy data frame of interpretations and an overall summary. recommendRemediationStrategies() produces a structured remediation plan. warnDiagnosticAssumptions() returns warnings about assumption violations. buildDiagnosticDecisionTree() constructs a tidy decision tree. composeDiagnosticNarrative() outputs a plain-language character vector, and generateHeteroRecommendations() returns an object of class hetero_recommendation_report bundling all components.

See Also

runHeteroTests(), suggestRemediation(), generateDiagnosticReport()

Examples

model <- lm(mpg ~ wt + hp, data = mtcars)
recs <- generateHeteroRecommendations(model, mtcars)
print(recs)

Description

This dataset is generated from the model $y_i = 1 + 2 x_i + \varepsilon_i$, where $\varepsilon_i \sim N(0, (0.5 + 2 x_i)^2)$. A fixed seed ensures repeatable values.

Usage

data(hetero_data)

Format

A data frame with 100 rows and 2 variables:

x

predictor

y

response

Source

Simulated with set.seed(42); runif() and rnorm().

Examples

data(hetero_data)
plot(hetero_data$x, hetero_data$y)

Description

Collections of heteroscedasticity test results returned by runHeteroTests. A hetero_test_suite is a simple named list of htest objects with additional metadata. When diagnostics are evaluated on grouped data, the returned object inherits from hetero_grouped_suite and contains one hetero_test_suite per group along with the grouping keys.

Details

These classes are primarily useful for method dispatch (e.g. the broom tidiers and autoplot() methods). Users typically interact with the objects via generics::tidy(), generics::glance(), generics::augment() and ggplot2::autoplot().

Description

Create a diagnostic object that exposes test(), plot() and summary() methods. Formulas are accepted for convenience.

Usage

HeteroDiagnostic(model, data = NULL)

Arguments

Value

An object of class HeteroDiagnostic.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 d <- HeteroDiagnostic(m, mtcars)
 test(d)

Description

These helpers manage the package-level logging subsystem used to debug complex diagnostic workflows. Users can adjust verbosity, enable log capture, inspect recent log entries and clear the stored history when finished.

Usage

ht_set_log_level(level = c("INFO", "WARN", "ERROR", "SILENT"))

ht_enable_log_capture(enabled = TRUE, max_entries = 1000L, sink = NULL)

ht_log_history()

ht_clear_log_history()

Arguments

Value

ht_set_log_level() returns the previous log level invisibly. ht_enable_log_capture() and ht_clear_log_history() return NULL. ht_log_history() returns a data frame with columns timestamp, level and message.

Description

Launch a production-ready Shiny dashboard for running heteroscedasticity diagnostics, exploring interactive plots, and experimenting with simulation studies.

Usage

launchDiagnosticDashboard(model, data)

Arguments

Details

Requires optional packages shiny, DT, and plotly. Excel uploads additionally depend on readxl and exporting interactive graphics relies on htmlwidgets. The dashboard guides users through data preparation, model fitting, diagnostic testing, interactive Plotly visualisations, and a real-time simulation lab for exploring heteroscedastic data-generating processes. Download buttons are provided for both results tables and interactive plots.

Value

A shiny.appobj that can be run with shiny::runApp().

Examples

if (interactive() && requireNamespace("shiny", quietly = TRUE) &&
    requireNamespace("DT", quietly = TRUE) &&
    requireNamespace("plotly", quietly = TRUE)) {
  mod <- lm(mpg ~ wt + hp, data = mtcars)
  launchDiagnosticDashboard(mod, mtcars)
}

Description

Collection of advanced heteroscedasticity tests including wild bootstrap, heteroscedasticity-consistent covariance LM statistics, quantile regression comparisons, rank-based permutation checks, high-dimensional projections and spatial correlation diagnostics.

Usage

modern_diagnostics

Format

An object of class NULL of length 0.

Description

Regresses squared residuals on their lags to detect ARCH effects.

Usage

performArchLMTest(model, lags = 1)

Arguments

Details

The statistic is $n R^2$ from an auxiliary regression of $e_t^2$ on its lagged values, where $R^2$ is the coefficient of determination. Under the null of no ARCH effects it follows a chi-square distribution with degrees of freedom equal to the number of lags.

Value

An object of class htest containing the test statistic, p-value and degrees of freedom.

References

Engle, R. F. (1982). Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation. Econometrica, 50(4), 987–1007. doi:10.2307/1912773

Hamilton, J. D. (1994). Time Series Analysis. Princeton University Press.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performArchLMTest(m, lags = 2)

Description

Uses bartlett.test on model residuals grouped by a factor.

Usage

performBartlettTest(model, data, group)

Arguments

Details

The test statistic compares the pooled variance to the individual group variances. It is computed as $\chi^2 = (N - k) \ln S_p^2 - \sum (n_i - 1) \ln s_i^2$, where $S_p^2$ is the pooled variance and $s_i^2$ the group variances. Under the null it approximates a chi-square distribution with $k-1$ degrees of freedom.

Value

An object of class htest containing the chi-squared statistic, p-value and degrees of freedom.

References

Bartlett, M. S. (1937). Properties of sufficiency and statistical tests. Proceedings of the Royal Society of London, 160(901), 268–282. doi:10.1098/rspa.1937.0109

Hartley, H. O. (1950). The maximum F-ratio as a short-cut test for heterogeneity of variance. Biometrika, 37(3/4), 308–312. doi:10.2307/2332383

Examples

data(mtcars)
 mtcars$cyl <- factor(mtcars$cyl)
 m <- lm(mpg ~ wt, data = mtcars)
 performBartlettTest(m, mtcars, "cyl")

Description

Test whether multiple groups have equal covariance matrices.

Usage

performBoxMTest(data, group)

Arguments

Value

An object of class htest.

Examples

data(iris)
performBoxMTest(iris[,1:4], iris$Species)

Description

Lagrange Multiplier test for the presence of a random individual effect in panel data. This is not a test for heteroscedasticity and does not respond to one; use the auxiliary-regression diagnostics for that.

Usage

performBPRandomEffectsTest(model, data, id)

Arguments

Details

The statistic is Breusch and Pagan (1980) equation 5, $LM = nT / (2(T-1)) [ \sum_i (\sum_t e_{it})^2 / \sum_{it} e_{it}^2 - 1 ]^2$, which follows a chi-square distribution with one degree of freedom under the null of no individual effect. The bracketed ratio is close to one under the null and the statistic measures its squared departure from one. Before 0.11.0 the "- 1" and the square were absent and the scaling used T^2 rather than nT, which left the statistic sitting at the critical value: it rejected about a third of the time when no individual effect was present.

Value

An object of class htest.

References

Breusch, T. S., & Pagan, A. R. (1980). The Lagrange Multiplier Test and Its Applications to Model Specification in Econometrics. Review of Economic Studies, 47(1), 239–253.

Examples

df <- data.frame(id = rep(1:5, each = 4), time = rep(1:4, 5), x = runif(20), y = rnorm(20))
 m <- lm(y ~ x, data = df)
 performBPRandomEffectsTest(m, df, "id")

Description

Implements the classical Breusch-Pagan (1979) test on a fitted linear model, in which the scaled squared residuals are regressed on the original regressors.

Usage

performBPTest(model, data)
performBreuschPaganTest(model, data)

Arguments

Details

The test statistic is half the explained sum of squares from regressing the scaled squared residuals $e_i^2/\hat{\sigma}^2 - 1$ (with $\hat{\sigma}^2 = \sum e_i^2 / n$) on the explanatory variables. Under the null hypothesis of homoscedasticity and normal disturbances it follows a chi-square distribution with degrees of freedom equal to the number of regressors, matching lmtest::bptest(..., studentize = FALSE). For the studentized $n R^2$ form that drops the normality assumption use performKoenkerTest or performStudentizedBPTest.

Value

An object of class htest containing the test statistic, p-value and degrees of freedom.

References

Breusch, T. S., & Pagan, A. R. (1979). A simple test for heteroscedasticity and random coefficient variation. Econometrica, 47(5), 1287–1294. doi:10.2307/1911963

Koenker, R. (1981). A note on studentizing a test for heteroscedasticity. Journal of Econometrics, 17(1), 107–112. doi:10.1016/0304-4076(81)90062-2

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performBPTest(m, mtcars)

Description

Enhances performBPTest() by optionally studentising residuals, resampling the test statistic via bootstrap, and reporting effect sizes together with power diagnostics.

Usage

performBPTestRobust(
  model,
  data,
  studentized = TRUE,
  bootstrap = FALSE,
  B = 1000,
  ci_level = 0.95,
  parallel = FALSE
)

Arguments

Details

Offers expanded reporting for the Breusch–Pagan family of tests including bootstrap p-values and asymptotic confidence intervals. The optional studentized argument toggles between the classic and Koenker versions.

Value

An augmented htest object containing a robust_details element describing the additional diagnostics.

References

Breusch, T. S., & Pagan, A. R. (1979). A simple test for heteroscedasticity and random coefficient variation. Econometrica, 47(5), 1287–1294.

Koenker, R. (1981). A note on studentizing a test for heteroscedasticity. Journal of Econometrics, 17(1), 107–112.

See Also

performBPTest() for the baseline test and performStudentizedBPTest() for the standalone studentised variant.

Examples

data(mtcars)
mod <- lm(mpg ~ wt + qsec, data = mtcars)
performBPTestRobust(mod, mtcars, bootstrap = TRUE, B = 200)

Description

Computes the classical Breusch\–Pagan statistic using chunked cross-products so that large datasets can be evaluated without materialising the full auxiliary regression in memory. The streamed result is algebraically identical to performBPTest.

Usage

performBPTestStreaming(model, data, chunk_size = 10000, progress = interactive())

Arguments

Details

Each chunk contributes to the cross-product matrices $X'X$ and $X'y$ for the auxiliary regression of squared residuals on the original regressors. The chunks are aggregated to recover the exact Breusch\–Pagan statistic while keeping memory usage bounded. When Matrix is installed, sparse cross-products are used automatically for large chunks.

Value

A htest object mirroring performBPTest and reporting the chi-squared statistic, degrees of freedom, p-value, and metadata describing the chunked computation.

See Also

performBPTest for the standard implementation.

Examples

data(mtcars)
mod <- lm(mpg ~ wt + qsec, data = mtcars)
performBPTestStreaming(mod, mtcars, chunk_size = 16, progress = FALSE)

Description

Brown-Forsythe test using medians instead of means.

Usage

performBrownForsytheTest(model, data, group)

Arguments

Details

The absolute deviations from the group medians are compared across groups. The resulting statistic is an $F$ ratio with $k-1$ and $N-k$ degrees of freedom.

Value

An object of class htest containing the F statistic, p-value and degrees of freedom.

References

Brown, M. B., & Forsythe, A. B. (1974). Robust tests for the equality of variances. Journal of the American Statistical Association, 69(346), 364–367.

Examples

data(mtcars)
 mtcars$cyl <- factor(mtcars$cyl)
 m <- lm(mpg ~ wt, data = mtcars)
 performBrownForsytheTest(m, mtcars, "cyl")

Description

The Cook-Weisberg (1983) score test with the fitted values as the sole variance regressor.

Usage

performCookWeisbergTest(model)

Arguments

Details

Writing $\hat{\sigma}^2 = \sum_i \hat{e}_i^2 / n$ for the maximum-likelihood error variance, the test regresses the scaled squared residuals $\hat{e}_i^2 / \hat{\sigma}^2$ on the fitted values and refers half the explained sum of squares to a chi-square distribution with one degree of freedom. This is the diagnostic returned by Stata's estat hettest with the fitted option, and it is exactly performNCVTest with its default variance model.

The chi-square reference distribution follows from the null variance of $\hat{e}^2 / \sigma^2$ being 2, which holds under normal errors. When that assumption is doubtful, prefer performKoenkerTest.

Value

An object of class htest containing the score statistic, its single degree of freedom and the p-value.

Validation

Reproduces car::ncvTest() to within 1e-8; see ‘tests/testthat/test-pass-a-reference.R’. Releases before 0.7.0 returned $n R^2$ from regressing the raw squared residuals on the fitted values, which is the studentized (Koenker) statistic rather than the Cook-Weisberg score test.

References

Cook, R. D., & Weisberg, S. (1983). Diagnostics for heteroscedasticity in regression. Biometrika, 70(1), 1–10. doi:10.1093/biomet/70.1.1

See Also

performNCVTest, performKoenkerTest, performBPTest

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performCookWeisbergTest(m)

Description

Regresses log(residual^2) on fitted values using a polynomial.

Usage

performDavidianCarrollTest(model, degree = 2)

Arguments

Details

A polynomial in the fitted values is fitted to $\log(e^2)$. Joint significance of the polynomial terms is evaluated with an $F$ statistic.

Value

An object of class htest.

References

Davidian, M., & Carroll, R. J. (1987). Variance function estimation. Journal of the American Statistical Association, 82(400), 1079–1091.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performDavidianCarrollTest(m)

Description

Non-parametric test based on ranks.

Usage

performFlignerKilleenTest(model, data, group)

Arguments

Details

Absolute residuals are ranked after adjusting for group medians. The statistic approximates a chi-square distribution with $k-1$ degrees of freedom.

Value

An object of class htest containing the chi-squared statistic, p-value and degrees of freedom.

References

Fligner, M. A., & Killeen, T. J. (1976). Distribution-free two-sample tests for scale. Journal of the American Statistical Association, 71(353), 210–213.

Examples

data(mtcars)
 mtcars$cyl <- factor(mtcars$cyl)
 m <- lm(mpg ~ wt, data = mtcars)
 performFlignerKilleenTest(m, mtcars, "cyl")

Description

Regresses absolute residuals on a transformation of a suspected variable.

Usage

performGlejserTest(model, data, variable,
                   transformation = c("abs", "sqrt", "inverse", "inverse_sqrt"))

Arguments

Details

A variety of transformations of the explanatory variable (e.g. absolute value, square root) can reveal a relationship between scale and the covariate. Significance of the slope parameter is assessed with a t test.

Value

An object of class htest containing the t statistic, p-value and degrees of freedom.

References

Glejser, H. (1969). A new test for heteroskedasticity. Journal of the American Statistical Association, 64(325), 316–323.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performGlejserTest(m, mtcars, "wt")

Description

Implements the Goldfeld-Quandt test on a fitted linear model with directional or two-sided alternatives.

Usage

performGQTest(model, data, order_by, fraction = 0.2,
  alternative = c("greater", "two.sided", "less"))

Arguments

Details

Observations are ordered by a suspected variance-driving variable. With the split point fixed at the sample midpoint, a central fraction is omitted and the original model is re-estimated on the lower and upper segments. The statistic is the residual mean square of segment 2 divided by the residual mean square of segment 1 and is therefore directional rather than being forced above one. Split arithmetic and p-value conventions match lmtest::gqtest(..., point = 0.5).

Value

An object of class htest containing the directional GQ statistic, p-value, degrees of freedom and alternative hypothesis.

References

Goldfeld, S. M., & Quandt, R. E. (1965). Some tests for homoscedasticity. Journal of the American Statistical Association, 60(310), 539–547. doi:10.1080/01621459.1965.10480811

Greene, W. H. (2018). Econometric Analysis (8th ed.). Pearson.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performGQTest(m, mtcars, order_by = "wt")
 performGQTest(m, mtcars, order_by = "wt", alternative = "two.sided")

Description

Compares the maximum and minimum group residual variances using Hartley's maximum F-ratio distribution.

Usage

performHartleyFmaxTest(model, data, group)

Arguments

Details

The statistic is $F_{max}=\max_j s_j^2/\min_j s_j^2$. Under normality and equal group sizes its null distribution is the maximum F-ratio distribution for $k$ independent mean squares with common degrees of freedom, evaluated with SuppDists::pmaxFratio(). If group sizes differ, the function warns and rounds the mean group size, then subtracts one, to obtain an approximate common integer degrees of freedom.

Value

An object of class htest containing the Fmax statistic, number of groups, reference degrees of freedom and p-value.

References

Hartley, H. O. (1950). The maximum F-ratio as a short-cut test for heterogeneity of variance. Biometrika, 37(3/4), 308–312.

Examples

set.seed(1701)
 n <- 20
 d <- data.frame(g = factor(rep(letters[1:3], each = n)), x = rnorm(3 * n))
 d$y <- 1 + d$x + rnorm(3 * n)
 m <- lm(y ~ x, data = d)
 performHartleyFmaxTest(m, d, "g")

Description

Harvey's (1976) Lagrange multiplier test, which regresses log(residuals^2) on a set of variance regressors.

Usage

performHarveyTest(model, auxiliary = c("regressors", "fitted"),
                  studentize = FALSE)

Arguments

Details

Harvey (1976) models the error variance as $\sigma_i^2 = \exp(z_i^\top \gamma)$ and tests $\gamma = 0$ through the auxiliary regression of $\log \hat{e}_i^2$ on $z_i$. Under the null the auxiliary error behaves like a centred $\log \chi^2_1$ variate with variance $\pi^2 / 2 \approx 4.9348$, so the classical statistic is $\mathrm{ESS} / (\pi^2 / 2)$, asymptotically chi-square with $q$ degrees of freedom.

Setting studentize = TRUE replaces the fixed constant $\pi^2 / 2$ with the auxiliary residual mean square and refers the overall F statistic to an F distribution. The two forms are asymptotically equivalent under normal errors; the studentized form is more reliable when normality is doubtful, because $\pi^2 / 2$ is the null variance of $\log \hat{e}^2$ only for Gaussian errors.

Degrees of freedom are taken from the realised rank of the auxiliary design, so a rank-deficient variance model is not credited with degrees of freedom for aliased columns.

Value

An object of class htest containing the test statistic, its degrees of freedom and the p-value.

Validation

The default statistic reproduces an independent reconstruction of Harvey (1976) to within 1e-8; see ‘tests/testthat/test-pass-a-reference.R’. Simulated size and power are recorded in ‘inst/validation/pass-a-size-power.csv’.

References

Harvey, A. C. (1976). Estimating regression models with multiplicative heteroscedasticity. Econometrica, 44(3), 461–465. doi:10.2307/1913974

Greene, W. H. (2018). Econometric Analysis (8th ed.). Pearson. Section 9.5 derives the $\mathrm{ESS} / 4.9348$ form of the statistic.

See Also

performParkTest, performGlejserTest, performBPTest

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performHarveyTest(m)

 # Studentized variant, which does not assume normal errors
 performHarveyTest(m, studentize = TRUE)

 # Variance driven by the conditional mean rather than by the regressors
 performHarveyTest(m, auxiliary = "fitted")

Description

Applies principal component projections to the design matrix and evaluates a Breusch-Pagan style statistic on the reduced representation. The procedure is designed for settings where the number of predictors rivals or exceeds the sample size.

Usage

performHighDimensionalTest(
  model,
  data,
  variance_threshold = 0.9,
  max_components = NULL
)

Arguments

Value

An htest object summarising the chi-squared statistic of the auxiliary regression on principal component scores.

References

Fan, J., & Lv, J. (2008). Sure independence screening for ultrahigh dimensional feature space. Journal of the Royal Statistical Society: Series B, 70(5), 849–911.

Examples

set.seed(123)
X <- matrix(rnorm(80 * 20), nrow = 80)
beta <- c(rep(1, 5), rep(0, 15))
y <- X %*% beta + rnorm(80, sd = 0.5 + 0.2 * scale(X[, 1]))
df <- as.data.frame(cbind(y = as.numeric(y), X))
model <- lm(y ~ ., data = df)
performHighDimensionalTest(model, df)

Description

Uses Cook's distance to flag influential observations.

Usage

performInfluenceDiagnostics(model, cutoff = NULL)

Arguments

Value

A list with Cook's distances and indices of influential points.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
performInfluenceDiagnostics(m)

Description

Implementation of the Koenker version of the Breusch-Pagan test.

Usage

performKoenkerTest(model, data)

Arguments

Details

Squared residuals are regressed on the regressors but the statistic $n R^2$ uses a studentized form that is robust to non-normality.

Value

An object of class htest containing the test statistic, p-value and degrees of freedom.

References

Koenker, R. (1981). A note on studentizing a test for heteroscedasticity. Journal of Econometrics, 17(1), 107–112.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performKoenkerTest(m, mtcars)

Description

Evaluates Koenker's studentized variant of the Breusch\–Pagan test (the $n R^2$ statistic from regressing the squared residuals on the regressors) using streamed cross-products so that large datasets can be processed without allocating the full auxiliary regression matrix.

Usage

performKoenkerTestStreaming(model, data, chunk_size = 10000, progress = interactive())

Arguments

Details

Chunks of the data contribute to the cross-product matrices for the regression of squared residuals on the model regressors. Aggregating these matrices yields the exact Koenker statistic while bounding memory usage. Sparse cross-products from Matrix are used automatically when available for large chunks.

Value

A htest object equivalent to performKoenkerTest with metadata recording the streaming configuration.

See Also

performKoenkerTest for the standard implementation.

Examples

data(mtcars)
mod <- lm(mpg ~ wt + qsec, data = mtcars)
performKoenkerTestStreaming(mod, mtcars, chunk_size = 16, progress = FALSE)

Description

Tests equality of variances across groups using residuals from a linear model.

Usage

performLeveneTest(model, data, group)

Arguments

Details

Absolute deviations from group means are analyzed via a one-way ANOVA. The resulting $F$ statistic has $k-1$ and $N-k$ degrees of freedom under the null of equal variances.

Value

An object of class htest containing the F statistic, p-value and degrees of freedom.

References

Levene, H. (1960). Robust tests for equality of variances. In Contributions to Probability and Statistics (pp. 278–292). Stanford University Press.

Brown, M. B., & Forsythe, A. B. (1974). Robust tests for the equality of variances. Journal of the American Statistical Association, 69(346), 364–367. doi:10.1080/01621459.1974.10482955

Examples

data(mtcars)
 mtcars$cyl <- factor(mtcars$cyl)
 m <- lm(mpg ~ wt, data = mtcars)
 performLeveneTest(m, mtcars, "cyl")

Description

Applies the Ljung-Box test to squared residuals.

Usage

performMcLeodLiTest(model, lags = 10)

Arguments

Details

Serial correlation in $e_t^2$ indicates conditional heteroscedasticity. The Ljung-Box statistic is compared to a chi-square distribution with the chosen number of lags.

Value

An object of class htest containing the test statistic, p-value and degrees of freedom.

References

McLeod, A. I., & Li, W. K. (1983). Diagnostic checking ARMA time series models using squared-residual autocorrelations. Journal of Time Series Analysis, 4(4), 269–273.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performMcLeodLiTest(m, lags = 10)

Description

The Cook-Weisberg score test for non-constant error variance, the diagnostic returned by car::ncvTest().

Usage

performNCVTest(model, var_formula = NULL)

Arguments

Details

Let $\hat{e}_i$ denote the OLS residuals and $\hat{\sigma}^2 = \sum_i \hat{e}_i^2 / n$ the maximum-likelihood variance estimate. The test regresses the scaled squared residuals $u_i = \hat{e}_i^2 / \hat{\sigma}^2$ on the variance regressors $Z$ and computes half the explained sum of squares of that auxiliary regression. Under homoscedasticity and normal errors the statistic is asymptotically chi-square with degrees of freedom equal to the number of variance regressors.

With var_formula = NULL the fitted values are the sole variance regressor, matching the default of car::ncvTest() and Stata's estat hettest.

Because the divisor 2 is the null variance of $\hat{e}^2 / \sigma^2$ under normality, the test is sensitive to non-normal errors; performKoenkerTest provides the studentized variant, which is robust to non-normal kurtosis.

Value

An object of class htest containing the chi-square score statistic, its degrees of freedom and the p-value.

Validation

Reproduces car::ncvTest() to within 1e-8 for both the default and the var_formula forms; see ‘tests/testthat/test-pass-a-reference.R’. Releases before 0.7.0 regressed the absolute residuals on the fitted values and reported a t statistic, which is a Glejser-type test rather than the Cook-Weisberg score test.

References

Cook, R. D., & Weisberg, S. (1983). Diagnostics for heteroscedasticity in regression. Biometrika, 70(1), 1–10. doi:10.1093/biomet/70.1.1

Fox, J., & Weisberg, S. (2019). An R Companion to Applied Regression (3rd ed.). SAGE.

See Also

performCookWeisbergTest, performKoenkerTest, performBPTest

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performNCVTest(m)

 # Score test against a specific variance model rather than the fitted values
 performNCVTest(m, var_formula = ~wt)

Description

Implements O'Brien's observation-level transformed-residual test for equality of group variances.

Usage

performOBrienTest(model, data, group)

Arguments

Details

For each residual within a group, O'Brien's transformation combines its squared deviation from the group mean with the group's sample variance and sample size. A one-way ANOVA of those transformed observations yields an approximate $F_{k-1,N-k}$ test. Every group must contain at least three observations.

Value

An object of class htest containing the F statistic, numerator and denominator degrees of freedom, and p-value.

References

O'Brien, R. G. (1981). A simple test for variance effects in experimental designs. Psychological Bulletin, 89(3), 570–574.

Examples

set.seed(1702)
 n <- 25
 d <- data.frame(g = factor(rep(letters[1:3], each = n)), x = rnorm(3 * n))
 d$y <- 2 + d$x + rnorm(3 * n, sd = rep(c(1, 1, 1.8), each = n))
 m <- lm(y ~ x, data = d)
 performOBrienTest(m, d, "g")

Description

Regresses the log of squared residuals on the log of a suspected variable.

Usage

performParkTest(model, data, variable)

Arguments

Details

The slope coefficient from $\log(e^2)$ regressed on $\log x$ is tested for zero using a t statistic. A significant coefficient indicates scale depending on $x$.

Value

An object of class htest containing the t statistic, p-value and degrees of freedom.

References

Park, R. E. (1966). Estimation with heteroscedastic error terms. Econometrica, 34(5), 888.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performParkTest(m, mtcars, "wt")

Description

Checks for cross-sectional dependence in panel residuals.

Usage

performPesaranTest(model, data, id, time)

Arguments

Details

The statistic averages pairwise correlation coefficients of the residuals and is standardized to follow a normal distribution under the null of independence.

Value

An object of class htest.

References

Pesaran, M. H. (2004). General diagnostic tests for cross section dependence in panels. Cambridge Working Papers in Economics.

Examples

df <- data.frame(id = rep(1:3, each = 5), time = rep(1:5, 3), x = runif(15), y = rnorm(15))
 m <- lm(y ~ x, data = df)
 performPesaranTest(m, df, "id", "time")

Description

Tests equality of regression slopes across two or more conditional quantiles using the joint Wald-type test implemented by quantreg::anova.rqs(). The procedure accounts for dependence among quantile-specific estimates from the same sample rather than treating their covariance matrices as independent.

Usage

performQuantileRegressionTest(
  model,
  data,
  taus = c(0.25, 0.75),
  se_type = c("nid", "ker"),
  iid = TRUE
)

Arguments

Details

Under a pure location-shift model with homoskedastic errors, regression slopes are equal across quantiles. Rejection therefore provides evidence against that location-shift/homoskedastic specification. The result should not be interpreted as a universal test for every possible form of heteroscedasticity.

Value

An htest object containing the F-like joint statistic, numerator and denominator degrees of freedom, p-value, fitted quantiles, and quantile-specific slope estimates.

References

Koenker, R., & Bassett, G. (1982). Robust tests for heteroscedasticity based on regression quantiles. Econometrica, 50(1), 43–61.

Koenker, R. (2005). Quantile Regression. Cambridge University Press.

Examples

if (requireNamespace("quantreg", quietly = TRUE)) {
  # The test needs at least 40 observations, so mtcars (32) is too small.
  model <- lm(stations ~ mag + depth, data = quakes)
  performQuantileRegressionTest(model, quakes)
}

Description

Performs a non-parametric permutation test based on the rank correlation between absolute residuals and a chosen ordering variable. Significant correlations imply systematic changes in residual spread.

Usage

performRankPermutationTest(
  model,
  data,
  order_by = NULL,
  B = 999,
  progress = interactive()
)

Arguments

Value

An htest object containing the observed Spearman correlation and a permutation-based p-value.

References

Hollander, M., Wolfe, D. A., & Chicken, E. (2013). Nonparametric Statistical Methods (3rd ed.). Wiley.

Examples

data(mtcars)
model <- lm(mpg ~ wt + hp, data = mtcars)
set.seed(42)
performRankPermutationTest(model, mtcars, B = 199, progress = FALSE)

Description

Adds powers of the fitted values and performs an F-test to check for neglected nonlinearity.

Usage

performRESETTest(model, power = 2:3)

Arguments

Value

An object of class htest.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
performRESETTest(m)

Description

Computes correlations between absolute residuals and selected variables.

Usage

performScatterDiagnostic(model, data, vars)

Arguments

Details

High correlations suggest increasing spread with the explanatory variables and motivate variance-stabilizing transformations.

Value

A named numeric vector of correlations.

References

Cleveland, W. S. (1979). Robust locally weighted regression and smoothing scatterplots. Journal of the American Statistical Association, 74(368), 829–836.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performScatterDiagnostic(m, mtcars, c("wt", "qsec"))

Description

Evaluates spatial clustering in squared residuals using Moran's I with a permutation reference distribution. Significant positive autocorrelation in the squared residuals is evidence of spatially varying variance.

Usage

performSpatialHeteroTest(
  model,
  data,
  listw,
  permutations = 499,
  zero.policy = NULL
)

Arguments

Value

An htest result with Moran's I statistic applied to squared residuals.

References

Anselin, L. (1988). Spatial Econometrics: Methods and Models. Kluwer.

Bivand, R. S., Pebesma, E., & Gómez-Rubio, V. (2013). Applied Spatial Data Analysis with R (2nd ed.). Springer.

Examples

if (requireNamespace("spdep", quietly = TRUE)) {
  data(mtcars)
  coords <- cbind(runif(nrow(mtcars)), runif(nrow(mtcars)))
  nb <- spdep::knn2nb(spdep::knearneigh(coords, k = 4))
  lw <- spdep::nb2listw(nb)
  model <- lm(mpg ~ wt + hp, data = mtcars)
  performSpatialHeteroTest(model, mtcars, listw = lw, permutations = 199)
}

Description

Computes Spearman's rho between absolute residuals and fitted values.

Usage

performSpearmanTest(model)

Arguments

Details

The squared rank correlation coefficient times the sample size minus 1 approximates a chi-square distribution with one degree of freedom.

Value

An object of class htest containing the test statistic, p-value, degrees of freedom and rho.

References

Spearman, C. (1904). The proof and measurement of association between two things. American Journal of Psychology, 15(1), 72–101.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performSpearmanTest(m)

Description

Tests the slope of log(|residuals|) on log(fitted).

Usage

performSpreadLevelTest(model)

Arguments

Details

A slope near 0 indicates constant variance. A significant slope suggests a power transformation may stabilize the spread.

Value

An object of class htest.

References

Cleveland, W. S. (1979). Robust locally weighted regression and smoothing scatterplots. Journal of the American Statistical Association, 74(368), 829–836.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performSpreadLevelTest(m)

Description

Computes the Koenker–Bassett studentized Lagrange Multiplier statistic for heteroscedasticity by regressing centred squared residuals on the regressors. Compared with the classical Breusch–Pagan test, the studentized version is less sensitive to violations of normality and small-sample bias.

Usage

performStudentizedBPTest(model, data)

Arguments

Details

Following Koenker (1981) and the implementation in lmtest::bptest(), the procedure fits an auxiliary regression of $e_i^2 - \hat{\sigma}^2$ on the regressors from the original model (including the intercept), where $e_i$ denotes the weighted residuals and $\hat{\sigma}^2$ their mean squared error. Under homoskedasticity the statistic $T = n \sum w_i \hat{g}_i^2 / \sum (e_i^2 - \hat{\sigma}^2)^2$ is asymptotically chi-squared with degrees of freedom equal to the number of regressors beyond the intercept. The implementation shares the validation helpers used across the package to ensure that: (i) the model and data satisfy minimum sample-size thresholds via rvalidateModelInputs() and rvalidateDataInputs(), (ii) missing values are handled by rhandleMissingValues(), and (iii) studentized-residual specific requirements registered in rvalidateTestRequirements() are met.

Value

An object of class htest reporting the chi-squared statistic and p-value for the null hypothesis of constant error variance.

References

Koenker, R. (1981). A note on studentizing a test for heteroscedasticity. Journal of Econometrics, 17(1), 107–112. doi:10.1016/0304-4076(81)90062-2

Davidson, R., & MacKinnon, J. G. (2004). Econometric Theory and Methods. Oxford University Press. Section 16.7 discusses LM tests for heteroscedasticity including studentized variants.

See Also

performBPTest() for the classical LM statistic and performKoenkerTest() for the absolute-residual variant. The robust workflow in performBPTestRobust() augments the studentized statistic with bootstrap diagnostics.

Examples

data(mtcars)
mod <- lm(mpg ~ wt + qsec, data = mtcars)
performStudentizedBPTest(mod, mtcars)

# Detect heteroscedasticity driven by a single regressor
set.seed(321)
x <- runif(180)
y <- 5 - 1.5 * x + rnorm(180, sd = 0.4 + 0.6 * x)
df <- data.frame(y, x)
performStudentizedBPTest(lm(y ~ x, data = df), df)

Description

Detects monotonic changes in variance when observations can be meaningfully ordered—typically by time or another covariate—using the cumulative weighting scheme proposed by Szroeter (1978).

Usage

performSzroeterTest(model, data, order_by,
  alternative = c("greater", "two.sided", "less"))

Arguments

Details

After ordering the residuals $\hat{e}_{(i)}$ by order_by, the test forms the rank-weighted average of the squared residuals

$h = \frac{\sum_{i = 1}^n i \, \hat{e}_{(i)}^2}{\sum_{i = 1}^n \hat{e}_{(i)}^2},$

which is Szroeter's (1978) class of statistics evaluated at the canonical weights $h_i = i$. Under homoskedasticity $h$ is centred on the mean rank $(n + 1) / 2$ with variance $(n^2 - 1) / (6n)$, so

$Q = \frac{h - (n + 1) / 2}{\sqrt{(n^2 - 1) / (6n)}}$

is asymptotically standard normal. Variance that grows with order_by shifts weight onto the high ranks and drives $Q$ upwards.

The implementation relies on the package validation helpers to align the supplied data with the model residuals, check that the ordering variable is present, and ensure sufficient sample size and variability in the squared residuals.

Value

An object of class htest reporting Szroeter's standardised statistic Q, the sample size, the underlying rank-weighted statistic h in estimate, and the p-value from the asymptotic normal reference distribution.

Validation

The statistic and its null variance are checked against an independent reconstruction of Szroeter (1978) in ‘tests/testthat/test-pass-a-reference.R’. Releases before 0.7.0 divided the centred statistic by a further $\sqrt{n}$, shrinking $Q$ by a factor of roughly $2 / \sqrt{n}$ and leaving the test with essentially no power against any alternative; see ‘NEWS.md’.

References

Szroeter, J. (1978). A class of parametric tests for heteroscedasticity in linear econometric models. Econometrica, 46(6), 1311–1327. doi:10.2307/1913833

Godfrey, L. G. (1988). Misspecification Tests in Econometrics. Cambridge University Press. Section 5.4 outlines the Szroeter test.

See Also

performKoenkerTest() for the regressor-based alternative and performGQTest() for split-sample diagnostics on ordered data.

Examples

data(mtcars)
mod <- lm(mpg ~ wt + qsec, data = mtcars)
performSzroeterTest(mod, mtcars, order_by = "wt")

# Detect ordered heteroscedasticity in simulated data with variance increasing
# in an index variable
set.seed(404)
n <- 150
x <- sort(runif(n))
y <- 2 + 0.5 * x + rnorm(n, sd = 0.4 + 0.8 * x)
df <- data.frame(y, x)
performSzroeterTest(lm(y ~ x, data = df), df, order_by = "x")

# Two-sided version when the direction of the change is not known in advance
performSzroeterTest(mod, mtcars, order_by = "wt", alternative = "two.sided")

Description

Compute variance inflation factors for assessing multicollinearity. Each VIF is the corresponding diagonal element of the inverse correlation matrix of the design, so the computation works for models containing factors (each contrast column receives its own VIF).

Usage

performVIFDiagnostic(model)

Arguments

Value

A named numeric vector of VIF values, one per design-matrix column (excluding the intercept). Perfectly collinear columns are reported as Inf.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
performVIFDiagnostic(m)

Description

Implements White's test on a fitted linear model.

Usage

performWhiteTest(model, data, cross_products = TRUE, max_interactions = 10)

Arguments

Details

An auxiliary regression of $e^2$ on all regressors, their squares and cross-products produces $R^2$. The statistic $n R^2$ follows a chi-square distribution with degrees of freedom equal to the number of regressors in the auxiliary model.

Value

An object of class htest containing the test statistic, p-value and degrees of freedom.

References

White, H. (1980). A heteroskedasticity-consistent covariance matrix estimator and a direct test for heteroskedasticity. Econometrica, 48(4), 817–838. doi:10.2307/1912934

Greene, W. H. (2018). Econometric Analysis (8th ed.). Pearson.

Examples

data(mtcars)
 m <- lm(mpg ~ wt + qsec, data = mtcars)
 performWhiteTest(m, mtcars)

Description

Approximates the finite-sample distribution of White's LM statistic by resampling the fitted residuals, refitting the model, and recalculating the test statistic across many bootstrap replications.

Usage

performWhiteTestBootstrap(model, data, B = 1000, parallel = FALSE)

Arguments

Details

For a fitted model $\hat{y} = X\hat{\beta}$, the algorithm proceeds as follows:

1. Compute White's LM statistic $n R^2$ from the auxiliary regression on squares and cross-products of the regressors.

2. Generate $B$ bootstrap samples by resampling the centred residuals with replacement, forming $y^{*(b)} = \hat{y} + \hat{e}^{*(b)}$.

3. Refit the model to each bootstrap sample and recompute White's statistic $T^{*(b)}$ using the same auxiliary specification.

4. Estimate the bootstrap p-value as $\hat{p} = B^{-1} \sum_{b = 1}^B I\{T^{*(b)} \ge T_{\text{obs}}\}$.

The bootstrap distribution offers improved size control for moderate sample sizes or high-dimensional designs where the chi-squared approximation may be inaccurate. When parallel = TRUE the resampling step exploits available CPU cores to reduce computation time.

Value

A htest object reporting both the asymptotic White statistic and its bootstrap p-value. The returned object also stores the simulated test statistics in boot_statistics for further inspection.

References

Efron, B., & Tibshirani, R. J. (1993). An Introduction to the Bootstrap. Chapman & Hall/CRC.

Davidson, R., & MacKinnon, J. G. (2006). The power of bootstrap and asymptotic tests. Journal of Econometrics, 133(2), 421–441. doi:10.1016/j.jeconom.2005.02.002

See Also

performWhiteTest() for the classical statistic and performWhiteTestRobust() for enriched diagnostics.

Examples

# The bootstrap needs at least 50 observations, so mtcars (32) is too small.
set.seed(42)
n <- 120
sim <- data.frame(x = runif(n, 1, 5))
sim$y <- 1 + 2 * sim$x + rnorm(n, sd = 0.3 + 0.6 * sim$x)
mod <- lm(y ~ x, data = sim)
performWhiteTestBootstrap(mod, sim, B = 199)


# More replications give a smoother p-value estimate
performWhiteTestBootstrap(mod, sim, B = 499)

# Enable parallel processing when supported by the operating system
if (.Platform$OS.type != "windows") {
  performWhiteTestBootstrap(mod, sim, B = 199, parallel = TRUE)
}

Description

Extends performWhiteTest() with optional bootstrap resampling, confidence intervals, effect size reporting, and power analysis.

Usage

performWhiteTestRobust(
  model,
  data,
  method = c("standard", "reduced"),
  bootstrap = FALSE,
  B = 1000,
  ci_level = 0.95,
  parallel = FALSE
)

Arguments

Details

Provides enriched inference around the White test by combining bootstrap resampling (Efron & Tibshirani, 1993) with asymptotic approximations. The robust_details element summarises interval estimates, effect sizes, and power calculations to aid decision-making.

Value

An object of class htest augmented with a robust_details list containing bootstrap, effect size, and power information.

References

White, H. (1980). A heteroskedasticity-consistent covariance matrix estimator and a direct test for heteroscedasticity. Econometrica, 48(4), 817–838.

Efron, B., & Tibshirani, R. J. (1993). An Introduction to the Bootstrap. Chapman & Hall.

See Also

performWhiteTest() for the base statistic and performWhiteTestBootstrap() for a lighter-weight resampling option.

Examples

data(mtcars)
mod <- lm(mpg ~ wt + qsec, data = mtcars)
performWhiteTestRobust(mod, mtcars, bootstrap = TRUE, B = 200)

Description

Computes White's statistic via chunked cross-products rather than fitting the full auxiliary regression in memory. This streaming approach allows the test to scale to datasets that would otherwise exhaust available RAM.

Usage

performWhiteTestStreaming(
  model,
  data,
  chunk_size = 10000,
  cross_products = TRUE,
  max_interactions = 10,
  progress = interactive()
)

Arguments

Details

The streaming implementation iteratively builds the cross-product matrices required for the auxiliary regression without materialising the full design matrix. Each chunk contributes to $X'X$, $X'y$, and summary statistics for the response. The final $n R^2$ statistic is then computed exactly as in the standard White test, ensuring numerical equivalence while dramatically reducing peak memory usage. When Matrix is installed, sparse cross-products are leveraged automatically for large chunks.

Value

A htest object containing the chi-squared statistic, p-value, and metadata about the chunked computation.

References

White, H. (1980). A heteroskedasticity-consistent covariance matrix estimator and a direct test for heteroscedasticity. Econometrica, 48(4), 817–838.

See Also

performWhiteTest() for the exact computation and performWhiteTestRobust() for enhanced reporting.

Examples

data(mtcars)
performWhiteTestStreaming(lm(mpg ~ wt + qsec, data = mtcars), mtcars, chunk_size = 16)

Description

Calibrates the Breusch-Pagan Lagrange multiplier statistic with a null-imposed wild bootstrap, providing a p-value that is accurate in small samples and under non-normal errors without relying on the asymptotic $\chi^2$ approximation.

Usage

performWildBootstrapTest(
  model,
  data,
  B = 499,
  distribution = c("rademacher", "mammen"),
  progress = interactive()
)

Arguments

Details

The observed statistic is the usual $n R^2$ from the auxiliary regression of the squared residuals on the regressors. The bootstrap reference distribution, however, must be generated under the homoscedastic null — otherwise it inherits the heteroscedasticity the test is looking for and the procedure loses all power. Each bootstrap sample is therefore built from leverage-standardised, mean-centred residuals $r_i = e_i/\sqrt{1-h_{ii}}$ (which have a common variance under $H_0$) resampled i.i.d. and perturbed by a wild multiplier $v_i$, so that $y_i^* = \hat y_i + r^*_i v_i$. The statistic is recomputed on each refit and the p-value is $(1 + \#\{T_b^* \ge T\})/(B + 1)$. Under $H_0$ this controls size even for heavy-tailed errors; under the alternative the observed statistic is extreme relative to the homoscedastic reference, giving power.

Value

An object of class htest containing the observed Breusch-Pagan statistic, bootstrap p-value, and additional details under the bootstrap element.

References

Davidson, R., & Flachaire, E. (2008). The wild bootstrap, tamed at last. Journal of Econometrics, 146(1), 162–169.

Godfrey, L. G. (2006). Tests for regression models with heteroskedasticity of unknown form. Computational Statistics & Data Analysis, 50(10), 2715–2733.

Wu, C. F. J. (1986). Jackknife, bootstrap and other resampling methods in regression analysis. The Annals of Statistics, 14(4), 1261–1295.

Examples

data(mtcars)
model <- lm(mpg ~ wt + qsec, data = mtcars)
if (interactive()) {
  set.seed(123)
  performWildBootstrapTest(model, mtcars, B = 199, progress = FALSE)
}

Description

Produce basic residual diagnostic plots.

Usage

## S3 method for class 'HeteroDiagnostic'
plot(x, plots = c("residuals_fitted", "spread_level",
  "density", "qq", "bubble_variance"), ...)

Arguments

Value

List of ggplot objects.

Description

Plot method for power analysis results

Usage

## S3 method for class 'power_analysis'
plot(x, ...)

Arguments

Description

Overlays residuals of two models on a single plot to visualise improvement after applying a remediation method (e.g. WLS or robust regression).

Usage

plotBeforeAfter(original, remedied)

Arguments

Value

A ggplot object with residuals of both models.

Examples

data(mtcars)
m1 <- lm(mpg ~ wt, data = mtcars)
m2 <- fitWLS(m1)
plotBeforeAfter(m1, m2)

Description

Displays residual magnitude against a predictor with bubble size proportional to ⁠|residual|⁠.

Usage

plotBubbleVariance(model, variable = NULL)

Arguments

Value

A ggplot object.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
plotBubbleVariance(m, "wt")

Description

This convenience wrapper returns residual-vs-fitted and spread-level plots to help visually assess heteroscedastic patterns.

Usage

plotDiagnosticSuite(model)

Arguments

Value

A list with elements residuals_fitted and spread_level, each a ggplot object.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
plots <- plotDiagnosticSuite(m)
plots$residuals_fitted

Description

Returns a list of improved diagnostic plots with statistical overlays.

Usage

plotDiagnosticSuiteEnhanced(model)

Arguments

Value

A list of ggplot objects.

Description

Shows the distribution of residuals with a kernel density estimate.

Usage

plotResidualDensity(model)

Arguments

Value

A ggplot object.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
plotResidualDensity(m)

Description

Visualises departure from normality using a QQ plot.

Usage

plotResidualQQ(model)

Arguments

Value

A ggplot object.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
plotResidualQQ(m)

Description

Generates a simple scatter plot of residuals against fitted values from a linear model. A horizontal reference line at zero is added.

Usage

plotResidualsFitted(model)

Arguments

Value

A ggplot object.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
plotResidualsFitted(m)

Description

Highlights influential observations and includes a LOESS smooth with confidence bands.

Usage

plotResidualsFittedEnhanced(model)

Arguments

Value

A ggplot object.

Description

Plots the square root of the absolute residuals against fitted values. A lowess smooth is added to highlight trends.

Usage

plotSpreadLevel(model)

Arguments

Value

A ggplot object.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
plotSpreadLevel(m)

Description

Print method for enhanced White test results

Usage

## S3 method for class 'htest_enhanced'
print(x, ...)

Arguments

Description

Provides a consistent wrapper around bootstrap resampling for test statistics produced by heteroscedasticity diagnostics. The routine refits the supplied model on each bootstrap replicate and evaluates test_function on it, returning the bootstrap distribution, a percentile interval, and—for null-imposed resampling—a p-value.

Usage

rbootstrap_test_statistic(
  test_function,
  model,
  data,
  B = 1000,
  parallel = FALSE,
  ci_level = 0.95,
  resample = c("null", "pairs"),
  n_cores = NULL,
  progress = interactive(),
  ...
)

Arguments

Details

The resample argument decides what the replicates mean.

With resample = "null" (the default) the response is regenerated as $\hat y_i + e^*_i$, where the $e^*_i$ are drawn with replacement from the model's residuals after dividing by $\sqrt{1 - h_i}$ and centring. Those data satisfy homoscedasticity by construction, so the replicates estimate the null distribution and p_value is a test. The leverage correction matters: OLS residuals have variance $\sigma^2 (1 - h_i)$, and resampling them unscaled under-disperses the regenerated errors, which inflates the rejection rate.

With resample = "pairs" rows are sampled with replacement. The replicates then follow the statistic's distribution under whatever variance structure the data actually have, which is useful for describing its variability but is not a null distribution: the replicates are centred on the observed statistic, so comparing the two returns roughly 0.5 whatever the data. Measured rejection under $\sigma_i = x_i^2$ was 0%. p_value is therefore NA for pairs resampling.

Neither strategy accepts a glm: each replicate is refitted with least squares, so the family and link would be discarded and the replicates would describe a different model from the one supplied.

Null-imposed resampling additionally requires the response to be a plain variable. For log(y) ~ x the fitted values are on the log scale while the data column holds y, so regenerating one from the other and refitting would take the logarithm twice. That case raises an error; resample = "pairs" resamples rows and is unaffected by it.

Value

A list with components:

original

Result returned by test_function on the original data.

original_statistic

Numeric value of the test statistic from the original sample.

replicates

Numeric vector of bootstrap statistics.

ci

Percentile interval of the bootstrap distribution of the statistic, at ci_level. This summarises where the resampled statistic falls; it is not a confidence interval for a parameter and carries no coverage guarantee.

p_value

Empirical p-value from the null-imposed replicates, computed as $(1 + \#\{T^*_b \ge T\}) / (B_{\mathrm{eff}} + 1)$; NA when resample = "pairs".

B

Requested number of replications.

effective_samples

Number of non-missing bootstrap replications.

call

Matched call for reproducibility.

Examples

data(mtcars)
model <- lm(mpg ~ wt + cyl, data = mtcars)
if (interactive()) {
  set.seed(123)
  boot <- rbootstrap_test_statistic(performWhiteTest, model, mtcars, B = 100)
  boot$ci
}

Description

Converts chi-squared statistics produced by heteroscedasticity tests into interpretable effect sizes such as Cramer's V, the phi coefficient, or an eta-squared analogue. The helper also provides qualitative magnitude descriptors and a brief interpretation string that can be surfaced to users.

Usage

rcalculateEffectSize(
  test_result,
  model,
  data,
  type = c("cramers_v", "phi", "eta_squared")
)

Arguments

Value

A named list with elements effect_size, magnitude, practical_significance, interpretation, and type.

Examples

data(mtcars)
model <- lm(mpg ~ wt + cyl, data = mtcars)
result <- performWhiteTest(model, mtcars)
rcalculateEffectSize(result, model, mtcars)

Description

Adds a function to the diagnostics registry so it can be called by runHeteroTests.

Usage

registerDiagnostic(name, fun)

Arguments

Value

Invisibly returns NULL.

Examples

custom <- function(model, data) list(statistic = 0)
registerDiagnostic("custom", custom)

Description

Register a diagnostic plot

Usage

registerPlot(name, fun)

Arguments

Value

Invisibly returns NULL.

Examples

registerPlot("custom_plot", function(model) ggplot2::ggplot())

Description

Uses the observed chi-squared statistic and effect size to approximate the achieved power of a heteroscedasticity test and to suggest an increased sample size required to attain the desired power threshold.

Usage

restimate_test_power(
  test_result,
  model,
  data,
  alpha = 0.05,
  target_power = 0.8,
  max_multiplier = 5
)

Arguments

Value

A list with elements power, recommended_n, and details containing auxiliary information (degrees of freedom, non-centrality parameter, and a power curve over a grid of effect sizes).

Description

Provides enhanced implementations of core heteroscedasticity diagnostics with bootstrap support, effect size calculations, and statistical power summaries. The module also exposes orchestration helpers for running the enhanced diagnostics in batch and utilities for validating results against reference implementations from other packages.

Description

Executes one or more robust diagnostics with automatic enhancements for small samples and optional studentisation.

Usage

rrunAdvancedDiagnostics(
  model,
  data,
  tests = "all",
  auto_enhance = TRUE,
  bootstrap_B = 500,
  parallel = FALSE,
  ci_level = 0.95
)

Arguments

Value

A list with the executed results and metadata describing the enhancements that were applied.

Description

run_benchmark_suite() evaluates a selection of heteroscedasticity diagnostics across varying sample sizes while measuring runtime, memory allocation, and statistical agreement with the lmtest and car packages. The companion generate_benchmark_report() helper aggregates the raw output into tidy summary tables and recommendations.

Usage

run_benchmark_suite(
  sample_sizes = c(100L, 500L, 1000L, 10000L, 100000L, 1000000L),
  tests = NULL,
  replicates = 3L,
  hetero_patterns = c("none", "linear", "group"),
  hetero_strength = 1,
  baseline_packages = c("lmtest", "car"),
  seed = 123L,
  n_predictors = 4L,
  profile_memory = TRUE,
  progress = interactive()
)

generate_benchmark_report(benchmark_results, accuracy_tolerance = 1e-4)

Arguments

Details

Datasets are generated from a linear regression model with a configurable number of predictors and variance patterns (none, linear, group, or exponential). Each diagnostic from heteroTests is executed alongside equivalent tests from lmtest and car when available. Memory profiling is enabled via bench when installed; otherwise only runtimes are collected. The output is suitable for regression testing (to detect performance regressions) and for building artefacts such as CSV benchmark reports.

Value

run_benchmark_suite() returns a list with four elements:

performance

Data frame containing runtime, memory, and inference metrics for every test, sample size, and replicate.

accuracy

Data frame recording absolute differences in p-values and test statistics relative to each baseline implementation.

summary

List of aggregated medians for quick inspection of speed, memory, and accuracy.

metadata

Metadata describing the benchmark configuration (sample sizes, baselines, seed, and availability of optional dependencies).

generate_benchmark_report() converts the raw results into aggregated speed, memory, accuracy, recommendation, and scalability tables alongside the original metadata.

Examples

if (requireNamespace("lmtest", quietly = TRUE) &&
    requireNamespace("car", quietly = TRUE)) {
  results <- run_benchmark_suite(
    sample_sizes = c(100L, 250L),
    replicates = 1L,
    profile_memory = FALSE,
    progress = FALSE
  )
  report <- generate_benchmark_report(results)
  head(report$recommendations)
}

Description

Run registered diagnostic plots

Usage

runDiagnosticPlots(
  model,
  plots = c("residuals_fitted", "spread_level", "density", "qq", "bubble_variance")
)

Arguments

Value

Named list of ggplot objects

Examples

runDiagnosticPlots(lm(mpg ~ wt, mtcars))

Description

Combines heteroscedasticity checks with tests for collinearity, nonlinearity and influential observations.

Usage

runDiagnostics(
  model,
  data = NULL,
  tests = c("white", "breusch_pagan"),
  power = 2:3,
  use_cache = TRUE,
  chunk_threshold_mb = 100,
  chunk_size = 10000,
  progress = interactive()
)

Arguments

Value

A list with the results of all diagnostics.

Examples

data(mtcars)
runDiagnostics(mpg ~ wt + qsec, mtcars)

Description

Convenience wrapper that executes several heteroscedasticity tests on a fitted linear model.

Usage

runHeteroTests(
  model,
  data = NULL,
  tests = c("white", "breusch_pagan"),
  use_cache = TRUE,
  chunk_threshold_mb = 100,
  chunk_size = 10000,
  progress = interactive()
)

Arguments

Details

By default runs performWhiteTest and performBPTest, but additional tests can be requested. Custom diagnostics registered via registerDiagnostic are also available.

Value

A named list of htest objects.

References

White, H. (1980). A heteroskedasticity-consistent covariance matrix estimator and a direct test for heteroskedasticity. Econometrica, 48(4), 817–838. Breusch, T. S., & Pagan, A. R. (1979). A Simple Test for Heteroscedasticity and Random Coefficient Variation. Econometrica, 47(5), 1287–1294.

Examples

data(mtcars)
m <- lm(mpg ~ wt + qsec, data = mtcars)
# Default: White and Breusch-Pagan
runHeteroTests(m, mtcars)
# Specify additional diagnostics
runHeteroTests(m, mtcars, tests = c("white", "koenker", "ncv"))
custom <- function(model, data) list(stat = 1)
registerDiagnostic("custom", custom)
runHeteroTests(m, mtcars, tests = c("white", "custom"))

Description

Executes a set of registered diagnostics in parallel when multiple CPU cores are available, falling back to sequential execution otherwise.