Hmisc (version 3.17-4)

dotchart3: Enhanced Version of dotchart Function

Description

This is an adaptation of the R dotchart function that sorts categories top to bottom, adds auxdata and auxtitle arguments to put extra information in the right margin, and adds arguments cex.labels, cex.group.labels, and groupfont. By default, group headings are in a larger, bold font. dotchart3 also cuts a bit of white space from the top and bottom of the chart. The most significant change, however, is in how x is interpreted. Columns of x no longer provide an alternate way to define groups. Instead, they define superpositioned values. This is useful for showing three quartiles, for example. Going along with this change, pch can now be a vector specifying symbols to use going across columns of x. x was changed in this way because to put multiple points on a line (e.g., quartiles) and keeping track of par() parameters when dotchart2 was called with add=TRUE was cumbersome. All the dotchart functions change the margins to account for horizontal labels.

summaryD creates aggregate data using summarize and calls dotchart3 with suitable arguments to summarize data by major and minor categories.

Usage

dotchart3(x, labels = NULL, groups = NULL, gdata = NULL, cex = par("cex"), pch = 21, gpch = pch, bg = par("bg"), color = par("fg"), gcolor = par("fg"), lcolor = "gray", xlim = range(c(x, gdata), na.rm=TRUE), main = NULL, xlab = NULL, ylab = NULL, auxdata = NULL, auxtitle = NULL, auxgdata=NULL, axisat=NULL, axislabels=NULL, cex.labels = cex, cex.group.labels = cex.labels * 1.25, cex.auxdata=cex, groupfont = 2, ...)
summaryD(formula, data=NULL, fun=mean, funm=fun, groupsummary=TRUE, auxvar=NULL, auxtitle='', vals=length(auxvar) > 0, fmtvals=format, cex.auxdata=.7, xlab=v[1], ylab=NULL, gridevery=NULL, gridcol=gray(.95), sort=TRUE, ...)

Arguments

x
a numeric vector or matrix
labels
labels for categories corresponding to rows of x. If not specified these are taken from row names of x.
groups,gdata,cex,pch,gpch,bg,color,gcolor,lcolor,xlim,main,xlab,ylab
auxdata
a vector of information to be put in the right margin, in the same order as x. May be numeric, character, or a vector of expressions containing plotmath markup
auxtitle
a column heading for auxdata
auxgdata
similar to auxdata but corresponding to the gdata argument. These usually represent overall sample sizes for each group of lines.
axisat
a vector of tick mark locations to pass to axis. Useful if transforming the data axis
axislabels
a vector of strings specifying axis tick mark labels. Useful if transforming the data axis
cex.labels
cex for labels
cex.group.labels
cex for group labels
cex.auxdata
cex for auxdata
groupfont
font number for group headings
...
other arguments passed to some of the graphics functions, or to dotchart3 from summaryD
formula
a formula with one variable on the left hand side (the variable to compute summary statistics on), and one or two variables on the right hand side. If there are two variables, the first is taken as the major grouping variable. If the left hand side variable is a matrix it has to be a legal R variable name, not an expression, and fun needs to be able to process a matrix.
data
a data frame or list used to find the variables in formula. If omitted, the parent environment is used.
fun
a summarization function creating a single number from a vector. Default is the mean.
funm
applies if there are two right hand variables and groupsummary=TRUE and the marginal summaries over just the first x variable need to be computed differently than the summaries that are cross-classified by both variables. funm defaults to fun and should have the same structure as fun.
groupsummary
By default, when there are two right-hand variables, summarize(..., fun) is called a second time without the use of the second variable, to obtain marginal summaries for the major grouping variable and display the results as a dot (and optionally in the right margin). Set groupsummary=FALSE to suppress this information.
auxvar
when fun returns more than one statistic and the user names the elements in the returned vector, you can specify auxvar as a single character string naming one of them. This will cause the named element to be written in the right margin, and that element to be deleted when plotting the statistics.
vals
set to TRUE to show data values (dot locations) in the right margin. Defaults to TRUE if auxvar is specified.
fmtvals
an optional function to format values before putting them in the right margin. Default is the format function.
gridevery
specify a positive number to draw very faint vertical grid lines every gridevery x-axis units
gridcol
color for grid lines; default is very faint gray scale
sort
specify sort=FALSE to plot data in the original order, from top to bottom on the dot chart

Value

See Also

dotchart,dotchart2,summarize, rlegend

Examples

Run this code
set.seed(135)
maj <- factor(c(rep('North',13),rep('South',13)))
g <- paste('Category',rep(letters[1:13],2))
n <- sample(1:15000, 26, replace=TRUE)
y1 <- runif(26)
y2 <- pmax(0, y1 - runif(26, 0, .1))
dotchart3(cbind(y1,y2), g, groups=maj, auxdata=n, auxtitle='n',
          xlab='Y', pch=c(1,17))
## Compare with dotchart function (no superpositioning or auxdata allowed):
## dotchart(y1, g, groups=maj, xlab='Y')

summaryD(y1 ~ maj + g, xlab='Mean')
summaryD(y1 ~ maj + g, groupsummary=FALSE)
summaryD(y1 ~ g, fmtvals=function(x) sprintf('%4.2f', x))
Y <- cbind(y1, y2)   # summaryD cannot handle cbind(...) ~ ...
summaryD(Y  ~ maj + g, fun=function(y) y[1,], pch=c(1,17))
rlegend(.1, 26, c('y1','y2'), pch=c(1,17))

summaryD(y1 ~ maj, fun=function(y) c(mean(y), n=length(y)),
         auxvar='n', auxtitle='N')

Run the code above in your browser using DataCamp Workspace