Spineplot and spinogram types

Description

Type function(s) for producing spineplots and spinograms, which are modified versions of histograms or mosaic plots, and particularly useful for visualizing factor variables. Note that tinyplot defaults to type_spineplot() if y is a factor variable.

Usage

type_spineplot(
  breaks = NULL,
  tol.ylab = 0.05,
  off = NULL,
  xlevels = NULL,
  xord = NULL,
  ylevels = NULL,
  yord = NULL,
  col = NULL,
  weights = NULL,
  lighten = FALSE,
  xaxlabels = NULL,
  yaxlabels = NULL
)

Arguments

breaks if the explanatory variable is numeric, this controls how it is discretized. breaks is passed to hist and can be a list of arguments.
tol.ylab convenience tolerance parameter for y-axis annotation. If the distance between two labels drops under this threshold, they are plotted equidistantly.
off vertical offset between the bars (in per cent). It is fixed to 0 for spinograms and defaults to 2 for spine plots.
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 (weighted) frequency, i.e. most or least common first. (Long forms like “descending” and “increasing” are also accepted.)

    • “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). Both arguments are thus ignored for spinograms, which have a (binned) numeric x axis. Each argument defaults to NULL, i.e. keep the existing factor levels.
ylevels, yord as for xlevels / xord above, but for the y variable. Note that y is always coerced to a factor for spineplots and spinograms, so these arguments are always binding if provided. Be aware that a numeric y gives one level per distinct value.
col a vector of fill colors of the same length as levels(y). The default is to call gray.colors.
weights numeric. A vector of frequency weights for each observation in the data. If NULL all weights are implicitly assumed to be 1. If x is already a 2-way table, the weights are ignored.
lighten logical. For grouped spineplots where the y variable is itself the grouping variable (i.e. y == by), should the fills use a lighter, opaque tint of the series colour(s)? Default is FALSE, i.e. the fills use the fully-saturated palette colour(s). (Unlike the other area types such as type_barplot, where lightening is the default, spineplot tiles abut one another with no gap, so the darker saturated fills read better against their matching border colours.) Set to TRUE to opt in to the lighter tint. Note that lighten has no effect on other spineplot displays (single-group or x == by), which always use a sequential shading ramp of the base colour.
xaxlabels, yaxlabels [Deprecated] character vectors for annotation of the x and y axis. Use the top-level xaxl / yaxl arguments instead, which apply consistently across tinyplot types. These two type-specific arguments will be removed in a future release.

Examples

library("tinyplot")

# "spineplot" type convenience string
tinyplot(Species ~ Sepal.Width, data = iris, type = "spineplot")

# Aside: specifying the type is redundant for this example, since tinyplot()
# defaults to "spineplot" if y is a factor (just like base plot).
tinyplot(Species ~ Sepal.Width, data = iris)

# Use `type_spineplot()` to pass extra arguments for customization
tinyplot(
  Species ~ Sepal.Width, data = iris,
  type = type_spineplot(breaks = 4)
)

# Passing custom colors to the y-axis categories
tinyplot(
  Species ~ Sepal.Width, data = iris,
  type = type_spineplot(breaks = 4, col = palette.colors(3, "Pastel 1"))
)

# More idiomatic tinyplot way of drawing the previous plot: use y == by
tinyplot(
  Species ~ Sepal.Width | Species, data = iris,
  type = type_spineplot(breaks = 4),
  palette = "Pastel 1", legend = FALSE
)

## Grouped and faceted spineplots

ttnc = as.data.frame(Titanic)

# Note: The Titanic (ttnc) dataset is pre-tabulated, so we pass its frequency
# counts via the top-level `weights` argument (accepted via non-standard
# evaluation in the formula method).
tinyplot(
  Survived ~ Sex, facet = ~ Class, data = ttnc,
  # type_spineplot(weights = ttnc$Freq), ## same thing but not NSE
  type = "spineplot", weights = Freq
)

# Reorder x and y variable categories either by their character levels or
# numeric indexes. (Here we combine a top-level `weights` with constructor-
# level arguments passed through `type_spineplot()`.)
tinyplot(
  Survived ~ Sex, facet = ~ Class, data = ttnc,
  type = type_spineplot(xlevels = c("Female", "Male"), ylevels = 2:1),
  weights = Freq
)

# For (colour) grouped "by" spineplots, it's visually better to facet too
tinyplot(
  Survived ~ Sex | Class, data = ttnc,
  facet = "by",
  type = "spineplot", weights = Freq
)

# Fancier version. Note the smart inheritance of spacing etc.
tinyplot(
  Survived ~ Sex | Class, data = ttnc,
  facet = "by", facet.args = list(nrow = 1),
  type = "spineplot", weights = Freq,
  theme = "void", axes = "t", lty = 0, legend = FALSE,
  main = "Who survived the Titanic disaster?",
  sub = "Frequencies by boarding class and sex"
)

# Aside: It's possible to use "by" on its own (without faceting), but the
# overlaid result isn't great. We will likely overhaul this behaviour in a
# future version of tinyplot...
tinyplot(Survived ~ Sex | Class, data = ttnc,
  type = "spineplot", weights = Freq, alpha = 0.3
)