hist.eba {ExtremeBounds}

Histograms for Extreme Bounds Analysis

Description

hist.eba is used to generate a set of histograms that present the results of extreme bounds analysis graphically. Each histogram illustrates the distribution of regression coefficients across the models estimated in the course of EBA. In addition, function hist.eba can overlay each histogram with lines that indicate the value of the regression coefficient assumed under the null hypothesis (argument mu.show), as well as with curves that indicate the distribution's kernel density (argument density.show) and a normally distributed approximation (argument normal.show). Additional formatting options are available.

Usage

## S3 method for class 'eba'
hist(x, variables = NULL, col = "gray", freq = FALSE, main = NULL,
     mu.show = TRUE, mu.col = "red", mu.lwd = 2, mu.visible = TRUE,
     density.show = TRUE, density.col = "blue", density.lwd = 2, density.args = NULL, 
     normal.show = FALSE, normal.col = "darkgreen", normal.lwd = 2, 
     normal.weighted = FALSE, xlim = NULL, ylim = NULL, ...) 

Arguments

x

an object of class "eba", typically generated by the eba function.

variables

a character vector that specifies the variables for which histograms are requested. If NULL, histograms for all variables will be produced.

col

a color to be used to fill the histogram bars. Default is "gray".

freq

logical; if TRUE, the histogram graphic is a representation of frequencies, the counts component of the result; if FALSE, probability densities, component density, are plotted (so that the histogram has a total area of one). Defaults to TRUE if and only if breaks are equidistant (and probability is not specified).

main

a named character vector that specifies the histogram title labels for the requested variables. The name of the vector component specifies the variable, while the content of the component itself contains the title label. If the vector's components are not named, variables are labelled in the order that they appear in the argument variables.

mu.show

logical; if TRUE (default), a vertical line for each variable's regression coefficient value assumed under the null hypothesis (specified by the mu argument of the eba function, with a default of 0) will be drawn over the histograms.

mu.col

a color to be used to draw the vertical line at mu. Default is "red".

mu.lwd

the line width for vertical line at mu. Default is 2.

mu.visible

logical; if TRUE (default), make sure that the histograms' horizontal axes are scaled so that the vertical line at mu is always visible.

density.show

logical; if TRUE, a kernel density curve for the regression coefficients' distribution will be drawn over the histograms. The kernel densities are calculated using the standard density function. Additional arguments can be passed on to the density function via the density.args argument.

density.col

a color to be used to draw the kernel density curve. Default is "blue".

density.lwd

the line width for the kernel density curve. Default is 2.

density.args

a list of additional arguments that will be passed on to the kernel density function.

normal.show

logical; if TRUE, a density curve for the normal distribution function will be drawn over the histograms. For each variable, the distribution's mean and standard error will be the means and standard errors of the corresponding regression coefficients.

normal.col

a color to be used to draw the normal distribution density curve. Default is "darkgreen".

normal.lwd

the line width for the normal distribution density curve. For more detail, see the documentation for lwd in par. Default is 2.

normal.weighted

logical; If TRUE, the normal distribution density shown by normal.show will use the weighted mean and standard error, with each regression model's weight specified by eba's argument weights. If FALSE (default), the unweighted mean and standard error will be used (i.e., each regression model receives equal weight).

xlim

the range of x values with sensible defaults.

ylim

the range of y values with sensible defaults.

...

additional arguments that will be passed on to the hist function that creates the histograms.

Value

hist.eba returns an object of class "hist.eba".

An object of class "hist.eba" is a list containing the following components:

call

the matched call

histograms

a list of objects of class histogram that store information about the histograms produced by hist.eba. The histograms are included in the order that was requested and are indexed by the variable name. See the documentation for the default hist method for more information.

Please cite as:

Hlavac, Marek (2016). ExtremeBounds: Extreme Bounds Analysis in R. Journal of Statistical Software, 72(9), 1-22. doi: 10.18637/jss.v072.i09.

Author(s)

Marek Hlavac < mhlavac at alumni.princeton.edu >
Research Fellow, Central European Labour Studies Institute (CELSI), Bratislava, Slovakia

See Also

density, eba, hist, print.eba

Examples

# perform Extreme Bounds Analysis

eba.results <- eba(formula = mpg ~ wt | hp + gear | cyl + disp + drat + qsec + vs + am + carb,
                   data = mtcars[1:10, ], k = 0:2)

# The same result can be achieved by running:
# eba.results <- eba(data = mtcars[1:10, ], y = "mpg", free = "wt",
#                    doubtful = c("cyl","disp","hp","drat","qsec","vs","am","gear","carb"),
#                    focus = c("hp","gear"), k = 0:2)

# create histograms, keeping the default settings
hist(eba.results)

# re-create histograms with customized settings
hist(eba.results, variables = c("hp","gear"),
     main = c("hp" = "Gross horsepower", "gear" = "Number of forward gears"),
     mu.visible=FALSE, normal.show=TRUE, normal.lwd=1)