Learn R Programming

lessR (version 3.5.5)

BarChart: Bar Chart for One or Two Variables

Description

Abbreviation: bc Plots a bar chart, such as for counts, with default colors for one or two variables, including background color and grid lines, from a variety of different types of data. For two variables a legend is provided. Also displays the frequency table for one or two variables, Cramer's V association, and the corresponding chi-square inferential analysis. For two variables, the frequencies include the joint and marginal frequencies. Unlike the standard R function, barplot, the variable(s) can be entered directly into the function call without first converting to a table. If the provided object to analyze is a set of multiple variables, including an entire data frame, then a bar chart is calculated for each non-numeric variable in the data frame and the results written to a pdf file in the current working directory. The name of each output pdf file that contains a bar chart and its path are specified in the output.

Usage

BarChart(x=NULL, by=NULL, data=mydata, n.cat=getOption("n.cat"), 

fill=getOption("fill.bar"), stroke=getOption("stroke.bar"), bg=getOption("bg"), grid=getOption("grid"), box=getOption("box"),

colors=c("rainbow", "terrain", "heat"),

horiz=FALSE, over.grid=FALSE, addtop=0.05, gap=NULL, proportion=FALSE, xlab=NULL, ylab=NULL, main=NULL, cex.axis=0.75, axes="gray30", value.labels=NULL, label.max=20, rotate.values=0, offset=0.5,

beside=FALSE, low.color=NULL, hi.color=NULL, count.labels=NULL,

legend.title=NULL, legend.loc="right.margin", legend.labels=NULL, legend.horiz=FALSE,

quiet=getOption("quiet"), width=4.5, height=4.5, pdf=FALSE, …)

bc(…)

Arguments

x
Variable(s) to analyze. Can be a single variable, either within a data frame or as a vector in the user's workspace, or multiple variables in a data frame such as designated with the c function, or an entire data frame. If not specified, then defaults to all non-numerical variables in the specified data frame, mydata by default.
by
For each level of the first variable, x, display the frequencies at each level of this second variable, y.
data
Optional data frame that contains the variables of interest, default is mydata.
n.cat
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 analyzed as a categorical. Default is 0.
fill
Specified bar colors. Remove with fill="off".
stroke
Color of the border of the bars. Black by default unless the background is dark. Remove with stroke="off".
bg
Color of the plot background. Remove with bg="off".
grid
Color of the grid lines. Remove with grid="off".
box
Color of border around the plot background, the box, that encloses the plot. Remove with box="off".
colors
Optional palettes that provide pre-defined color gradients, which include values of "heat", "rainbow" and "terrain".
horiz
By default bars are vertical, but can set to TRUE.
over.grid
If TRUE, plot the grid lines over the histogram.
addtop
When horiz=FALSE, in the same scale as the vertical axis, puts more space between the bars and the top of the plot area, usually to accommodate the legend when plotting two variables. Now a multiplicative factor instead of additive as previous to Version 3.4.5.
gap
Gap between bars. Provides the value of the space option from the standard R barplot function with a default of 0.2 unless two variables are plotted and beside=TRUE, in which case the default is c(.1,1).
proportion
Display proportions instead raw frequencies. For two-variable plots, display the column proportions, that is, a proportional stacked bar graph.
xlab
Label for x-axis, more generally the label for the values which could be on the vertical axis for a two variable plot if horiz=TRUE. Defaults to variable name.
ylab
Label for y-axis, more generally the frequency axis. Defaults to Frequency.
main
Title of graph.
cex.axis
Scale magnification factor, which by default displays the axis values to be smaller than the axis labels.
axes
Color of the font used to label the axis values.
value.labels
Labels for the value axis on the graph to override the existing data values, including factor levels. If the variable is a factor and value.labels is not specified (is NULL), then the value.labels are set to the factor levels with each space replaced by a new line character.
label.max
Maximum size of labels for the values of a variable. Not a literal maximum as preserving unique values may require a larger number of characters than specified.
rotate.values
Degrees that the axis values are rotated, usually to accommodate longer values, typically used in conjunction with offset.
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.
beside
For a two variable plot, set to TRUE for the levels of the first variable to be plotted as adjacent bars instead of stacked on each other.
low.color
Only when the variable is an ordered factor, sets the color for the lowest level of the factor in the resulting ordered progression of colors.
hi.color
Only when the variable is an ordered factor, sets the color for the highest level of the factor in the resulting ordered progression of colors.
count.labels
If the name of a variable, this signals that the primary variable x has values that are counts, already tabulated. The specified variable here contains the names of the levels of x.
legend.title
Title of the legend, which is usually set by default except when raw counts are entered as a matrix. Then a title must be specified to generate a legend.
legend.loc
When plotting two variables, location of the legend, with the default in the right margin. Additional options from standard R are "topleft", "top", "topright" and others as shown in the help for the legend function.
legend.labels
When plotting two variables, labels for the legend, which by default are the levels for the second or by variable.
legend.horiz
By default the legend is vertical, but can be changed to horizontal.
quiet
If set to TRUE, no text output. Can change system default with theme function.
width
Width of the plot window in inches, defaults to 4.5.
height
Height of the plot window in inches, defaults to 4.5.
pdf
If TRUE, the pdf file is to be redirected to a pdf file.
Other parameter values for graphics as defined by barplot, legend, and par including space for one variable only, las=2 for vertical axis labels, and cex.lab, col.main, col.lab, sub, col.sub, and col.ticks to specify the color of the tick marks.

