Package {hcinfer}

Title: Heteroskedasticity-Consistent Inference for Linear Models
Version: 0.1.0
Description: Computes heteroskedasticity-consistent covariance matrix estimators for ordinary least squares regression models. The published HC0 through HC5m estimators implemented in the package follow White (1980) <doi:10.2307/1912934>, Hinkley (1977) <doi:10.1080/00401706.1977.10489550>, Horn et al. (1975) <doi:10.1080/01621459.1975.10479877>, MacKinnon and White (1985) <doi:10.1016/0304-4076(85)90158-7>, Cribari-Neto (2004) <doi:10.1016/S0167-9473(02)00366-3>, Cribari-Neto and da Silva (2011) <doi:10.1007/s10182-010-0141-2>, Cribari-Neto et al. (2007) <doi:10.1080/03610920601126589>, and Li et al. (2016) <doi:10.1080/00949655.2016.1198906>. The package also includes HCbeta, a new estimator proposed by the package authors. It provides normal Wald tests, confidence intervals, diagnostics, and S3 output for applied inference.
URL: https://prdm0.github.io/hcinfer/, https://github.com/prdm0/hcinfer
BugReports: https://github.com/prdm0/hcinfer/issues
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 4.1.0)
Imports: cli, ggplot2, purrr, rlang, tibble
Suggests: dplyr, knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/Needs/website: pkgdown
LazyData: true
Config/roxygen2/version: 8.0.0
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2026-06-05 12:46:39 UTC; prdm0
Author: Pedro Rafael D. Marinho ORCID iD [aut, cre], Francisco Cribari-Neto ORCID iD [aut], Marina Oliveira Cunha ORCID iD [aut]
Maintainer: Pedro Rafael D. Marinho <pedro.rafael.marinho@gmail.com>
Repository: CRAN
Date/Publication: 2026-06-10 08:00:02 UTC

hcinfer: Heteroskedasticity-consistent inference

Description

The hcinfer package computes heteroskedasticity-consistent covariance estimators for ordinary least squares models and reports normal Wald inference with rich S3 output.

Author(s)

Maintainer: Pedro Rafael D. Marinho pedro.rafael.marinho@gmail.com (ORCID)

Authors:

See Also

Useful links:

Public school expenditure and income by US state

Description

Public school expenditure and income data for US states and Washington DC in 1979. The expenditure value for Wisconsin is missing in the source data, so the standard regression example uses 50 complete observations. The data are useful for illustrating heteroskedasticity-consistent inference because Alaska is a high-leverage observation in the quadratic public-schools model studied in the HCbeta paper.

Usage

PublicSchools

Format

A tibble with 51 rows and 3 variables:

state

US state or Washington DC.

expenditure

Per capita expenditure on public schools in 1979. This variable has one missing value.

income

Per capita income in 1979.

Source

Greene, W. H. (1993). Econometric Analysis, 2nd ed. Macmillan Publishing Company, New York. Table 14.1, p. 385. The data were originally sourced from the U.S. Department of Commerce, Statistical Abstract of the United States (1979). The dataset is also available in the sandwich R package.

Examples

data(PublicSchools)
PublicSchools[PublicSchools$state == "Alaska", ]

schools <- PublicSchools |>
  dplyr::mutate(
    income_scaled = income / 10000,
    income_scaled_sq = income_scaled^2
  )
fit <- lm(expenditure ~ income_scaled + income_scaled_sq, data = schools)
hcinfer(fit, type = "hcbeta")

Extract model coefficients from an hcinfer object

Description

Extracts the OLS coefficients stored in an hcinfer() result.

Usage

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

Arguments

object

An object returned by hcinfer().

...

Unused.

Value

A named numeric vector of OLS coefficients.

Confidence intervals for hcinfer objects

Description

Extracts normal Wald confidence intervals from an hcinfer() result. If the requested level differs from the level used to create the object, only the normal critical value and interval endpoints are recomputed.

Usage

## S3 method for class 'hcinfer'
confint(object, parm, level = object$confidence_level, ...)

Arguments

object

