# dotchart3

##### Enhanced Version of dotchart Function

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`

.

- Keywords
- hplot

##### 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, …)

##### 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
see

`dotchart`

- 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. For`dotchartp`

,`auxdata`

may be a matrix to go along with the numeric x-axis variable, to result in point-specific hover text.- 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

- digits
number of significant digits for formatting numeric data in hover text for

`dotchartp`

- dec
for

`dotchartp`

only, overrides`digits`

to specify the argument to`round()`

for rounding values for hover labels- cex.labels
`cex`

for labels- cex.group.labels
`cex`

for group labels- cex.auxdata
`cex`

for`auxdata`

- groupfont
font number for group headings

- auxwhere
for

`summaryD`

and`dotchartp`

specifies whether`auxdata`

and`auxgdata`

are to be placed on the far right of the chart, or should appear as pop-up tooltips when hovering the mouse over the ordinary`x`

data points on the chart. Ignored for`dotchart3`

.- …
other arguments passed to some of the graphics functions, or to

`dotchart3`

or`dotchartp`

from`summaryD`

. The`auxwhere='hover'`

option is a useful argument to pass from`summaryD`

to`dotchartp`

.- layoutattr
set to

`TRUE`

to put`plotly::layout`

information in a list as an attribute`layout`

of the returned`plotly`

object instead of running the`plotly`

object through the`layout`

function. This is useful if running`dotchartp`

multiple times to later put together using`plotly::subplot`

and only then running the result through`plotly::layout`

.- showlegend
set to

`FALSE`

to suppress the`plotly`

legend with`dotchartp`

- 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.- symbol
a scalar or vector of

`pch`

values for ordinary graphics or a character vector or scalar of`plotly`

symbols. These correspond to columns of`x`

or elements produced by`fun`

.- 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

`plotly`

documentation; corresponds to column names/`fun`

output for`plotly`

graphs only- gridevery
specify a positive number to draw very faint vertical grid lines every

`gridevery`

`x`

-axis units; for non-`plotly`

charts- 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. For`dotchartp`

, set`sort`

to`'descending'`

to sort in descending order of the first column of`x`

, or`'ascending'`

to do the reverse. These do not make sense if`groups`

is present.- height,width
height and width in pixels for

`dotchartp`

if not using`plotly`

defaults. Ignored for`dotchart3`

. If set to`"auto"`

the height is computed using`Hmisc::plotlyHeightDotchart`

.

##### Value

the function returns invisibly

##### See Also

##### Examples

```
# NOT RUN {
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', 'line-ns-open'))
# }
# 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')
# }
```

*Documentation reproduced from package Hmisc, version 4.0-3, License: GPL (>= 2)*