Enhanced Version of dotchart Function for plotly

This function produces a plotly interactive graphic and accepts a different format of data input than the other dotchart 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 groups 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.

Specify fun=exp and ifun=log if estimates and confidence limits are on the log scale. Make sure that zeros were prevented in the original calculations. For exponential hazard rates this can be accomplished by replacing event counts of 0 with 0.5.

Usage

dotchartpl(x, major=NULL, minor=NULL, group=NULL, mult=NULL,
           big=NULL, htext=NULL, num=NULL, denom=NULL,
           numlabel='', denomlabel='',
           fun=function(x) x, ifun=function(x) x, op='-',
           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',
           dec=3, width=800, height=NULL,
           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 groups

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

numlabel

character string to put to the right of the numerator in hover text

denomlabel

character string to put to the right of the denominator in hover text

fun

a transformation to make when printing estimates. For example, one may specify fun=exp to anti-log estimates and confidence limites that were computed on a log basis

ifun

inverse transformation of fun

op

set to for example '/' when fun=exp and effects are computed as ratios instead of differences. This is used in hover text.

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.

dec

number of places to the right of the decimal place for formatting numeric quantities in hover text

width

width of plot in pixels

height

height of plot in pixels; computed from number of strata by default

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

Frank Harrell

See also

dotchartp

Examples

if (FALSE) { # \dontrun{
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,
            lower=lower, upper=upper, 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')

# Plot hazard rates and ratios with confidence limits, on log scale
d <- data.frame(tx=c('a', 'a', 'b', 'b'),
                event=c('MI', 'stroke', 'MI', 'stroke'),
                count=c(10, 5, 5, 2),
                exposure=c(1000, 1000, 900, 900))
# There were no zero event counts in this dataset.  In general we
# want to handle that, hence the 0.5 below
d <- upData(d, hazard = pmax(0.5, count) / exposure,
               selog  = sqrt(1. / pmax(0.5, count)),
               lower  = log(hazard) - 1.96 * selog,
               upper  = log(hazard) + 1.96 * selog)
with(d,
     dotchartpl(log(hazard), minor=event, group=tx, num=count, denom=exposure,
                lower=lower, upper=upper,
                fun=exp, ifun=log, op='/',
                numlabel='events', denomlabel='years',
                refgroup='a', xlab='Events Per Person-Year')
)
} # }