Bar Graph

DESCRIPTION:

USAGE:

barplot(height, width=<<see below>>, names=NULL, legend=NULL, 
        style.bar=list(), space=.2, inside=T, beside=F, 
        horiz=F, blocks=T, histo=F, axes=T, 
        angle=<<see below>>, sbangle=45, dbangle=45,  
        density=<<see below>>, sbdensity=5, dbdensity=5, 
        col=<<see below>>, sbcol=2, dbcol=<<see below>>) 

REQUIRED ARGUMENTS:

height

matrix or vector giving the heights (positive or negative) of the bars. If height is a matrix, each column represents one bar; the values in the columns are treated as heights of blocks. Blocks of positive height are stacked above the zero line and those with negative height are stacked below the line. Matrix values in height can also be treated as the positions of the dividing lines; see argument blocks.

OPTIONAL ARGUMENTS:

width

if histo=FALSE, vector of relative bar widths; in this case all of the bars are the same width by default. When histo=TRUE, width represents where the breaks are for the histogram.

names

character vector of names for the bars.

legend

a vector of names to be correlated with the bar shading which should be plotted as a legend. This usually corresponds to the rows of height. The legend is put in the upper right of the plot by default; use the legend function if more control over legend positioning is required.

style.bar

character string or list indicating the style of the barplot. If specified as a character string, the string is appended to " bar." to get the name of a dataset which is a list. Component names of this list should match the names of the arguments below; the component values serve as the defaults for the corresponding arguments (i.e., other arguments supplied to the function override the style.bar list member values). Standard style.bar option values include "splus" and "old".

space

the space (as a fraction of the average bar width) that should be left before each bar. This may be given as a single number or one number per bar. If beside is TRUE, space may be specified by 2 numbers where the first is the space between bars in a set, and the second is the space between sets.

inside

logical flag: if TRUE, the internal lines which divide adjacent bars will be drawn.

beside

logical flag: if TRUE and if height is a matrix, the bars for different rows will be plotted beside each other, not as a single divided bar. If width is given in the case beside=TRUE, there must be as many widths as the number of values in heights, not the number of columns. The same is true of names, if this is supplied.

horiz

logical flag: if TRUE, the graph will be drawn horizontally, with the first bar at the bottom.

blocks

logical flag: if TRUE, the height matrix is treated according to the "blocks" model in which each value in height is the height of a block to be stacked above or below the axis. If blocks is FALSE, values in height give the coordinates at which the bar dividing lines are to be drawn. In this case, the values in any column of height should be monotonically increasing.

histo

logical flag: if TRUE, a histogram is produced; that is, space is set to 0, width is given a different meaning, and the axis in the width direction is drawn as well as the height axis if axes=TRUE.

axes

logical flag: should the axis for height be drawn? Both axes are drawn if histo=TRUE.

angle

vector giving the angle (degrees, counter-clockwise from horizontal) for shading each bar division. Negative values are allowed. This defaults to either sbangle or dbangle, if density is supplied.

sbangle

similar to the angle argument, but only applies to solid bars, i.e., where the height argument is a vector or a matrix with only one row. If the angle argument is supplied, sbangle is ignored.

dbangle

similar to the angle argument, but only applies to the blocks of a divided bar chart, i.e., where the height argument is a matrix with more than one row. If the angle argument is supplied, dbangle is ignored.

density

vector for bar shading, giving the number of lines per inch for shading each bar division. A density of 0 implies solid filling, and negative values produce no shading. The special value, NA, will produce no shading if angle is not supplied, or the default value of 5 if angle is supplied. The density option defaults to either sbdensity or dbdensity, if angle is supplied.

sbdensity

similar to the density argument, but only applies to solid bars, i.e., where the height argument is a vector or a matrix with only one row. If the density argument is supplied, sbdensity is ignored.

dbdensity

similar to the density argument, but only applies to the blocks of a divided bar chart, i.e., where the height argument is a matrix with more than one row. If the density argument is supplied, dbdensity is ignored.

col

