hetplot {skedastic}

Graphical Methods for Detecting Heteroskedasticity in a Linear Regression Model

Description

This function creates various two-dimensional scatter plots that can aid in detecting heteroskedasticity in a linear regression model.

Usage

hetplot(
  mainlm,
  horzvar = "index",
  vertvar = "res",
  vertfun = "identity",
  filetype = NA,
  values = FALSE,
  ...
)

Arguments

mainlm

Either an object of class "lm" (e.g., generated by lm), or a list of two objects: a response vector and a design matrix. The objects are assumed to be in that order, unless they are given the names "X" and "y" to distinguish them. The design matrix passed in a list must begin with a column of ones if an intercept is to be included in the linear model. The design matrix passed in a list should not contain factors, as all columns are treated 'as is'. For tests that use ordinary least squares residuals, one can also pass a vector of residuals in the list, which should either be the third object or be named "e".

horzvar

A character vector describing the variable(s) to plot on horizontal axes ("index" for the data index i, "fitted.values" for the OLS predicted values \hat{y}_i, "fitted.values2" for transformed OLS predicted values m_{ii}\hat{y}_i, and/or names of explanatory variable columns). "explanatory" passes all explanatory variable columns. "log_" concatenated with names of explanatory variable columns passes logs of those explanatory variables. "log_explanatory" passes logs of all explanatory variables. If more than one variable is specified, a separate plot is created for each.

vertvar

A character vector describing the variable to plot on the vertical axis ("res" for OLS residuals [the default], "res_blus" for BLUS residuals, "res_stand" for standardised OLS residuals: e_i/\sqrt{\hat{\omega}}, "res_constvar" for OLS residuals transformed to have constant variance: e_i/\sqrt{m_{ii}}, "res_stud" for studentised OLS residuals: e_i/(s\sqrt{m_{ii}}). If more than one value is specified, a separate plot is created for each.

vertfun

A character vector giving the name of a function to apply to the vertvar variable. Values that can be coerced to numeric such as "2" are taken to be powers to which vertvar should be set. If multiple values are specified, they are all applied to each element of vertvar. Common choices might be "identity" (the default), "abs" (absolute value), and "2" (squaring).

filetype

A character giving the type of image file to which the plot(s) should be written. Values can be "png", "bmp", "jpeg", or "tiff". Image files are written to a subdirectory called "hetplot" within the R session's temporary directory, which can be located using tempdir(). The files should be moved or copied to another location if they are needed after the R session is ended. Default filenames contain timestamps for uniqueness. If NA (the default), no image files are written, and in this case, if there are multiple plots, they are plotted on a single device using the "mfrow" graphical parameter. If many plots are requested at once, it is advisable to write them to image files.

values

A logical. Should the sequences corresponding to the horizontal and vertical variable(s) be returned in a list object?

...

Arguments to be passed to methods, such as graphical parameters (see par), parameters for plot, for graphics devices, and/or the omit argument for function blus, if BLUS residuals are being plotted. If it is desired to pass the type argument to a graphics device, use gtype = , since a type argument will be passed to plot.

Details

The variable plotted on the horizontal axis could be the original data indices, one of the explanatory variables, the OLS predicted (fitted) values, or any other numeric vector specified by the user. The variable plotted on the vertical axis is some function of the OLS residuals or transformed version thereof such as the BLUS residuals Theil (1968) or standardised or studentised residuals as discussed in Cook and Weisberg (1983). A separate plot is created for each (horzvar, vertvar, vertfun) combination.

Value

A list containing two data frames, one for vectors plotted on horizontal axes and one for vectors plotted on vertical axes.

References

Cook RD, Weisberg S (1983). “Diagnostics for Heteroscedasticity in Regression.” Biometrika, 70(1), 1–10.

Theil H (1968). “A Simplification of the BLUS Procedure for Analyzing Regression Disturbances.” Journal of the American Statistical Association, 63(321), 242–251.

See Also

plot.lm

Examples

mtcars_lm <- lm(mpg ~ wt + qsec + am, data = mtcars)
# Generates 2 x 2 matrix of plots in console
hetplot(mtcars_lm, horzvar = c("index", "fitted.values"),
vertvar = c("res_blus"), vertfun = c("2", "abs"), filetype = NA)

# Generates 84 png files in tempdir() folder
## Not run: hetplot(mainlm = mtcars_lm, horzvar = c("explanatory", "log_explanatory",
"fitted.values2"), vertvar = c("res", "res_stand", "res_stud",
"res_constvar"), vertfun = c("identity", "abs", "2"), filetype = "png")
## End(Not run)