lessR (version 1.5.2)

color.hist: Histogram with Color

Description

Using the standard R function hist, plots a frequency histogram with default colors, including background color and gridlines plus an option for a relative frequency and/or cumulative histogram, as well as summary statistics and a table that provides the bins, midpoints, counts, proportions, cumulative counts and cumulative proportions. Also provides improved error diagnostics and feedback for the user on how to correct the problem when the bins do not contain all of the specified data.

Usage

color.hist(x, col="lightsteelblue", border="black", col.bg="snow1",
         col.grid="grey90", breaks="Sturges", over.grid=FALSE,
         show.values=FALSE, prop=FALSE, cumul=c("off", "on", "both"), 
         col.reg="seashell2", digits=5, xlab=NULL, main=NULL, ...)

Arguments

x

Variable for which to construct the histogram.

col

Color of the histogram's bars.

border

Color of the border of the bars.

col.bg

Color of the plot background.

col.grid

Color of the grid lines.

breaks

The method for calculating the bins, or an explicit specification of the bins, such as with the standard R seq function or other options provided by the hist

over.grid

If true, plot the grid lines over the histogram.

show.values

If true, display the frequency of the bin at the top of the corresponding bar.

prop

Specify proportions or relative frequencies on the vertical axis. Default is FALSE.

cumul

Specify a cumulative histogram. The value of "on" displays the cumulative histogram, with default of "off". The value of "both" superimposes the regular histogram.

col.reg

The color of the superimposed, regular histogram when cumul="both".

xlab

Label for x-axis.

digits

Number of significant digits for each of the displayed summary statistics.

main

Title of graph.

...

Other parameter values for graphics as defined processed by hist and plot, including xlim, ylim, lwd and cex.la

Details

Results are based on the standard hist function for calculating and plotting a histogram, with the additional provided color capabilities and other options. However, a histogram with densities is not supported.

An error by beginning users of the base R hist function may encounter is to manually specify a sequence of bins with the seq function that does not fully span the range of specified data values. The result is a rather cryptic error message and program termination. Here, color.hist detects this problem before attempting to generate the histogram with hist, and then informs the user of the problem with a more detailed and explanatory error message.

The freq option from the traditional hist function has no effect as it is always off in each internal call to hist. To plot densities, which correspond to setting freq to FALSE, use the color.density function in this package.

See Also

hist, plot, par.

Examples

# generate 100 random normal data values
y <- rnorm(100)

# histogram with all defaults
color.hist(y)

# histogram with specified bins and grid lines displayed over the histogram
color.hist(y, breaks=seq(-5,5,.25), xlab="My Variable", over.grid=TRUE)

# histogram with bins calculated with the Scott method and values displayed
color.hist(y, breaks="Scott", show.values=TRUE)

# histogram with the number of suggested bins, with proportions
color.hist(y, breaks=25, prop=TRUE)

# histogram with specified colors, overriding defaults
# col.bg and col.grid are defined in color.hist
# all other parameters are defined in hist, par and plot functions
color.hist(y, col="darkblue", border="lightsteelblue4", col.bg="ivory",
  col.grid="darkgray", density=25, angle=-45, cex.lab=.8, cex.axis=.8,
  col.lab="sienna3", main="My Title", col.main="gray40", xlim=c(-5,5), lwd=2)

# cumulative histogram with superimposed regular histogram, all defaults
color.hist(y, cumul="both")

# cumulative histogram plus regular histogram
# present with proportions on vertical axis, override other defaults
color.hist(y, cumul="both", breaks=seq(-4,4,.25), prop=TRUE, 
  col.reg="mistyrose")