vector giving the colors in which the bars should be filled or shaded. If col is specified and neither angle nor density are given as arguments, bars will be filled solidly with the colors. If angle or density are given, col refers to the color of the shading lines. The special value, NA, can be used to indicate that the current par("col") value is to be used for the fill or shading color.

sbcol

similar to the col argument, but only applies to solid bars, i.e., where the height argument is a vector or a matrix with only one row. If the col argument is supplied, sbcol is ignored.

dbcol

similar to the col argument, but only applies to the blocks of a divided bar chart, i.e., where the height argument is a matrix with more than one row. If the col argument is supplied, dbcol is ignored. By default, it cycles through the available colors, starting at color 2.

Graphical parameters may also be supplied as arguments to this function (see par ). In addition, the high-level graphics arguments described under plot.default and the arguments to title may be supplied to this function. However, barplot will always use linear axes: the log and [xy]axt parameters do not affect it. You may transform your data, call barplot with axes=F, and then call axis with the at and labels arguments to make nonlinear axes that match your transformation. See the rootogram example below.

VALUE:

a non-printing vector which contains the x-coordinates of the centers of the bars (y-coordinates if the bars are horizontal). The returned value can be used if you want to add to the plot.

SIDE EFFECTS:

DETAILS:

The default options are geared towards devices that have color or halftoning capabilities, such as motif and postscript.

Occasionally the legend will overwrite a bar; if it does, use ylim ( xlim if horiz=TRUE) to expand the axis.

To produce solid filling, specify col but neither angle or density. If you want to have both hatching and solid filling, specify density=0 for the solidly filled segments. Solid filling of bars is dependent on the area-filling capability of the device. For devices without explicit area-filling capability, solid filling can be simulated by specifying a very high density shading.

The sb* and db* arguments are primarily for use in style.bar argument lists, as is the use of NA for col and density argument values.

When using a height matrix of more than one row, the col, density and angle arguments can be specified either as vectors or as matrices having the same dimensions as the height matrix. As a matrix, each element specifies the attribute to be used for the block drawn from the corresponding element of the height matrix. As a vector, it is repeated (or truncated) to the number of rows in height . Using vectors for the attributes gives corresponding blocks in different bars the same attributes. Using matrices allows control of the attributes for all of the blocks in the barplot.

REFERENCES:

Cleveland, W. S. (1985). The Elements of Graphing Data. Monterey, California: Wadsworth.

SEE ALSO:

EXAMPLES:

x <- barplot(height)  # do plot, save x coordinates of bar centers 
text(x, height+1, height)  # label the tops of the bars 
# a plot, sans labels and legend, using a style list 
bar.dbstyle <- list(dbangle=c(45, 135), dbdensity=(1:4)*6) 
barplot(  t(telsam.response[1:5,]), ylim=c(0, 200), style="dbstyle") 
# a similar plot, with hollow 1st block, solid 2nd block and density 
# set to 18 and 24 for the remaining 2 blocks 
bar.dbstyle <- list(dbangle=c(45, 135), dbdensity=c(-1, 0, 18, 24)) 
barplot(  t(telsam.response[1:5,]), ylim=c(0, 200), style="dbstyle") 
# the following rootogram function plots a histogram on a 
# square root scale 
rootogram <- function(x, ...) 
{ 
        h <- hist(x, ..., plot = F) 
        h$counts <- sqrt(h$counts) 
        barplot(height = h$counts, width = h$breaks, histo = T, axes = F) 
        axis(side = 1) 
        lab <- pretty(c(0, h$counts), par("lab")[2])^2 
        axis(side = 2, at = sqrt(lab), labels = as.character(lab), 
                srt = if (par("las")==0) 90 else 0) 
        invisible() 
} 
barplot( t(telsam.response[1:5,]), ylim=c(0, 200), 
      angle=c(45, 135), density=(1:4)*6, 
      legend=dimnames(telsam.response)[[2]], 
      names=as.character(dimnames(telsam.response)[[1]][1:5]), 
      xlab="Interviewer", ylab="Number of Responses", 
      main="Response to Quality of Service Question")