dotchart3 {Hmisc}  R Documentation 
Enhanced Version of dotchart Function
Description
These are adaptations 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 for dotchart3
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, for dotchart3
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.
dotchart3
changes the margins to account for horizontal labels.
dotchartp
is a version of dotchart3
for making the chart
with the plotly
package.
summaryD
creates aggregate data using summarize
and
calls dotchart3
with suitable arguments to summarize data by
major and minor categories. If options(grType='plotly')
is in
effect and the plotly
package is installed, summaryD
uses
dotchartp
instead of dotchart3
.
summaryDp
is a streamlined summaryD
like function that
uses the dotchartpl
function to render a plotly
graphic.
It is used to compute summary statistics stratified separately by a
series of variables.
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,
auxwhere=NULL, height=NULL, width=NULL, ...)
dotchartp(x, labels = NULL, groups = NULL, gdata = NULL,
xlim = range(c(x, gdata), na.rm=TRUE), main=NULL,
xlab = NULL, ylab = '', auxdata=NULL, auxtitle=NULL,
auxgdata=NULL, auxwhere=c('right', 'hover'),
symbol='circle', col=colorspace::rainbow_hcl,
legendgroup=NULL,
axisat=NULL, axislabels=NULL, sort=TRUE, digits=4, dec=NULL,
height=NULL, width=700, layoutattr=FALSE, showlegend=TRUE, ...)
summaryD(formula, data=NULL, fun=mean, funm=fun,
groupsummary=TRUE, auxvar=NULL, auxtitle='',
auxwhere=c('hover', 'right'),
vals=length(auxvar) > 0, fmtvals=format,
symbol=if(use.plotly) 'circle' else 21,
col=if(use.plotly) colorspace::rainbow_hcl else 1:10,
legendgroup=NULL,
cex.auxdata=.7, xlab=v[1], ylab=NULL,
gridevery=NULL, gridcol=gray(.95), sort=TRUE, ...)
summaryDp(formula,
fun=function(x) c(Mean=mean(x, na.rm=TRUE),
N=sum(! is.na(x))),
overall=TRUE, xlim=NULL, xlab=NULL,
data=NULL, subset=NULL, na.action=na.retain,
ncharsmax=c(50, 30),
digits=4, ...)
Arguments
x 
a numeric vector or matrix 
labels 
labels for categories corresponding to rows of

groups , gdata , cex , pch , gpch , bg , color , gcolor , lcolor , xlim , main , xlab , ylab 
see 
auxdata 
a vector of information to be put in the right margin,
in the same order as 
auxtitle 
a column heading for 
auxgdata 
similar to 
axisat 
a vector of tick mark locations to pass to 
axislabels 
a vector of strings specifying axis tick mark labels. Useful if transforming the data axis 
digits 
number of significant digits for formatting numeric data
in hover text for 
dec 
for 
cex.labels 

cex.group.labels 

cex.auxdata 

groupfont 
font number for group headings 
auxwhere 
for 
... 
other arguments passed to some of the graphics functions,
or to 
layoutattr 
set to 
showlegend 
set to 
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 
data 
a data frame or list used to find the variables in

fun 
a summarization function creating a single number from a
vector. Default is the mean. For 
funm 
applies if there are two right hand variables and

groupsummary 
By default, when there are two righthand
variables, 
auxvar 
when 
vals 
set to 
fmtvals 
an optional function to format values before putting
them in the right margin. Default is the 
symbol 
a scalar or vector of 
col 
a function or vector of colors to assign to multiple points plotted in one line. If a function it will be evaluated with an argument equal to the number of groups/columns. 
legendgroup 
see 
gridevery 
specify a positive number to draw very faint vertical
grid lines every 
gridcol 
color for grid lines; default is very faint gray scale 
sort 
specify 
height , width 
height and width in pixels for 
overall 
set to 
subset 
an observation subsetting expression 
na.action 
an 
ncharsmax 
a 2vector specifying the number of characters after which an html new line character should be placed, respectively for the xaxis label and the stratification variable levels 
Value
the function returns invisibly
Author(s)
Frank Harrell
See Also
dotchart
,dotchart2
,summarize
,
rlegend
Examples
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')
## Not run:
dotchartp(cbind(y1, y2), g, groups=maj, auxdata=n, auxtitle='n',
xlab='Y', gdata=cbind(c(0,.1), c(.23,.44)), auxgdata=c(1,2),
symbol=c('circle', 'linensopen'))
summaryDp(sbp ~ region + sex + race + cut2(age, g=5), data=mydata)
## End(Not run)
## Put options(grType='plotly') to have the following use dotchartp
## (rlegend will not apply)
## Add argument auxwhere='hover' to summaryD or dotchartp to put
## aux info in hover text instead of right margin
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,], symbol=c(1,17))
rlegend(.1, 26, c('y1','y2'), pch=c(1,17))
summaryD(y1 ~ maj, fun=function(y) c(Mean=mean(y), n=length(y)),
auxvar='n', auxtitle='N')