An object returned by hcinfer().

parm

Optional coefficient names or positions.

level

Confidence level.

...

Unused.

Value

A tibble with columns term, conf_low, conf_high, and level.

Available heteroskedasticity-consistent estimators

Description

Returns the HC covariance estimators implemented by hcinfer.

Usage

hc_methods()

Value

A tibble with columns type, label, description, and default_arguments.

Examples

hc_methods()

Heteroskedasticity-consistent Wald inference

Description

Computes normal Wald tests and confidence intervals for an ordinary least squares model using a heteroskedasticity-consistent covariance estimator.

Usage

hcinfer(object, type = "hcbeta", alpha = 0.05, null = 0, ...)

Arguments

object

An ordinary least squares model fitted by stats::lm().

type

A character string specifying the HC estimator. The default is "hcbeta".

alpha

Significance level. The confidence level is 1 - alpha.

null

Null values for the coefficient tests. Use a scalar to test all coefficients against the same value, or a numeric vector with one value per coefficient.

...

Method-specific constants passed to vcov_hc(). Defaults are documented in vcov_hc() and can be inspected with hc_methods().

Details

For each coefficient, hcinfer tests

H_0: \beta_j = \beta_j^{(0)}

against a two-sided alternative using the statistic

z_j = \frac{\hat\beta_j - \beta_j^{(0)}} {\sqrt{[\widehat{\Psi}_{HC}]_{jj}}}.

The reference distribution is the standard normal distribution. Confidence intervals are Wald intervals obtained by direct inversion of the test,

\hat\beta_j \pm z_{1 - \alpha / 2} \sqrt{[\widehat{\Psi}_{HC}]_{jj}}.

Bootstrap intervals and Student t quantiles are not used.

Value

An object of class hcinfer containing the fitted HC covariance estimator, coefficient tests, p-values, confidence intervals, diagnostics, and method parameters.

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

Hinkley, D. V. (1977). Jackknifing in unbalanced situations. Technometrics, 19(3), 285-292. doi:10.1080/00401706.1977.10489550

Horn, S. D., Horn, R. A., and Duncan, D. B. (1975). Estimating heteroscedastic variances in linear models. Journal of the American Statistical Association, 70(350), 380-385. doi:10.1080/01621459.1975.10479877

MacKinnon, J. G. and White, H. (1985). Some heteroskedasticity-consistent covariance matrix estimators with improved finite sample properties. Journal of Econometrics, 29(3), 305-325. doi:10.1016/0304-4076(85)90158-7

Davidson, R. and MacKinnon, J. G. (1993). Estimation and Inference in Econometrics. Oxford University Press.

Cribari-Neto, F. (2004). Asymptotic inference under heteroskedasticity of unknown form. Computational Statistics and Data Analysis, 45(2), 215-233. doi:10.1016/S0167-9473(02)00366-3

Cribari-Neto, F. and da Silva, W. B. (2011). A new heteroskedasticity consistent covariance matrix estimator for the linear regression model. AStA Advances in Statistical Analysis, 95(2), 129-146. doi:10.1007/s10182-010-0141-2

Cribari-Neto, F., Souza, T. C., and Vasconcellos, K. L. P. (2007). Inference under heteroskedasticity and leveraged data. Communications in Statistics - Theory and Methods, 36(10), 1877-1888. doi:10.1080/03610920601126589

Li, S., Zhang, N., Zhang, X., and Wang, G. (2016). A new heteroskedasticity-consistent covariance matrix estimator and inference under heteroskedasticity. Journal of Statistical Computation and Simulation, 87(1), 198-210. doi:10.1080/00949655.2016.1198906

Examples

schools <- PublicSchools |>
  dplyr::mutate(
    income_scaled = income / 10000,
    income_scaled_sq = income_scaled^2
  )
fit <- lm(expenditure ~ income_scaled + income_scaled_sq, data = schools)
result <- hcinfer(fit, type = "hcbeta")
result
summary(result)
confint(result)

