tinyplot (version 0.8.0)

type_errorbar: Error bar and pointrange plot types

Description

Type function(s) for producing error bar and pointrange plots.

Usage

type_errorbar(
  length = 0.05,
  dodge = 0,
  fixed.dodge = FALSE,
  xlevels = NULL,
  xord = "asis"
)
type_pointrange(dodge = 0, fixed.dodge = FALSE, xlevels = NULL, xord = "asis")

Arguments

length

length of the edges of the arrow head (in inches).

dodge

Adjustment parameter for dodging overlapping points or ranges in grouped plots along the x-axis (or y-axis for flipped plots). Either:

• numeric value in the range [0,1). Note that values are scaled relative to the spacing of x-axis breaks, e.g. dodge = 0.1 places the outermost groups one-tenth of the way to adjacent breaks, dodge = 0.5 places them midway between breaks, etc. Values < 0.5 are recommended.

• logical. If TRUE, the dodge width is calculated automatically based on the number of groups (0.1 per group for 2-4 groups, 0.45 for 5+ groups). If FALSE or 0, no dodging is performed.

Default value is 0 (no dodging). While we do not check, it is strongly recommended that dodging only be used in cases where the x-axis comprises a limited number of discrete breaks.

fixed.dodge

Logical. If FALSE (default), dodge positions are calculated independently for each x value, based only on the groups present at that position. If TRUE, dodge positions are based on all groups, ensuring "fixed" spacing across x-axis breaks (i.e., even if some groups are missing for a particular x value).

xlevels, xord

arguments controlling the order of the x variable, and hence of the x-axis. Supply one or the other; if both arguments are provided, xlevels takes precedence and xord is silently ignored.

• xlevels specifies the levels literally, either a character vector of level names in the desired order (e.g., c("C", "B", "A")), or a numeric vector of the corresponding level indexes (e.g. 3:1).

• xord instead accepts a keyword or custom function, which then derives the order from the data. Options are:

  • "desc" and "asc" rank the categories by their mean y value, largest or smallest first. (Long forms like "descending" and "increasing" are also accepted.)

  • "minvar" ranks them by variance, lowest first. This needs more than one observation per category, so it does not apply to the usual one-row-per-term coefficient table.

  • "asis" or "rev" permute the existing levels without consulting the data at all. The former takes the categories in the order that they appear in the data, while the latter reverses the current level order.

  • a custom function that determines both the ranking statistic and its direction. The statistic is always sorted ascending, so function(y) -median(y) ranks by median, largest first.

Note that x is only reordered when it is categorical (i.e., factor or character). A numeric x is plotted at its own values and cannot be reordered, so supplying either argument there is ignored with a warning.

Unlike most other plot types, xord defaults to "asis" here rather than NULL: these types are typically used for coefficient plots, where the row order of the data (e.g., the terms of a model) is usually intentional. Set xord = NULL to follow the factor levels instead, matching the other types.

Examples

tinytheme("basic") # filled points & background grid (but not dynamic yet)

#
## Basic coefficient plot(s)

mod = lm(mpg ~ wt * factor(am), mtcars)
coefs = data.frame(names(coef(mod)), coef(mod), confint(mod))
colnames(coefs) = c("term", "est", "lwr", "upr")

# "errorbar" and "pointrange" type convenience strings
tinyplot(est ~ term, ymin = lwr, ymax = upr, data = coefs, type = "errorbar")
tinyplot(est ~ term, ymin = lwr, ymax = upr, data = coefs, type = "pointrange")

# Use `type_errorbar()` to pass extra arguments for customization
tinyplot(est ~ term, ymin = lwr, ymax = upr, data = coefs,
         type = type_errorbar(length = 0.2))

#
## Flipped plots

# For flipped errobar / pointrange plots, it is recommended to use a
# *dynamic* theme for horizontal axis tick labels + appropriate spacing

tinytheme("classic") # or  "clean(2)", "bw", "socviz", "float", ... 
tinyplot(est ~ term, ymin = lwr, ymax = upr, data = coefs, type = "errorbar",
         flip = TRUE)
tinyplot_add(type = "hline", lty = 2) # "hline" b/c flip = TRUE (not vline!)

tinytheme("basic") # back to basic theme for the remaining examples

#
## Dodging groups

models = list(
    "Model A" = lm(mpg ~ wt, data = mtcars),
    "Model B" = lm(mpg ~ wt + cyl, data = mtcars),
    "Model C" = lm(mpg ~ wt + cyl + hp, data = mtcars)
)

models = do.call(
  rbind,
  lapply(names(models), function(m) {
    data.frame(
      model = m,
      term = names(coef(models[[m]])),
      estimate = coef(models[[m]]),
      setNames(data.frame(confint(models[[m]])), c("conf.low", "conf.high"))
    )
  })
)

tinyplot(estimate ~ term | model,
         ymin = conf.low, ymax = conf.high,
         data = models,
         type = type_pointrange(dodge = 0.1))

# Aside 1: relative vs fixed dodge
#  The default dodge position is based on the unique groups (here: models)
#  available to each x value (here: coefficient term). To "fix" the dodge
#  position across all x values, use `fixed.dodge = TRUE`.

tinyplot(estimate ~ term | model,
         ymin = conf.low, ymax = conf.high,
         data = models,
         type = type_pointrange(dodge = 0.1, fixed.dodge = TRUE))

# Aside 2: layering
#  For layering on top of dodged plots, rather pass the dodging arguments
#  through the top-level call if you'd like the dodging behaviour to be
#  inherited automatically by the added layers.

tinyplot(estimate ~ term | model,
         ymin = conf.low, ymax = conf.high,
         data = models,
         type = "pointrange",
         dodge = 0.1, fixed.dodge = TRUE)
tinyplot_add(type = "l", lty = 2)

#
## Handling (long/overlapping) tick labels

# You may face the annoyance of long and/or overlapping tick labels, e.g.
mod2 = lm(mpg ~ 0 + factor(cyl) * factor(am), mtcars)
coefs2 = data.frame(names(coef(mod2)), coef(mod2), confint(mod2))
colnames(coefs2) = c("term", "est", "lwr", "upr")
# (re-usable plot function)
demo_plot = function(...) {
  tinyplot(
    est ~ term, ymin = lwr, ymax = upr,
    data = coefs2,
    type = "errorbar",
    xlab = NA,
    ylab = "MPG (miles per gallon)",
    main = "Impact on fuel efficiency",
    ...
  )
}
demo_plot()

# Here are some useful arguments (strategies) to avoid this annoyance...

# 1) dynamic theme + rotated x-labels
demo_plot(theme = "clean", xaxr = 45)
# 2) dynamic theme + labeller function (here: dictionary w/ newline spacing)
dict = c(
  "factor(cyl)4"             = "Manual\n4 Cyclinders",
  "factor(cyl)6"             = "Manual\n6 Cyclinders",
  "factor(cyl)8"             = "Manual\n8 Cyclinders",
  "factor(am)1"              = "Automatic\n4 Cylinders",
  "factor(cyl)6:factor(am)1" = "Automatic\n6 Cylinders",
  "factor(cyl)8:factor(am)1" = "Automatic\n8 Cylinders"
)
demo_plot(theme = "clean", xaxl = dict)
# 3) dynamic theme + flipped axes
demo_plot(theme = "clean", flip = TRUE)
# 4) any combination of the above, e.g., labeller dictionary + flipped axes
demo_plot(theme = "clean", flip = TRUE, xaxl = dict)

tinytheme() # reset theme