dotchartpl {Hmisc} | R Documentation

## Enhanced Version of dotchart Function for plotly

### Description

This function produces a `plotly` interactive graphic and accepts a different format of data input than the other `dotchart`x functions. It was written to handle a hierarchical data structure including strata that further subdivide the main classes. Strata, indicated by the `mult` variable, are shown on the same horizontal line, and if the variable `big` is `FALSE` will appear slightly below the main line, using smaller symbols, and having some transparency. This is intended to handle output such as that from the `summaryP` function when there is a superpositioning variable `group` and a stratification variable `mult`, especially when the data have been run through the `addMarginal` function to create `mult` categories labelled `"All"` for which the user will specify `big=TRUE` to indicate non-stratified estimates (stratified only on `group`) to emphasize.

When viewing graphics that used `mult` and `big`, the user can click on the legends for the small points for `group`s to vanish the finely stratified estimates.

When `group` is used by `mult` and `big` are not, and when the `group` variable has exactly two distinct values, you can specify `refgroup` to get the difference between two proportions in addition to the individual proportions. The individual proportions are plotted, but confidence intervals for the difference are shown in hover text and half-width confidence intervals for the difference, centered at the midpoint of the proportions, are shown. These have the property of intersecting the two proportions if and only if there is no significant difference at the `1 - conf.int` level.

### Usage

    dotchartpl(x, major=NULL, minor=NULL, group=NULL, mult=NULL,
               big=NULL, htext=NULL, num=NULL, denom=NULL,
               lower=NULL, upper=NULL,
               refgroup=NULL, sortdiff=TRUE, conf.int=0.95,
               minkeep=NULL, xlim=NULL, xlab='Proportion',
               tracename=NULL, limitstracename='Limits',
               nonbigtracename='Stratified Estimates',
               width=800,
               col=colorspace::rainbow_hcl)

### Arguments

`x` | a numeric vector used for values on the `x`-axis
`major` | major vertical category, e.g., variable labels
`minor` | minor vertical category, e.g. category levels within variables
`group` | superpositioning variable such as treatment
`mult` | strata names for further subdivisions without `group`s
`big` | omit if all levels of `mult` are equally important or if `mult` is omitted. Otherwise denotes major (larger points, right on horizontal lines) vs. minor (smaller, transparent points slightly below the line).
`htext` | additional hover text per point
`num` | if `x` represents proportions, optionally specifies numerators to be used in fractions added to hover text. When `num` is given, `x` is automatically added to hover text, rounded to 3 digits after the decimal point.
`denom` | like `num` but for denominators
`lower` | lower limits for optional error bars
`upper` | upper limits for optional error bars
`refgroup` | if `group` is specified and there are exactly two groups, specify the character string for the reference group in computing difference in proportions. For example if `refgroup='A'` and the `group` levels are `'A','B'`, you will get B - A.
`sortdiff` | `minor` categories are sorted by descending values of the difference in proportions when `refgroup` is used, unless you specify `sortdiff=FALSE`
`conf.int` | confidence level for computing confidence intervals for the difference in two proportions. Specify `conf.int=FALSE` to suppress confidence intervals.
`minkeep` | if `refgroup` and `minkeep` are both given, observations that are at or above `minkeep` for at least one of the groups are retained. The defaults to to keep all observations.
`xlim` | `x`-axis limits
`xlab` | `x`-axis label
`tracename` | `plotly` trace name if `group` is not used
`limitstracename` | `plotly` trace name for `lower` and `upper` if `group` is not used
`nonbigtracename` | `plotly` trace name used for non-big elements, which usually represent stratified versions of the "big" observations
`col` | a function or vector of colors to assign to `group`. If a function it will be evaluated with an argument equal to the number of distinct groups.
`width` | width of plot in pixels

### Value

a `plotly` object. An attribute `levelsRemoved` is added if `minkeep` is used and any categories were omitted from the plot as a result. This is a character vector with categories removed. If `major` is present, the strings are of the form `major:minor`

### Author(s)

Frank Harrell

### See Also

`dotchartp`

### Examples

    ## Not run:
    set.seed(1)
    d <- expand.grid(major=c('Alabama', 'Alaska', 'Arkansas'),
                     minor=c('East', 'West'),
                     group=c('Female', 'Male'),
                     city=0:2)
    n <- nrow(d)
    d$num   <- round(100*runif(n))
    d$denom <- d$num + round(100*runif(n))
    d$x     <- d$num / d$denom
    d$lower <- d$x - runif(n)
    d$upper <- d$x + runif(n)

    with(d,
     dotchartpl(x, major, minor, group, city, lower=lower, upper=upper,
                big=city==0, num=num, denom=denom, xlab='x'))

    # Show half-width confidence intervals for Female - Male differences
    # after subsetting the data to have only one record per
    # state/region/group
    d <- subset(d, city == 0)
    with(d,
     dotchartpl(x, major, minor, group, num=num, denom=denom, refgroup='Male')
    )

    n <- 500
    set.seed(1)
    d <- data.frame(
      race         = sample(c('Asian', 'Black/AA', 'White'), n, TRUE),
      sex          = sample(c('Female', 'Male'), n, TRUE),
      treat        = sample(c('A', 'B'), n, TRUE),
      smoking      = sample(c('Smoker', 'Non-smoker'), n, TRUE),
      hypertension = sample(c('Hypertensive', 'Non-Hypertensive'), n, TRUE),
      region       = sample(c('North America','Europe','South America',
                              'Europe', 'Asia', 'Central America'), n, TRUE))

    d <- upData(d, labels=c(race='Race', sex='Sex'))

    dm <- addMarginal(d, region)
    s <- summaryP(race + sex + smoking + hypertension ~
                    region + treat,  data=dm)

    s$region <- ifelse(s$region == 'All', 'All Regions', as.character(s$region))

    with(s,
     dotchartpl(freq / denom, major=var, minor=val, group=treat, mult=region,
                big=region == 'All Regions', num=freq, denom=denom)
    )

    s2 <- s[- attr(s, 'rows.to.exclude1'), ]
    with(s2,
         dotchartpl(freq / denom, major=var, minor=val, group=treat, mult=region,
                    big=region == 'All Regions', num=freq, denom=denom)
    )
    # Note these plots can be created by plot.summaryP when options(grType='plotly')

    ## End(Not run)

[Package Hmisc version 4.2-0 Index]