hcinfer(fit, type = "hcbeta", c1 = 7, c2 = 0.75, lower = 0.01, upper = 0.99)
hcinfer(fit, type = "hc5", k = 0.7)
hcinfer(fit, type = "hc5m", k = 0.7, k1 = 1, k2 = 0, k3 = 1)

Plot robust confidence intervals

Description

Plots normal Wald confidence intervals for an hcinfer() result. Each interval is color-coded by the test decision at the stored significance level: coefficients for which the null hypothesis is rejected are shown in red, and those for which it is not rejected are shown in blue. Formatted p-values are printed to the right of each interval for quick reading.

Usage

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

Arguments

x

An object returned by hcinfer().

parm

Optional coefficient names or integer positions. When supplied, only the selected coefficients are plotted. The selection follows the same rules as confint.hcinfer() and tests.hcinfer().

...

Unused. Passing named arguments raises an error.

Value

A ggplot2::ggplot() object.

See Also

hcinfer(), confint.hcinfer(), tests.hcinfer()

Examples

schools <- PublicSchools |>
  dplyr::mutate(
    income_scaled = income / 10000,
    income_scaled_sq = income_scaled^2
  )
fit <- lm(expenditure ~ income_scaled + income_scaled_sq, data = schools)
result <- hcinfer(fit)
plot(result)
plot(result, parm = "income_scaled_sq")

Plot HC adjustment factors against leverages

Description

Plots the HC adjustment factors g_t against the leverage values h_t stored in a vcov_hc() object. Points with h_t > 3p/n are highlighted because this threshold is commonly used to flag high-leverage observations in the empirical examples from the HCbeta paper.

Usage

## S3 method for class 'hcinfer_vcov'
plot(x, label_top = 3, ...)

Arguments

x

An object returned by vcov_hc().

label_top

A nonnegative whole number. The observations with the largest adjustment factors are labeled. Use 0 to suppress labels.

...

Unused. Passing named arguments raises an error.

Value

A ggplot2::ggplot() object.

See Also

vcov_hc(), hcinfer(), plot.hcinfer()

Examples

schools <- PublicSchools |>
  dplyr::mutate(
    income_scaled = income / 10000,
    income_scaled_sq = income_scaled^2
  )
fit <- lm(expenditure ~ income_scaled + income_scaled_sq, data = schools)

cov <- vcov_hc(fit, type = "hcbeta")
plot(cov)
plot(vcov_hc(fit, type = "hc4"), label_top = 2)

Print hcinfer objects

Description

Prints a compact overview of a heteroskedasticity-consistent inference object. Emoji markers are used when the current locale supports UTF-8 and getOption("hcinfer.use_emoji", TRUE) is true.

Usage

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

Arguments

x

An object returned by hcinfer().

...

Unused.

Value

The input object, invisibly.

Print hcinfer covariance objects

Description

Prints a compact overview of a heteroskedasticity-consistent covariance object. Emoji markers are used when the current locale supports UTF-8 and getOption("hcinfer.use_emoji", TRUE) is true.

Usage

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

Arguments

x

An object returned by vcov_hc().

...

Unused.

Value

The input object, invisibly.

Summarize heteroskedasticity-consistent inference

Description

Builds a detailed summary for an hcinfer() result. The summary includes model metadata, HC method information, leverage diagnostics, robust weight diagnostics, and coefficient-by-coefficient normal Wald tests with p-values and confidence intervals. The print method adds formal test decisions to improve interpretation while preserving the numeric components of the object.

Usage

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

Arguments

object

An object returned by hcinfer().

...

Unused.

Value

An object of class summary_hcinfer.

Summarize heteroskedasticity-consistent covariance objects

Description

Builds a detailed summary for an object returned by vcov_hc().

Usage

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

Arguments

object

An object returned by vcov_hc().

...

Unused.

Value

An object of class summary_hcinfer_vcov.

Extract coefficient test results

Description

Extracts the normal Wald test results from an hcinfer() object. If the requested significance level differs from the one used to create the object, only the reject column is recomputed. The test statistics and p-values are not affected by alpha and are never recomputed.

Usage

tests(object, ...)

