| Histogram {lessR} | R Documentation |
Histogram
Description
Abbreviation: hs
From the standard R function hist, the function plots a frequency histogram with default colors, including background color and grid lines 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 and/or the bin start. 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 a set of multiple variables is provided, including an entire data frame, then each numeric variable in that set of variables is analyzed, with the option to write the resulting histograms to separate pdf files. The related CountAll function does the same for all variables in the set of variables, histograms for continuous variables and bar charts for categorical variables. Specifying a by1 or by2 variable implements Trellis graphics.
When output is assigned into an object, such as h in h <- hs(Y), can assess the pieces of output for later analysis. A primary such analysis is knitr for dynamic report generation from a generated R markdown file according to the Rmd option in which interpretative R output is embedded in documents. See value below.
Usage
Histogram(
# ------------------------------------------
# Data from which to construct the histogram
x=NULL, data=d, filter=NULL,
stat_x=c("count", "proportion"),
# --------------------
# Trellis (facet) plot
by1=NULL, by2=NULL,
n_row=NULL, n_col=NULL, aspect="fill",
# -----------------------------------------------------------------
# Analogy of physical Marks on paper that create the bars and labels
theme=getOption("theme"),
fill=getOption("bar_fill_cont"),
color=getOption("bar_color_cont"),
transparency=getOption("trans_bar_fill"),
values=FALSE,
# ---------------------------------------
# Form of the histogram
# ---------------------------------------
# Binning the continuous variable x
bin_start=NULL, bin_width=NULL, bin_end=NULL, breaks="Sturges",
# Cumulative histogram
cumulate=c("off", "on", "both"), reg="snow2",
# Density (smooth curve) plot
density=FALSE, show_histogram=TRUE,
bandwidth=NULL, type=c("general", "normal", "both"),
fill_general=NULL, fill_normal=NULL, fill_hist=getOption("se_fill"),
color_general="gray20", color_normal="gray20",
x.pt=NULL, y_axis=FALSE,
rug=FALSE, color_rug="black", size_rug=0.5,
# -----------------------------------------------------------------
# Labels for axes, values, and legend if x and by variables, margins
xlab=NULL, ylab=NULL, main=NULL, sub=NULL,
lab_adjust=c(0,0), margin_adjust=c(0,0,0,0),
rotate_x=getOption("rotate_x"), rotate_y=getOption("rotate_y"),
offset=getOption("offset"),
scale_x=NULL, scale_y=NULL,
# ----------------------------------------------------------------------
# Draw one or more objects, text, or geometric figures, on the histogram
add=NULL, x1=NULL, y1=NULL, x2=NULL, y2=NULL,
# ---------------------------------------
# Output: turn off, chart to PDF file, decimal digits, markdown file
quiet=getOption("quiet"), do_plot=TRUE,
pdf_file=NULL, width=6.5, height=6,
digits_d=NULL,
Rmd=NULL,
# --------------------------------------
# Deprecated, removed in future versions
n_cat=getOption("n_cat"), rows=NULL,
# ---------------------------------
# Miscellaneous
eval_df=NULL, fun_call=NULL, ...)
hs(...)
Arguments
x |
Variable(s) to analyze. Can be a single numerical variable,
either within a data frame or as a vector in the users workspace,
or multiple variables in a data frame such as designated with the
|
data |
Optional data frame that contains the variable(s) of interest,
default is |
filter |
A logical expression that specifies a subset of rows of the data frame to analyze. |
stat_x |
Bin and transform values of variable |
by1 |
A categorical variable called a conditioning variable that
activates Trellis graphics, from the lattice package, to provide
a separate scatterplot (panel) of numeric primary variables |
by2 |
A second conditioning variable to generate Trellis
plots jointly conditioned on both the |
n_row |
Optional specification for the number of rows in the layout
of a multi-panel display with Trellis graphics. Need not specify
|
n_col |
Optional specification for the number of columns in the
layout a multi-panel display with
Trellis graphics. Need not specify |
aspect |
Lattice parameter for the aspect ratio of the panels,
defined as height divided by width.
The default value is |
theme |
Color theme for this analysis. Make persistent across analyses
with |
fill |
Fill color of the bars.
Can explicitly choose |
color |
Border color of the bars, can be a vector
to customize the color for each bar. Default is
|
transparency |
Transparency factor of the area of each slice.
Default is
|
values |
Replaces standard R |
bin_start |
Optional specified starting value of the bins. |
bin_width |
Optional specified bin width, which can be specified with or
without a |
bin_end |
Optional specified value that is within the last bin, so the actual endpoint of the last bin may be larger than the specified value. |
breaks |
The method for calculating the bins, or an explicit specification
of the bins, such as with the standard R |
cumulate |
Specify a cumulative histogram. The value of |
reg |
The color of the superimposed, regular histogram when
|
density |
If |
show_histogram |
When |
bandwidth |
Bandwidth of kernel density estimation, which determines the smoothness of the resulting density curve, larger values yield more smooth curves. Initial value is "nrd0", but unless specified, may be automatically iterated upward to create a smoother curve. |
type |
Type of density curve plotted. By default, the general density is plotted, though can request the normal density and both densities. |
fill_general |
Fill color for the estimated general density curve, with a partially transparent light red as the default, and a light transparent gray for the gray theme. Supplied color names are automatically revised with moderate transparency, the same level as the default. |
fill_normal |
Fill color for the estimated normal curve, with a partially transparent blue as the default, and transparent for the gray theme. |
fill_hist |
Fill color for the histogram behind density curve, defaults to a light gray. |
color_general |
Color of the general density curve border. |
color_normal |
Color of the normal curve border. |
x.pt |
Value of the point on the x-axis for which to draw a unit interval
around illustrating the corresponding area under the general density curve.
Only applies when requesting |
y_axis |
Specifies if the y-axis, the density axis, should be included. |
rug |
If |
color_rug |
Color of the rug ticks. |
size_rug |
Line width of the rug ticks. |
xlab |
Label for x-axis_ Defaults to variable name unless variable labels
are present, the defaults to also include the corresponding variable
label. Can style with the lessR |
ylab |
Label for y-axis_ Defaults to Frequency or Proportion.
Can style with the lessR |
main |
Label for the title of the graph.
Can set size with |
sub |
Sub-title of graph, below xlab. Not yet implemented. |
lab_adjust |
Two-element vector – x-axis label, y-axis label – adjusts the position of the axis labels in approximate inches. + values move the labels away from plot edge. Not applicable to Trellis graphics. |
margin_adjust |
Four-element vector – top, right, bottom and left – adjusts the margins of the plotted figure in approximate inches. + values move the corresponding margin away from plot edge. Not applicable to Trellis graphics. |
rotate_x |
Degrees that the |
rotate_y |
Degrees that the |
offset |
The amount of spacing between the axis values and the axis_ Default
is 0.5. Larger values such as 1.0 are used to create space for the label when
longer axis value names are rotated.
Can set persistently with the lessR |
scale_x |
If specified, a vector of three values that define the numerical values of the x-axis: starting, ending and number of intervals, within the bounds of plot region. |
scale_y |
Applies to the y-axis_ See |
add |
Draw one or more objects, text or a geometric figures,
on the plot.
Possible values are any text to be written, the first argument, which is
|
x1 |
First x coordinate to be considered for each object. All coordinates vary from -1 to 1. |
y1 |
First y coordinate to be considered for each object. |
x2 |
Second x coordinate to be considered for each object.
Only used for |
y2 |
Second y coordinate to be considered for each object.
Only used for |
quiet |
If set to |
do_plot |
If |
pdf_file |
Indicate to direct pdf graphics to the specified name of the pdf file. |
width |
Width of the plot window in inches, defaults to 4.5. |
height |
Height of the plot window in inches, defaults to 4.5. |
digits_d |
Number of significant digits for each of the displayed summary statistics. |
Rmd |
File name for the file of R markdown to be written, if specified. The file type is .Rmd, which automatically opens in RStudio, but it is a simple text file that can be edited with any text editor, including RStudio. |
n_cat |
For the analysis of multiple variables, such as a data frame, specifies the largest number of unique values of variable of a numeric data type for which the variable will be analyzed as a categorical. Default is 0. [deprecated]: Best to convert a categorical integer variable to a factor. |
rows |
Deprecated old parameter name that is now called |
eval_df |
Determines if to check for existing data frame and
specified variables. By default is |
fun_call |
Function call. Used with |
... |
Other parameter values for graphics as defined processed
by |
Details
OVERVIEW
Results are based on the standard R hist function to calculate and plot a histogram, or a multi-panel display of histograms with Trellis graphics, plus the additional provided color capabilities, a relative frequency histogram, summary statistics and outlier analysis. The freq option from the standard R hist function has no effect as it is always set to FALSE in each internal call to hist. To plot densities, set the parameter density to TRUE.
VARIABLES and TRELLIS PLOTS
At a minimum there is one primary variable, x, which results in a single histogram. Trellis graphics, from Deepayan Sarkar's lattice package, may be implemented in which multiple panels are displayed according to the levels of one or two categorical variables, called conditioning variables. A variable specified with by1 is a conditioning variable that results in a Trellis plot, the histogram of x produced at each level of the by1 variable. Inclusion of a second conditioning variable, by2, results in a separate histogram for each combination of cross-classified values of both by1 and by2.
DATA
The data may either be a vector from the global environment, the user's workspace, as illustrated in the examples below, or one or more variable's in a data frame, or a complete data frame. The default input data frame is d. Can specify the source data frame name with the data option. If multiple variables are specified, only the numerical variables in the list of variables are analyzed. The variables in the data frame are referenced directly by their names, that is, no need to invoke the standard R mechanisms of the d$name notation, the with function or the attach function. If the name of the vector in the global environment and of a variable in the input data frame are the same, the vector is analyzed.
To obtain a histogram of each numerical variable in the d data frame, use Histogram(). Or, for a data frame with a different name, insert the name between the parentheses. To analyze a subset of the variables in a data frame, specify the list with either a : or the c function, such as m01:m03 or c(m01,m02,m03).
The rows parameter subsets rows (cases) of the input data frame according to a logical expression. Use the standard R operators for logical statements as described in Logic such as & for and, | for or and ! for not, and use the standard R relational operators as described in Comparison such as == for logical equality != for not equals, and > for greater than. See the Examples.
COLORS
Individual colors in the plot can be manipulated with options such as color_bars for the color of the histogram bars. A color theme for all the colors can be chosen for a specific plot with the colors option with the lessR function style. The default color theme is lightbronze, but a gray scale is available with "gray", and other themes are available as explained in style, such as "red" and "green". Use the option style(sub_theme="black") for a black background and partial transparency of plotted colors.
For the color options, such as fill, the value of "off" is the same as "transparent".
Set fill to a single color or a color range, of which there are many possibilities. For "hues" colors of the same chroma and luminance set fill to multiple colors all with the same saturation and brightness. Also available are the pre-specified R color schemes "rainbow", "terrain", and "heat". Can also provide pre-defined color ranges "blues", "reds" and "greens", or generate custom colors, such as from the lessR function getColors.
VARIABLE LABELS
If variable labels exist, then the corresponding variable label is by default listed as the label for the horizontal axis and on the text output. For more information, see Read.
ONLY VARIABLES ARE REFERENCED
The referenced variable in a lessR function can only be a variable name (or list of variable names). This referenced variable must exist in either the referenced data frame, such as the default d, or in the user's workspace, more formally called the global environment. That is, expressions cannot be directly evaluated. For example:
> Histogram(rnorm(50)) # does NOT work
Instead, do the following:
> Y <- rnorm(50) # create vector Y in user workspace
> Histogram(Y) # directly reference Y
ERROR DETECTION
A somewhat relatively 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, Histogram 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.
PDF OUTPUT
To obtain pdf output, use the pdf_file option, perhaps with the optional width and height options. These files are written to the default working directory, which can be explicitly specified with the R setwd function.
Value
The output can optionally be saved into an R object, otherwise it simply appears in the console. Two different types of components are provided: the pieces of readable output, and a variety of statistics. The readable output are character strings such as tables amenable for display. The statistics are numerical values amenable for further analysis. The motivation of these types of output is to facilitate R markdown documents, as the name of each piece, preceded by the name of the saved object and a $, can be inserted into the R~Markdown document (see examples), interspersed with explanation and interpretation.
READABLE OUTPUT
out_suggest: Suggestions for other similar analyses
out_summary: Summary statistics
out_freq: Frequency distribution
out_outliers: Outlier analysis
STATISTICS
bin_width: Bin width
n_bins: Number of bins
breaks: Breaks of the bins
mids: Bin midpoints
counts: Bin counts
prop: Bin proportion
cumulate: Bin cumulative counts
cprop: Bin cumulative proportion
Author(s)
David W. Gerbing (Portland State University; gerbing@pdx.edu)
References
Gerbing, D. W. (2023). R Data Analysis without Programming: Explanation and Interpretation, 2nd edition, Chapter 5, NY: Routledge.
Gerbing, D. W. (2020). R Visualizations: Derive Meaning from Data, Chapter 4, NY: CRC Press.
Gerbing, D. W. (2021). Enhancement of the Command-Line Environment for use in the Introductory Statistics Course and Beyond, Journal of Statistics and Data Science Education, 29(3), 251-266, https://www.tandfonline.com/doi/abs/10.1080/26939169.2021.1999871.
Sarkar, Deepayan (2008) Lattice: Multivariate Data Visualization with R, Springer. http://lmdvr.r-forge.r-project.org/
See Also
getColors, hist, plot, par, style.
Examples
# get the data
d <- rd("Employee")
# make sure default style is active
style()
# --------------------
# different histograms
# --------------------
# histogram with all defaults
Histogram(Salary)
# short form
#hs(Salary)
# output saved for later analysis into object h
h <- hs(Salary)
# view full text output
h
# view just the outlier analysis
h$out_outliers
# list the names of all the components
names(h)
# histogram with no borders for the bars
Histogram(Salary, color="off")
# save the histogram to a pdf file
#Histogram(Salary, pdf=TRUE)
# just males employed more than 5 years
Histogram(Salary, rows=(Gender=="M" & Years > 5))
# histogram with red bars, black background, and black border
style(panel_fill="black", fill="red", panel_color="black")
Histogram(Salary)
# or use a lessR pre-defined sequential color palette
# with some transparency
Histogram(Salary, fill="rusts", color="brown", transparency=.1)
# histogram with purple color theme, translucent gold bars
style("purple", sub_theme="black")
Histogram(Salary)
# back to default color theme
style()
# histogram with specified bin width
# can also use bin_start
Histogram(Salary, bin_width=12000)
# histogram with rotated axis values, offset more from axis
# suppress text output
style(rotate_x=45, offset=1)
Histogram(Salary, quiet=TRUE)
style()
# histogram with specified bins and grid lines displayed over the histogram
Histogram(Salary, breaks=seq(0,150000,20000), xlab="My Variable")
# histogram with bins calculated with the Scott method and values displayed
Histogram(Salary, breaks="Scott", values=TRUE, quiet=TRUE)
# histogram with the number of suggested bins, with proportions
Histogram(Salary, breaks=15, stat_x="proportion")
# histogram with non-default values for x- and y-axes
d[2,4] <- 45000
Histogram(Salary, scale_x=c(30000,130000,5), scale_y=c(0,9.5,5))
# ----------------
# Trellis graphics
# ----------------
Histogram(Salary, by1=Dept)
# ---------------------
# cumulative histograms
# ---------------------
# cumulative histogram with superimposed regular histogram, all defaults
Histogram(Salary, cumulate="both")
# cumulative histogram plus regular histogram
Histogram(Salary, cumulate="both", reg="mistyrose")
# -------------
# density plots
# -------------
# default density plot
Histogram(Salary, density=TRUE)
# normal curve and general density curves superimposed over histogram
# all defaults
Histogram(Salary, density=TRUE, type="both")
# display only the general estimated density
# so do not display the estimated normal curve
# specify the bandwidth for the general density curve,
# use the standard bandwidth option for the density function
Histogram(Salary, density=TRUE, bandwidth=8000)
# display only the general estimated density and a corresponding
# interval of unit width around x.pt
Histogram(Salary, density=TRUE, x.pt=40000)
# densities for all specified numeric variables in a list of variables
# e.g., use the combine or c function to specify a list of variables
Histogram(c(Years,Salary), density=TRUE)
# -------------------------------------------------
# histograms for data frames and multiple variables
# -------------------------------------------------
# create data frame, d, to mimic reading data with Read function
# d contains both numeric and non-numeric data
d <- data.frame(rnorm(50), rnorm(50), rnorm(50), rep(c("A","B"),25))
names(d) <- c("X","Y","Z","C")
# although data not attached, access the variable directly by its name
Histogram(X)
# histograms for all numeric variables in data frame called d
# except for numeric variables with unique values < n_cat
# d is the default name, so does not need to be specified with data
Histogram()
# histogram with specified options, including red axis labels
style(fill="palegreen1", panel_fill="ivory", axis_color="red")
Histogram(values=TRUE)
style() # reset
# histograms for all specified numeric variables
# use the combine or c function to specify a list of variables
Histogram(c(X,Y))
# -----------
# annotations
# -----------
d <- rd("Employee")
# Place a message in the top-right of the graph
# Use \n to indicate a new line
hs(Salary, add="Salaries\nin our Company", x1=100000, y1=7)
# Use style to change some parameter values
style(add_trans=.8, add_fill="gold", add_color="gold4",
add_lwd=0.5, add_cex=1.1)
# Add a rectangle around the message centered at <100000,7>
hs(Salary, add=c("rect", "Salaries\nin our Company"),
x1=c(82000, 100000), y1=c(7.7, 7), x2=118000, y2=6.2)