Value

If the analysis is of a single categorical variable, a list is invisibly returned with two tables, the frequencies and the proportions, respectively named freq and prop. If two categorical variables are analyzed, then nothing is returned.

Details

OVERVIEW Plot a bar chart with default colors for one or two variables, presumably with a relatively small number of values for each variable. By default, colors are selected for the bars, background and grid lines, all of which can be customized. The basic computations of the chart are provided with the standard R functions barplot, chisq.test and, for two variables, legend. Horizontal bar charts, specified by horiz=TRUE, list the value labels horizontally and automatically extend the left margin to accommodate both the value labels and the variable label. The form of the entered data, the first variable x and optionally a second variable, y, is flexible. The data may be entered as factors, numeric values, characters, or a matrix. The data may be entered and the resulting frequencies computed, or the frequencies can be entered directly. The most natural type of data to enter, when entering the variables, is to enter factors. Plus, the bar colors for a second variable which is an ordered factor are also ordered in a corresponding progression. DATA The data may either be a vector from the global environment, the user's workspace, as illustrated in the examples below, or a variable in a data frame. The default input data frame is mydata. Specify a different data frame name with the data option. Regardless of its name, the variables in the data frame are referenced directly by their names, that is, no need to invoke the standard R mechanisms of the mydata$name notation, the with function or the attach function. If the name of vector in the global environment and of a variable in the input data frame are the same, the vector is analyzed. If two variables are specified, both variables should be in the data frame, or one of the variables is in the data frame and the other in the global environment. To obtain a bar chart of each numerical variable in the mydata data frame, invoke Bar chart(). 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 variable list with either a : or the c function, such as m01:m03 or c(m01,m02,m03). COLORS For a one variable plot, the color of the bars is set by the current color theme according to the function theme, which includes the default color theme dodgerblue. When two variables are plotted, a set of arbitrary colors represent the various levels of the second variable. Transparency effects are only incorporated for a one variable bar plot in a single color. There are two ways to override the default colors. 1. There are two pre-defined color palettes, each with 7 colors. Three more built-in R color palettes are also available by setting colors to one of "rainbow", "heat" and "terrain". The most vivid of all the palettes is "rainbow". 2. The desired colors can be explicitly specified with the color.bars option, which overrides any other bar color options. When plotting one variable, include one color in this color list, the color used for all of the bars. When plotting two variables, usually the list of colors includes the same number of elements as the number of levels for the second variable. As always with R, if the list includes more than once color, the c function must be used to generate the list, as in color.bars=c("coral3","seagreen3") for a second variable with two levels. When two variables are plotted, if there are fewer specified colors than the levels of the second variable, the remaining colors are selected from the remaining colors in the activated palette. For the color options, such as grid, the value of "off" is the same as "transparent". When plotting one ordered factor, or when plotting two variables, and the second variable is an ordered factor, then neither of the two standard color palettes are used. Instead, the resulting bar colors for each level of the ordered factor are also ordered in a progression of colors. The default progression is based on the first color of either the regular or gray color palettes, but this can be changed with the low.color and hi.color options, or individually specify the color of each bar with the color.bars option. A specified palette can, for example, be from light to dark of the same hue, or from a light color of one hue to a dark color of another hue. Each color value can be specified with a color name, or with a specification with the rgb function. See the examples below. The showColors function in this package provides, for each color: name, sample color swatch, and corresponding rgb specification. For a very small number of levels, such as two, it is may be desirable to specify the low and high values to not be closer to each other than the default values. LEGEND When two variables are plotted, a legend is produced, with values for each level of the second or by variable. By default, the location is placed in the right margin of the plot. This position can be changed with the legend.loc option, which, in addition to the lessR option of right.margin, accepts any valid value consistent with the standard R legend function, used to generate the legend. If the default right margin is retained, variable labels are also accommodated for the legend title. To conserve horizontal space, the variable label is listed in multiple lines if needed. The legend title is constructed by forming lines of maximum length of 12 characters, with multiple words per line if possible. Any single word in the label of more than 12 characters is abbreviated to 12 characters with the R abbreviate function. Also, any value labels are abbreviated to a maximum of 6 characters. If the legend is not in the right margin, sometimes bars from the graph may intrude into the legend. One response is to re-run the analysis with the legend in a new location. Another response is to invoke the addtop option to place more space between the top bar in the graph and the top of the graph. This option only applies for the default vertical bars. Also, the legend is displayed vertically by default, but can be changed to horizontal with the legend.horiz option. ENTER COUNTS DIRECTLY Instead of calculating the counts from the data, the counts can be entered directly. For two variables, enter the counts as a matrix and include the xlab option to label the horizontal axis, such as with the name of the variable. Also include the legend.title option to provide a legend. See the examples below. Or, include the already tabulated counts as the data which is read into R. If count.labels is not NULL, then it is presumed to be a valid variable name. As such, it indicates that the primary variable, x consists of values already tabulated, that is, counts, and is ready to be plotted directly. The value for count.labels specifies the label for each level of x. STATISTICS In addition to the barchart, descriptive and optional inferential statistics are also presented. First, the frequency table for one variable or the joint frequency table for two variables is displayed. Second, the corresponding Cramer's V and chi-square test are also displayed by default. VARIABLE LABELS If variable labels exist, then the corresponding variable label is listed as the label for the horizontal axis unless xlab is specified in the function call. If there are two variables to plot, the title of the resulting plot is based on the two variable labels, unless a specific title is listed with the main option. The variable label is also listed in the text output, next to the variable name. If the analysis is for two variables, then labels for both variables are included. 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. 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 mydata, or in the user's workspace, more formally called the global environment. That is, expressions cannot be directly evaluated. For example: > BarChart(cut(rnorm(50), breaks=seq(-5,5))) # does NOT work Instead, do the following:
    > Y <- cut(rnorm(50), breaks=seq(-5,5))   # create vector Y in user workspace
    > BarChart(Y)     # directly reference Y