## S3 method for class 'hcinfer'
tests(object, parm, alpha = object$alpha, ...)

Arguments

object

An object returned by hcinfer().

...

Unused. Passing named arguments raises an error.

parm

Optional coefficient names or integer positions to select a subset of coefficients. When omitted, all coefficients are returned.

alpha

Significance level used to compute the reject column. Must be strictly between 0 and 1. Defaults to the level stored in object. Changing alpha updates only the reject column; all other columns remain identical to the stored values.

Details

For each coefficient, the stored test is

H_0: \beta_j = \beta_j^{(0)}

against a two-sided alternative. The test statistic is

z_j = \frac{\hat\beta_j - \beta_j^{(0)}} {\sqrt{[\widehat{\Psi}_{HC}]_{jj}}},

and the p-value is 2\,\Phi(-|z_j|), where \Phi is the standard normal distribution function. The null value \beta_j^{(0)} is the one stored in the object, set when hcinfer() was called.

To test against a different null value, rerun hcinfer() with the desired null argument.

Value

A tibble with one row per selected coefficient and the following columns:

term

Coefficient name.

estimate

OLS estimate \hat\beta_j.

null_value

Null hypothesis value \beta_j^{(0)}.

std_error

Robust standard error \sqrt{[\widehat{\Psi}_{HC}]_{jj}}.

z_value

Normal Wald statistic z_j.

p_value

Two-sided p-value 2\,\Phi(-|z_j|).

alpha

Significance level used for the reject column.

reject

Logical. TRUE when p_value < alpha.

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

Hinkley, D. V. (1977). Jackknifing in unbalanced situations. Technometrics, 19(3), 285-292. doi:10.1080/00401706.1977.10489550

Horn, S. D., Horn, R. A., and Duncan, D. B. (1975). Estimating heteroscedastic variances in linear models. Journal of the American Statistical Association, 70(350), 380-385. doi:10.1080/01621459.1975.10479877

MacKinnon, J. G. and White, H. (1985). Some heteroskedasticity-consistent covariance matrix estimators with improved finite sample properties. Journal of Econometrics, 29(3), 305-325. doi:10.1016/0304-4076(85)90158-7

Davidson, R. and MacKinnon, J. G. (1993). Estimation and Inference in Econometrics. Oxford University Press.

Cribari-Neto, F. (2004). Asymptotic inference under heteroskedasticity of unknown form. Computational Statistics and Data Analysis, 45(2), 215-233. doi:10.1016/S0167-9473(02)00366-3

Cribari-Neto, F. and da Silva, W. B. (2011). A new heteroskedasticity consistent covariance matrix estimator for the linear regression model. AStA Advances in Statistical Analysis, 95(2), 129-146. doi:10.1007/s10182-010-0141-2

Cribari-Neto, F., Souza, T. C., and Vasconcellos, K. L. P. (2007). Inference under heteroskedasticity and leveraged data. Communications in Statistics - Theory and Methods, 36(10), 1877-1888. doi:10.1080/03610920601126589

Li, S., Zhang, N., Zhang, X., and Wang, G. (2016). A new heteroskedasticity-consistent covariance matrix estimator and inference under heteroskedasticity. Journal of Statistical Computation and Simulation, 87(1), 198-210. doi:10.1080/00949655.2016.1198906

See Also

hcinfer(), confint.hcinfer()

Examples

schools <- PublicSchools |>
  dplyr::mutate(
    income_scaled = income / 10000,
    income_scaled_sq = income_scaled^2
  )
fit <- lm(expenditure ~ income_scaled + income_scaled_sq, data = schools)
result <- hcinfer(fit)

tests(result)
tests(result, parm = "income_scaled_sq")
tests(result, alpha = 0.10)

Extract robust covariance matrices

Description

Extracts the heteroskedasticity-consistent covariance matrix stored in an hcinfer object. The matrix is returned directly and is not recomputed.

Usage

## S3 method for class 'hcinfer'
vcov(object, ...)

## S3 method for class 'hcinfer_vcov'
vcov(object, ...)

Arguments

object

An object returned by hcinfer() or vcov_hc().

