Last chance! 50% off unlimited learning
Sale ends in
Abbreviation: bc
Plots a bar chart, one categorical variable, x and one numeric variable y, as well as an optional second categorical variable by with a provided legend. By default the numeric variable is the computed frequency of values in each category, with default colors for one or two variables, which can be replaced with custom color scales. The numeric variable can be entered as the y-variable, in which case it could be a non-integer variable. 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. Activate Trellis graphics by specifying a by1 variable. 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.
BarChart(x=NULL, y=NULL, by=NULL, data=mydata, rows=NULL,
n.cat=getOption("n.cat"), one.plot=NULL, by1=NULL, n.row=NULL, n.col=NULL, aspect="fill",
horiz=FALSE, beside=FALSE, gap=NULL,
proportion=FALSE, scale.y=NULL,
fill=getOption("bar.fill.discrete"),
color=getOption("bar.color.discrete"),
trans=getOption("trans.bar.fill"),
legend.title=NULL, legend.loc="right.margin",
legend.labels=NULL, legend.horiz=FALSE,
value.labels=NULL,
rotate.x=getOption("rotate.x"),
offset=getOption("offset"),
break.x=TRUE, sort=c("0", "-", "+"),
label.max=100, out.size=80,
values=getOption("values"),
values.color=getOption("values.color"),
values.cex=getOption("values.cex"),
values.digits=getOption("values.digits"),
values.pos=getOption("values.pos"),
values.cut=NULL,
xlab=NULL, ylab=NULL, main=NULL, sub=NULL,
lab.adj=c(0,0), margin.adj=c(0,0,0,0), addtop=0.05,
add=NULL, x1=NULL, y1=NULL, x2=NULL, y2=NULL,
eval.df=NULL, quiet=getOption("quiet"),
width=6.5, height=6, pdf=FALSE, …)
bc(…)
Variable(s) to analyze. Can be a single 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
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.
To manage large category values, unless break.x is FALSE,
any space in each category value is
converted to new line for the corresponding axis label in the plot.
To keep two (small) words on the same line, replace the space that
separates them with an underscore, which is converted to a blank
for the corresponding axis label.
Numeric variable for which the values are displayed on the vertical axis. If not specified, then its value is the frequency of each category or joint category, automatically tabulated.
A categorical variable to provide a bar chart for
each level of the numeric primary variables x and
y on the same plot, which applies to the panels of
a Trellis plot if by1 is specified.
Optional data frame that contains the variables of interest, default
is mydata. Can contain data from which frequencies are computed, or
can contain values to plot on the y-axis instead of counts.
A logical expression that specifies a subset of rows of the data frame to analyze.
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.
For bar charts of multiple x-variables, indicates
if a bar plot is produced for each x-variable, or all are combined
into a single plot, such as for items that all share common responses
such as survey data with a common Likert scale across variables.
Default is if variables share a common response scale
set to TRUE, otherwise FALSE.
A categorical variable called a conditioning variable that
activates Trellis graphics, from the lattice package, to provide
a separate bar chart (panel) of numeric primary variables x
and y for each level of the variable.
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 of a multi-panel display with
Trellis graphics. Need not specify n.row. If set to 1, then
the strip that labels each group locates to the left of each plot
instead of the top.
Lattice parameter for the aspect ratio of the panels in
a Trellis plot (multi-panel display), defined as height divided by
width. The default value is "fill" to have the panels
expand to occupy as much space as possible. Set to 1 for square panels.
Set to "xy" to specify a ratio calculated
to "bank" to 45 degrees, that is, with the line slope approximately
45 degrees.
By default the value is FALSE so bars are vertical,
unless one.plot is TRUE.
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.
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).
Display proportions instead raw frequencies. For two-variable plots, display the column proportions, that is, a proportional stacked bar graph.
If specified, a vector of three values that define the numerical values of the y-axis, the numerical axis, within the bounds of plot region: starting, ending and number of intervals.
Fill color of the bars, override the default with a vector
of colors: names, rgb, hex or hcl and other possibilities.
Can generate these colors with pre-defined qualitative, sequential and
divergent palettes generated by lessR getColors.
See the details and examples sections. Default is
bar.color.discrete from the lessR style function.
Border color of the bars, can be a vector
to customize the color for each bar. Default is
bar.color.discrete from the lessR style function.
Transparency factor of the area of each slice from 0, no
transparency to 1, full transparency. Default is
trans.bar.fill from the lessR style function.
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.
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.
When plotting two variables, labels for the legend, which by
default are the levels for the second or by variable.
By default the legend is vertical, but can be changed to horizontal.
For factors, default is the factor labels, and for
character variables, default is the character values.
Or, provide labels for the x-axis on the graph to override
these values. 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. If x and y-axes have the same scale,
they also apply to the y-axis. Control the plotted size
with axis.cex and axis.x.cex from the lessR
style function.
Degrees that the axis values for the category values
axis are rotated, usually to accommodate longer values,
typically used in conjunction with offset. When equal 90
the value labels are perpendicular to the x-axis and a different
algorithm places the labels so that offset is not needed.
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.
Replace spaces in the category values with a new line and replace underscores with a blank.
Sort the categories by their frequency for one variable and by
the column sums if a by variable. Not applicable to Trellis plots.
By default "0" for no sort, or sort descending "-" or
ascending "+", unless one.plot is TRUE, then is
set to "+".
To improve readability, the maximum size of the value labels before the labels are abbreviated for text output only. Not a literal maximum as preserving unique values may require a larger number of characters than specified.
To improve the readability of the frequency distribution of a single variable displayed at the console, the maximum number of characters on a line of output at the console for one variable before the frequency distribution is written vertically.
If not "off", adds the
numerical results to the plot according to the default "%",
"prop" or "input", that is, percentages,
proportions, or the value from which the bars are plotted,
such as tabulated counts if y is not specified,
or the value of y if the plotted values are provided. If
any other values parameter is specified.
Color of the plotted text. Could be a vector to specify a unique color for each value. If fewer colors are specified than the number of categories, the colors are recycled.
Character expansion factor, the size, of the plotted text, for which the default value is 0.95.
Number of decimal digits for which to display the values.
Default is 0, round to the nearest integer, for "%"
and 2 for "prop".
Position of the plotted text. Default is inside the bar,
or, if "out", as part of the label for each value
outside of the bar.
Threshold for displaying the value. If values.pos
equals "out", then default is 0.015 unless there is a
by variable or multiple x-variables on the same plot, then
default is 0.045.
Label for x-axis. If xlab is not specified, then
the label becomes
the name of the corresponding variable label if it exists, or, if not, the
variable name. If xy.ticks is FALSE, then no label is displayed.
If no y variable is specified, then xlab is set to Index unless
xlab has been specified.
Label for y-axis. If xlab is not specified, then
the label becomes
the name of the corresponding variable label if it exists, or, if not, the
variable name. If xy.ticks is FALSE, then no label displayed.
Label for the title of the graph.
Can set size with main.cex and color with main.color from the
lessR style function.
Sub-title of graph, below xlab.
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.
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.
In the same scale as the corresponding axis, puts more space between the bars and the top of the plot area, usually to accommodate the legend when plotting two variables or a display of the values on top of the bars.
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
"text", or, to indicate a figure,
"rect" (rectangle), "line", "arrow",
"v.line" (vertical line), and "h.line" (horizontal line).
The value "means" is short-hand for vertical and horizontal lines
at the respective means. Does not apply to Trellis graphics.
Customize with parameters such as add.fill and add.color
from the style function.
First x coordinate to be considered for each object. All coordinates vary from -1 to 1.
First y coordinate to be considered for each object.
Second x coordinate to be considered for each object.
Only used for "rect", "line" and arrow.
Second y coordinate to be considered for each object.
Only used for "rect", "line" and arrow.
Determines if to check for existing data frame and
specified variables. By default is TRUE
unless the shiny package is loaded then set to FALSE so
that Shiny will run. Needs to be set to FALSE if using
the pipe %\>% notation.
If set to TRUE, no text output. Can change system default with
style function.
Width of the plot window in inches, defaults to 4.5.
Height of the plot window in inches, defaults to 4.5.
If TRUE, indicate to direct pdf graphics
for each specified variable to a pdf file named BarChart_name.pdf
where name is the variable name.
Other parameter values for graphics as defined
by barplot, legend, and par including
xlim and ylim for setting the range of the x and y-axes
cex.main for the size of the title
col.main for the color of the title
"dotted", "dotdash"
sub and col.sub for a subtitle and its color
las=3 to reorient vertical axis labels
space for one variable only
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, and also the frequency table converted to a data frame, named freq.df for input into other functions, including ggplot2. If two categorical variables are analyzed, then a data frame of the cross-tabulation table is returned.
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.
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 BarChart(). 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).
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.
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.
COLORS
For a one variable plot, set the default color of the bars by the current color theme according to bar.fill.discrete argument of the function style, which includes the default color theme "colors" that defines a qualitative HCL color scale, or set the bar color with the fill parameter, which references a specified vector of color specifications, such as generated by the lessR getColors function.
Set fill to a single color or a color palette, of which there are many possibilities. Define a qualitative color palette with "colors" that provides HCL colors of the same chroma (saturation) and luminance (brightness). Also available are the pre-specified R color palettes "rainbow", "terrain", and "heat". Pre-defined sequential and divergent color ranges are available as implicit calls to getColors. The full list of pre-defined color ranges (defined in 30 degree increments around the HCL color wheel): "reds", "rusts", "yellows",
"olives", "greens", "emeralds", "turquoises", "aquas", "blues", "purples","violets", "magentas", and "grays".
Define the default qualitative color scale with a fill set to "colors". Define a sequential color scale with single value of fill for a pre-defined palette such as "blues". Define a divergent color scale with value of fill that consists of a vector of two such pre-defined ranges, such as c("purples", "rusts"). Divergent color palettes are applicable in particular for plotting multiple bar charts on the same plot such as for a set of Likert response items, all on a common response scale. Or, manually specify colors. For example, for a two-level by variable, could set fill to c("coral3","seagreen3"), where the specified colors are not pre-defined color ranges.
For the pre-defined color scales can obtain more control over the obtained color palettes with an explicit call to getColors for the argument to fill. Here the value of chroma (c) and luminance (l) can be explicitly manipulated in conjunction with the specification of a pre-defined color range. Or, create a custom color range for any value of hue (h). See getColors for more information.
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.
LONG CATEGORY NAMES
For many plots, the names of the categories tend to be long. To adjust the plot for these long names, they can be rotated using the rotate.x and rotate.y parameters, in conjunction with offset, from the style function. The offset parameter moves the category name out from the axis to compensate for the rotation. The changes from style persist until further changes. To reset to the default after obtaining an analysis, use style().
Also, the following codes are used to adjust line spacing: 1. Any space in a category name is converted to a new line. 2. If the space should not be converted to a new line, the replace with an underscore, which will display as a space and no line break.
For the text output at the console, can specify the maximum number of characters in a label with labels.max. Longer value names are abbreviated to the specified length. This facilitates reading cross-tab tables. Also, a provided table pairs the abbreviated names with the actual names. For one variable frequency distributions, out.size provides the maximum number of characters for the text output before the horizontal display of the frequency distribution is shifted to a vertical presentation.
MULTIPLE BARCHARTS ON THE SAME PANEL (PLOT)
For multiple x-variables, set the parameter one.plot to TRUE to specify that each bar chart should be produced on the same panel as all other bars. This is most meaningful when all items have the same set of responses, such as a common Likert scale found in survey data. By default the one panel plot is produced when a common response scale is detected.
The algorithm to detect if the response scale is common first identifies the first variable with the largest set of responses, then checks the responses of all other variables. If all responses to all other variables are contained within the set of responses to the reference variable, then the response scales are the same. This means that on a Likert scale, for example, some items may not contain all possible responses, such as no one selects Strongly Disagree for an item. However, for the response scales to be deemed the same, at least one item (variable) must contain all possible responses.
Regardless, the one.plot parameter can be set to either TRUE or FALSE regardless of the commonality of responses. Setting this parameter explicitly saves some CPU time as the algorithm to evaluate the communality of responses need not be activated.
ENTER NUMERIC VARIABLE DIRECTLY
Instead of calculating the counts from the data, the values of any numerical variable, including
the counts, can be entered directly as the y-variable, in addition to the categorical x-variable, and perhaps a categorical by-variable. See the examples below, under "bar chart directly from data".
Or, include the already tabulated counts as the data which is read into R, either as a matrix or a data frame.
STATISTICS In addition to the bar chart, 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, set the pdf option to TRUE, 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 YGerbing, D. W. (2014). R Data Analysis without Programming, Chapter 4, NY: Routledge.
# NOT RUN {
# get the data
mydata <- rd("Employee", in.lessR=TRUE)
# --------------------------------------------------------
# bar chart from tabulating the data for a single variable
# --------------------------------------------------------
# for each level of Dept, display the frequencies
BarChart(Dept)
# short name
# bc(Dept)
# save the frequencies for later analysis
myCount <- BarChart(Dept)
# display the frequencies
myCount
# just males with salaries larger than 75,000 USD
BarChart(Dept, rows=(Gender=="M" & Salary > 85000))
# rotate and offset the axis labels, sort categories by frequencies
BarChart(Dept, rotate.x=45, offset=1, sort="-")
# set bars to a single color of blue with some transparency
BarChart(Dept, fill="blue", trans=0.3)
# progressive (sequential) color scale of blues
BarChart(Dept, fill="blues")
# set bar color to hcl custom hues with chroma and luminance
# at the values provided by the default hcl colors from
# the getColors function, which defaults to h=240 and h=60
# for the first two colors on the qualitative scale
bc(Gender, fill=c(hcl(h=180,c=100,l=55), hcl(h=0,c=100,l=55)))
# or set to unique colors via color names
BarChart(Gender, fill=c("palegreen3","tan"))
# darken the colors with an explicit call to getColors,
# do a lower value of luminance, set to l=25
BarChart(Dept, fill=getColors(l=25), trans=0.4)
# column proportions instead of frequencies
BarChart(Gender, proportion=TRUE)
myd <- Read("Cars93", in.lessR=TRUE)
# perpendicular labels
bc(Make, rotate.x=90, data=myd)
# manage size of horizontal value labels
bc(Make, horiz=TRUE, label.max=4, data=myd)
# ----------------------------------------------------
# bar chart from tabulating the data for two variables
# ----------------------------------------------------
# at each level of Dept, show the frequencies of the Gender levels
BarChart(Dept, by=Gender)
# at each level of Dept, show the row proportions of the Gender levels
# i.e., proportional stacked bar graph
BarChart(Dept, by=Gender, proportion=TRUE)
# at each level of Gender, show the frequencies of the Dept levels
# do not display percentages directly on the bars
BarChart(Gender, by=JobSat, fill="reds", values="off")
# specify two fill colors for Gender
BarChart(Dept, by=Gender, fill=getColors(c("deepskyblue", "black")))
# specify an ordered customized blue palette of colors for Dept
# colors can be named or customized with rgb function
# here "azure" is a single color instead of a range (ends in s)
BarChart(Gender, by=Dept,
fill=getColors("azure", end.clr=rgb(100,110,200,max=255)))
# display bars beside each other instead of stacked, Female and Male
# the levels of Dept are included within each respective bar
# plot horizontally, display the value for each bar at the
# top of each bar
BarChart(Gender, by=Dept, beside=TRUE, horiz=TRUE, values.pos="out")
# horizontal bar chart of two variables, put legend on the top
BarChart(Gender, by=Dept, horiz=TRUE, legend.loc="top")
# many options, including those from par: col.main, col.lab, lab.cex
# for more info on these graphic options, enter: help(par)
# here fill is set in the style function instead of BarChart
# along with the others
style(fill=c("coral3","seagreen3"), lab.color="wheat4", lab.cex=1.2,
panel.fill="wheat1", main.color="wheat4")
BarChart(Dept, by=Gender,
legend.loc="topleft", legend.labels=c("Girls", "Boys"),
xlab="Dept Level", main="Gender for Different Dept Levels",
value.labels=c("None", "Some", "Much", "Ouch!"))
style()
# -----------------------------------------------------------------
# multiple bar charts tabulated from data 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(one.plot=FALSE)
mydata <- rd("Mach4", in.lessR=TRUE, quiet=TRUE)
# all on the same plot, bar charts for 20 6-pt Likert scale items
# default scale is divergent from "yellows" to "blues"
BarChart(m01:m20, horiz=TRUE, values="off", sort="+")
# }
# NOT RUN {
# custom scale with explicit call to getColors, HCL chroma at 50
clrs <- getColors("greens", "purples", n=6, c=50)
BarChart(m01:m20, horiz=TRUE, values="off", sort="+", fill=clrs)
# custom divergent scale with pre-defined color palettes
# with implicit call to getColors
BarChart(m01:m20, horiz=TRUE, values="off", fill=c("aquas", "rusts"))
# ----------------------------
# 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 data
# ----------------------------
# include a y-variable, here Salary, in the data table to read directly
mydata <- read.csv(text="
Dept, Salary
ACCT,51792.78
ADMN,71277.12
FINC,59010.68
MKTG,60257.13
SALE,68830.06", header=TRUE)
BarChart(Dept, Salary)
# specify two variables for a two variable bar chart
# also specify a y-variable to provide the counts directly
mydata <- read.csv(text="
Dept,Gender,Count
ACCT,F,3
ACCT,M,2
ADMIN,F,4
ADMIN,M,2
FINC,F,1
FINC,M,3
MKTG,F,5
MKTG,M,1
SALE,F,5
SALE,M,10", header=TRUE)
BarChart(Dept, Count, by=Gender)
# -----------
# annotations
# -----------
mydata <- rd("Employee", in.lessR=TRUE)
# Place a message in the center of the plot
# \n indicates a new line
BarChart(Dept, add="Employees by\nDepartment", x1=3, y1=10)
# Use style to change some parameter values
style(add.trans=.8, add.fill="gold", add.color="gold4", add.lwd=0.5)
# Add a rectangle around the message centered at <3,10>
BarChart(Dept, add=c("rect", "Employees by\nDepartment"),
x1=c(2,3), y1=c(11, 10), x2=4, y2=9)
# }
Run the code above in your browser using DataLab