References

Gerbing, D. W. (2013). R Data Analysis without Programming, Chapter 4, NY: Routledge.

See Also

barplot, table, legend.

Examples

Run this code
# ---------------------------------------------------------
# generate some data in data frame mydata for two variables 
# ---------------------------------------------------------

# Pain is an ordered factor, Gender is an unordered factor
# Place in data frame mydata to simulate reading with rad
Pain <- sample(c("None", "Some", "Much", "Massive"), size=25, replace=TRUE)
Pain <- factor(Pain, levels=c("None", "Some", "Much", "Massive"), ordered=TRUE)
Gender <- sample(c("Male", "Female"), size=25, replace=TRUE)
Gender <- factor(Gender)
mydata <- data.frame(Pain, Gender)
rm(Pain); rm(Gender)


# --------------------------------------------
# barchart from the data for a single variable
# --------------------------------------------

# for each level of Pain, display the frequencies
# Pain is an ordered factor, so the bar colors are ordered
BarChart(Pain)
# short name
bc(Pain)
# save and then display the frequencies for later analysis
myCount <- BarChart(Pain)
myCount
# rotate and offset the axis labels
BarChart(Pain, rotate.values=45, offset=1)
# compare to standard R bar plot, which requires mydata$ reference
barplot(table(mydata$Pain))

# Gender is unordered, so one color used for all the bars
BarChart(Gender)

