lessR (version 2.2)

hst: Histogram with Color

Description

Accessing 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. Bins can be selected several different ways besides the default, including specifying just the bin width. 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.

If the provided object for which to calculate the histogram is a data frame, then a histogram is calculated for each numeric variable in the data frame and the results written to a pdf file in the current working directory. The name of this file and its path are specified in the output.

Usage

hst(x=NULL, dframe=mydata, ncut=4, ...)
## S3 method for class 'data.frame':
hst(x, ncut, \ldots) 
## S3 method for class 'default':
hst(x, col.bars="lightsteelblue", col.border="black",
         col.bg="ghostwhite", col.grid="grey90", over.grid=FALSE,
         breaks="Sturges", bin.start=NULL, bin.width=NULL,
         prop=FALSE, cumul=c("off", "on", "both"), mag.axis=.85,
         col.reg="snow2", digits.d=NULL, xlab=NULL, ylab=NULL, main=NULL, ...)
color.hist(...)

Arguments

x

Variable for which to construct the histogram. Can be a data frame. If not specified with dframe, that is, no variable specified, then the data frame mydata is assumed.

dframe

Optional data frame that contains the variable of interest, default is mydata.

ncut

When analyzing all the variables in a data frame, specifies the largest number of unique values of variable of a numeric data type for which the variable will be anlayzed as a categorical. Set to 0 to turn off.

col.bars

Color of the histogram's bars.

col.border

Color of the border of the bars.

col.bg

Color of the plot background.

col.grid

Color of the grid lines.

over.grid

If TRUE, plot the grid lines over the histogram.

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

bin.start

Optional specified starting value of the bins.

bin.width

Optional specified bin width, which can be specified with or without a bin.start value.

prop

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

mag.axis

Scale magnification factor, which by defaults displays the axis values to be smaller than the axis labels. Provides the functionality of, and can be replaced by, the standard R cex.axis.

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. Defaults to variable name.

ylab

Label for y-axis. Defaults to Frequency or Proportion.

digits.d

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

Details

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

If the variable is in a data frame, the input data frame has the assumed name of mydata. If this data frame is named something different, then specify the name with the dframe option. Regardless of its name, the data frame need not be attached to reference the variable directly by its name, that is, no need to invoke the mydata$name notation. If no variable is specified, then all numeric variables in the entire data frame are analyzed and the results written to a pdf file.

A somewhat common 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, hst 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. Moreover, the entire range of bins need not be specified to customize the bins. Instead, just a bin width need be specified, bin.width, and/or a value that begins the first bin, bin.start. If a starting value is specified without a bin width, the default Sturges method provides the bin width.

The freq option from the the standard R hist function has no effect as it is always set to FALSE in each internal call to hist. To plot densities, which correspond to setting freq to FALSE, use the dens function in this package.

A labels data frame named mylabels, obtained from the rad function, can list the label for some or all of the variables in the data frame that contains the data for the analysis. If this labels data frame exists, then the corresponding variable label is listed as the title of the resulting plot, unless a specific label is listed with the main option. The varible label is also listed in the text output, next to the variable name.

See Also

hist, plot, par.

Examples

# generate 100 random normal data values with three decimal digits
y <- round(rnorm(100),3)


# --------------------
# different histograms
# --------------------

# histogram with all defaults
hst(y)
# compare to standard R function hist
hist(y)

# histogram with specified bin width
# can also use bin.start
hst(y, bin.width=.25)

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

# histogram with bins calculated with the Scott method and values displayed
hst(y, breaks="Scott", labels=TRUE)

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

# histogram with specified colors, overriding defaults
# col.bg and col.grid are defined in histogram
# all other parameters are defined in hist, par and plot functions
hst(y, col.bars="darkblue", col.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,
  xlab="My Favorite Variable")


# ---------------------
# cumulative histograms
# ---------------------

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

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


# -------------------------------------------------
# histograms for data frames and multiple variables
# -------------------------------------------------

# create data frame, mydata, to mimic reading data with rad function
# mydata contains both numeric and non-numeric data
mydata <- data.frame(rnorm(100), rnorm(100), rnorm(100), rep(c("A","B"),50))
names(mydata) <- c("X","Y","Z","C")
rm(X); rm(Y); rm(Z); rm(C);

# although data not attached, access the variable directly by its name
hst(X)

# histograms for all numeric variables in data frame called mydata
#  except for numeric variables with unique values < ncut
# mydata is the default name, so does not need to be specified with dframe
hst()

# variable of interest is in a data frame which is not the default mydata
# access the breaks variable in the R provided warpbreaks data set
# although data not attached, access the variable directly by its name
data(warpbreaks)
hst(breaks, dframe=warpbreaks)
hst()

# histograms for all numeric variables in data frame called mydata
#  with specified options
hst(col.bars="palegreen1", col.bg="ivory", labels=TRUE)

# Use the subset function to specify a variable list
# histograms for all specified numeric variables
mysub <- subset(mydata, select=c(X,Y))
hst(dframe=mysub)