...

Unused.

Value

A numeric covariance matrix.

Heteroskedasticity-consistent covariance estimator

Description

Computes a heteroskedasticity-consistent covariance matrix estimator for an ordinary least squares model fitted with stats::lm(). The function returns a rich S3 object that stores the covariance matrix, HC weights, leverage values, method parameters, and model metadata.

Usage

vcov_hc(object, type = "hcbeta", ...)

Arguments

object

An ordinary least squares model fitted by stats::lm().

type

A character string specifying the HC estimator. The default is "hcbeta".

...

Method-specific constants. Unknown names are rejected. See Details for the accepted names, defaults, and parameter domains.

Details

For a linear model with design matrix X, OLS residuals \hat e_t, and HC weights g_t, the estimator is

\widehat{\Psi}_{HC} = (X'X)^{-1} X' \widehat{\Omega} X (X'X)^{-1},

where \widehat{\Omega} = diag(\hat e_t^2 g_t). The supported estimators are "hc0", "hc1", "hc2", "hc3", "hc4", "hc4m", "hc5", "hc5m", and "hcbeta".

Additional arguments in ... are method-specific. The defaults are:

For "hc5" and "hc5m", k, k1, k2, and k3 must be nonnegative, while gamma1 and gamma2 must be positive. For "hcbeta", c1 must be nonnegative, c2 must be positive, and lower and upper must lie in ⁠(0, 1)⁠ with lower < upper. The HCbeta truncation is w_t = max(lower, min(1 - h_t, upper)).

Value

An object of class hcinfer_vcov. The covariance matrix is stored in object$vcov and is returned directly by vcov().

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

Hinkley, D. V. (1977). Jackknifing in unbalanced situations. Technometrics, 19(3), 285-292. doi:10.1080/00401706.1977.10489550

Horn, S. D., Horn, R. A., and Duncan, D. B. (1975). Estimating heteroscedastic variances in linear models. Journal of the American Statistical Association, 70(350), 380-385. doi:10.1080/01621459.1975.10479877

MacKinnon, J. G. and White, H. (1985). Some heteroskedasticity-consistent covariance matrix estimators with improved finite sample properties. Journal of Econometrics, 29(3), 305-325. doi:10.1016/0304-4076(85)90158-7

Davidson, R. and MacKinnon, J. G. (1993). Estimation and Inference in Econometrics. Oxford University Press.

Cribari-Neto, F. (2004). Asymptotic inference under heteroskedasticity of unknown form. Computational Statistics and Data Analysis, 45(2), 215-233. doi:10.1016/S0167-9473(02)00366-3

Cribari-Neto, F. and da Silva, W. B. (2011). A new heteroskedasticity consistent covariance matrix estimator for the linear regression model. AStA Advances in Statistical Analysis, 95(2), 129-146. doi:10.1007/s10182-010-0141-2

Cribari-Neto, F., Souza, T. C., and Vasconcellos, K. L. P. (2007). Inference under heteroskedasticity and leveraged data. Communications in Statistics - Theory and Methods, 36(10), 1877-1888. doi:10.1080/03610920601126589

Li, S., Zhang, N., Zhang, X., and Wang, G. (2016). A new heteroskedasticity-consistent covariance matrix estimator and inference under heteroskedasticity. Journal of Statistical Computation and Simulation, 87(1), 198-210. doi:10.1080/00949655.2016.1198906

Examples

schools <- PublicSchools |>
  dplyr::mutate(
    income_scaled = income / 10000,
    income_scaled_sq = income_scaled^2
  )
fit <- lm(expenditure ~ income_scaled + income_scaled_sq, data = schools)
cov <- vcov_hc(fit, type = "hcbeta")
cov
vcov(cov)
plot(cov)

vcov_hc(fit, type = "hcbeta", c1 = 7, c2 = 0.75, lower = 0.01, upper = 0.99)
vcov_hc(fit, type = "hc5", k = 0.7)
vcov_hc(fit, type = "hc5m", k = 0.7, k1 = 1, k2 = 0, k3 = 1)