# column proportions instead of frequencies
BarChart(Gender, proportion=TRUE)

# specify a unique bar color for each of the two bars
BarChart(Gender, fill=c("palegreen3","tan"))

# automatically provide horizontal value labels 
#   and adjust left margin as needed
BarChart(Pain, horiz=TRUE)

# manage size of horizontal value labels
myd <- Read("Cars93", format="lessR")
bc(Make, horiz=TRUE, label.max=4, las=1, data=myd)


# ----------------------------------------
# barchart from the data for two variables
# ----------------------------------------

# at each level of Pain, show the frequencies of the Gender levels
BarChart(Pain, by=Gender)

# at each level of Pain, show the row proportions of the Gender levels
#   i.e., proportional stacked bar graph
BarChart(Pain, by=Gender, proportion=TRUE)

# at each level of Gender, show the frequencies of the Pain levels
# Pain levels are ordered, so the corresponding colors are also ordered 
# color theme set to gray
theme(colors="gray")
BarChart(Gender, by=Pain)
theme(colors="sienna")

# specify an ordered blue palette of colors for the ordered levels of Pain
# only works when the variable is an ordered factor
# colors can be named or customized with rgb function
BarChart(Gender, by=Pain, low.color="azure", hi.color=rgb(100,110,200,max=255))

# display bars beside each other instead of stacked, Female and Male
# the levels of Pain are included within each respective bar
BarChart(Gender, by=Pain, beside=TRUE, legend.horiz=TRUE)

# horizontal bar chart of two variables, put legend on the top
BarChart(Gender, by=Pain, horiz=TRUE, legend.loc="top")

# many options, including those from par: axes, col.main, col.lab, cex.lab
# for more info on these graphic options, enter:  help(par)
BarChart(Pain, by=Gender, fill=c("coral3","seagreen3"), 
  legend.loc="topleft", legend.labels=c("Girls", "Boys"), 
  xlab="Pain Level", main="Gender for Different Pain Levels", 
  bg="wheat1", grid="wheat3", axes="wheat4", 
  col.main="wheat4", col.lab="wheat4", cex.lab=1.2)


# ---------------------------------------------
# multiple bar charts across multiple variables
# ---------------------------------------------

# bar charts for all non-numeric variables in the data frame called mydata
#   and all numeric variables with a small number of values, < n.cat
BarChart()



# ----------------------------
# can enter many types of data
# ----------------------------

# generate and enter integer data
X1 <- sample(1:4, size=100, replace=TRUE)
X2 <- sample(1:4, size=100, replace=TRUE)
BarChart(X1)
BarChart(X1, by=X2)

# generate and enter type double data
X1 <- sample(c(1,2,3,4), size=100, replace=TRUE)
X2 <- sample(c(1,2,3,4), size=100, replace=TRUE)
BarChart(X1)
BarChart(X1, by=X2)

# generate and enter character string data
# that is, without first converting to a factor
Travel <- sample(c("Bike", "Bus", "Car", "Motorcycle"), size=25, replace=TRUE)
BarChart(Travel, horiz=TRUE)


# ------------------------------
# bar chart directly from counts
# ------------------------------

# barchart of one variable with five levels
# enter counts as a vector with the combine function, c
# must supply the level names and variable name
Dept <- c(5,6,4,6,15)
names(Dept) <- c("ACCT", "ADMIN", "FINC", "MKTG", "SALE")
BarChart(Dept)

# counts are in the data table to be read directly
mydata <- read.csv(text="
Dept, Count
ACCT,5
ADMN,6
FINC,4
MKTG,6
SALE,15", header=TRUE)
# use count.labels to indicate the label for each corresponding count
BarChart(Count, count.labels=Dept)

# barchart of two variables
# two Quality levels, the rows
# three Supplier levels, the columns
# enter counts row by row, then form the table with rbind function
# must supply the level (value) names and the variable names
# chart presented as Row Variable, analyzed at each level of Column Variable
row1 <- c(19, 16, 23) 
row2 <- c(6, 6, 8) 
mytable <- rbind(row1, row2)
rownames(mytable) <- c("Pass", "Defective")
colnames(mytable) <- c("Acme Inc", "Nuts Inc", "Bolts Inc")
BarChart(mytable, xlab="Supplier", legend.title="Quality")

Run the code above in your browser using DataLab