R: Enhanced Dot Chart

dotchart2 {Hmisc} | R Documentation

## Enhanced Dot Chart

### Description

`dotchart2` is an enhanced version of the `dotchart` function with several new options.

### Usage

    dotchart2(data, labels, groups=NULL, gdata=NA, horizontal=TRUE, pch=16,
              xlab='', ylab='', xlim=NULL, auxdata, auxgdata=NULL, auxtitle,
              lty=1, lines=TRUE, dotsize = .8,
              cex = par("cex"), cex.labels = cex,
              cex.group.labels = cex.labels*1.25, sort.=TRUE,
    	      add=FALSE, dotfont=par('font'), groupfont=2,
    	      reset.par=add, xaxis=TRUE, width.factor=1.1,
              lcolor='gray', leavepar=FALSE,
              axisat=NULL, axislabels=NULL, ...)

### Arguments

`data` | a numeric vector whose values are shown on the x-axis
`labels` | a vector of labels for each point, corresponding to `x`. If omitted, `names(data)` are used, and if there are no `names`, integers prefixed by `"#"` are used.
`groups` | an optional categorical variable indicating how `data` values are grouped
`gdata` | data values for groups, typically summaries such as group medians
`horizontal` | set to `FALSE` to make the chart vertical instead of the default
`pch` | default character number or value for plotting dots in dot charts. The default is 16.
`xlab` | x-axis title
`ylab` | y-axis title
`xlim` | x-axis limits. Applies only to `horizontal=TRUE`.
`auxdata` | a vector of auxiliary data given to `dotchart2`, of the same length as the first (`data`) argument. If present, this vector of values will be printed outside the right margin of the dot chart. Usually `auxdata` represents cell sizes.
`auxgdata` | similar to `auxdata` but corresponding to the `gdata` argument. These usually represent overall sample sizes for each group of lines.
`auxtitle` | if `auxdata` is given, `auxtitle` specifies a column heading for the extra printed data in the chart, e.g., `"N"`
`lty` | line type for horizontal lines. Default is 1 for R, 2 for S-Plus
`lines` | set to `FALSE` to suppress drawing of reference lines
`dotsize` | `cex` value for drawing dots. Default is 0.8. Note that the original `dotchart` function used a default of 1.2.
`cex` | see `par`
`cex.labels` | `cex` parameter that applies only to the line labels for the dot chart `cex` parameter for major grouping labels for `dotchart2`. Defaults to `cex`.
`cex.group.labels` | value of `cex` corresponding to `gdata`
`sort.` | set to `FALSE` to keep `dotchart2` from sorting the input data, i.e., it will assume that the data are already properly arranged. This is especially useful when you are using `gdata` and `groups` and you want to control the order that groups appear on the chart (from top to bottom).
`add` | set to `TRUE` to add to an existing plot
`dotfont` | font number of plotting dots. Default is one. Use `-1` to use "outline" fonts. For example, `pch=183, dotfont=-1` plots an open circle for UNIX on postscript. `pch=1` makes an open octagon under Windows.
`groupfont` | font number to use in drawing `group` labels for `dotchart2`. Default is `2` for boldface.
`reset.par` | set to `FALSE` to cause `dotchart2` to not reset the `par` parameters when finished. This is useful when `add=TRUE` is about to be used in another call. The default is to reset the `par` parameters if `add=TRUE` and not if `add=FALSE`, i.e., the program assumes that only one set of points will be added to an existing set. If you fail to use `reset.par=TRUE` for the first of a series of plots, the next call to `plot` with `add=TRUE` will result in distorted x-axis scaling.
`xaxis` | set to `FALSE` to suppress drawing x-axis
`width.factor` | When the calculated left margin turns out to be faulty, specify a factor by which to multiple the left margin as `width.factor` to get the appropriate space for labels on horizonal charts.
`lcolor` | color for horizontal reference lines. Default is `"gray"` for R, `par("col")` for S-Plus.
`leavepar` | set to `TRUE` to leave `par()` unchanged. This assumes the user has allocated sufficient left and right margins for a horizontal dot chart.
`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
`...` | arguments passed to `plot.default`

### Side Effects

`dotchart` will leave `par` altered if `reset.par=FALSE`.

### Author(s)

Frank Harrell
Department of Biostatistics
Vanderbilt University
fh@fharrell.com

### See Also

`dotchart`

### 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))
    dotchart2(y1, g, groups=maj, auxdata=n, auxtitle='n', xlab='Y')
    dotchart2(y2, g, groups=maj, pch=17, add=TRUE)
    ## Compare with dotchart function (no superpositioning or auxdata allowed):
    ## dotchart(y1, g, groups=maj, xlab='Y')

    ## To plot using a transformed scale add for example
    ## axisat=sqrt(pretty(y)), axislabels=pretty(y)

[Package Hmisc version 4.7-0 Index]