Package 'tinyplot'

Description

Main exported function for drawing legends. Supports:

• Inner and outer positioning (with "!" suffix)

• Discrete and continuous (gradient) legends

• Automatic margin adjustment

Usage

draw_legend(
  legend = NULL,
  legend_args = NULL,
  by_dep = NULL,
  lgnd_labs = NULL,
  labeller = NULL,
  type = NULL,
  pch = NULL,
  lty = NULL,
  lwd = NULL,
  col = NULL,
  bg = NULL,
  cex = NULL,
  gradient = FALSE,
  lmar = NULL,
  has_sub = FALSE,
  has_cap = FALSE,
  cap_text = NULL,
  new_plot = TRUE,
  draw = TRUE,
  soma_target = NULL,
  dynmar_title_mar = NULL
)

Arguments

Value

No return value, called for side effect of producing a(n empty) plot with a legend in the margin.

Examples

oldmar = par("mar")

draw_legend(
  legend = "right!", ## default (other options incl, "left(!)", ""bottom(!)", etc.)
  legend_args = list(title = "Key", bty = "o"),
  lgnd_labs = c("foo", "bar"),
  type = "p",
  pch = 21:22,
  col = 1:2
)

# The legend is placed in the outer margin...
box("figure", col = "cyan", lty = 4)
# ... and the plot is proportionally adjusted against the edge of this
# margin.
box("plot")
# You can add regular plot objects per normal now
plot.window(xlim = c(1,10), ylim = c(1,10))
points(1:10)
points(10:1, pch = 22, col = "red")
axis(1); axis(2)
# etc.

# Important: A side effect of draw_legend is that the inner margins have been
# adjusted. (Here: The right margin, since we called "right!" above.)
par("mar")

# To reset you should call `dev.off()` or just reset manually.
par(mar = oldmar)

# Note that the inner and outer margin of the legend itself can be set via
# the `lmar` argument. (This can also be set globally via
# `tpar(lmar = c(inner, outer))`.)
draw_legend(
  legend_args = list(title = "Key", bty = "o"),
  lgnd_labs = c("foo", "bar"),
  type = "p",
  pch = 21:22,
  col = 1:2,
  lmar = c(0, 0.1) ## set inner margin to zero
)
box("figure", col = "cyan", lty = 4)

par(mar = oldmar)

# Continuous (gradient) legends are also supported
draw_legend(
  legend = "right!",
  legend_args = list(title = "Key"),
  lgnd_labs = LETTERS[1:5],
  col = hcl.colors(5),
  gradient = TRUE ## enable gradient legend
)

par(mar = oldmar)

Description

Convenience function for retrieving the graphical parameters (i.e., the full list of tag = value pairs held in par) from either immediately before or immediately after the most recent tinyplot call.

Usage

get_saved_par(when = c("before", "after", "first"))

Arguments

Details

A potential side-effect of tinyplot is that it can change a user's par settings. For example, it may adjust the inner and outer plot margins to make space for an automatic legend; see draw_legend. While it is possible to immediately restore the original par settings upon exit via the tinyplot(..., restore.par = TRUE) argument, this is not the default behaviour. The reason being that we need to preserve the adjusted parameter settings in case users want to add further graphical annotations to their plot (e.g., abline, text, etc.) Nevertheless, it may still prove desirable to recall and reset these original graphical parameters after the fact (e.g., once all these extra annotations have been added). That is the purpose of this get_saved_par function.

Of course, users may prefer to manually capture and reset graphical parameters, as per the standard method described in the par documentation. For example:

op = par(no.readonly = TRUE)  # save current par settings 
# <do lots of (tiny)plotting>
par(op)                       # reset original pars

This standard manual approach may be safer than get_saved_par because it offers more precise control. Specifically, the value of get_saved_par itself will be reset after ever new tinyplot call; i.e. it may inherit an already-changed set of parameters. Users should bear these trade-offs in mind when deciding which approach to use. As a general rule, get_saved_par offers the convenience of resetting the original par settings even if a user forgot to save them beforehand. But one should avoid invoking it after a series of consecutive tinyplot calls.

Finally, note that users can always call dev.off to reset all par settings to their defaults.

Value

A list of par settings.

Examples

#
# Contrived example where we draw a grouped scatterplot with a legend and
# manually add corresponding best fit lines for each group...
#

# First draw the grouped scatterplot
tinyplot(Sepal.Length ~ Petal.Length | Species, iris)

# Preserving adjusted par settings is good for adding elements to our plot
for (s in levels(iris$Species)) {
  abline(
    lm(Sepal.Length ~ Petal.Length, iris, subset = Species==s),
    col = which(levels(iris$Species)==s)
  )
}

# Get saved par from before the preceding tinyplot call (but don't use yet)
sp = get_saved_par("before")

# Note the changed margins will affect regular plots too, which is probably
# not desirable
plot(1:10)

# Reset the original parameters (could use `par(sp)` here)
tpar(sp)
# Redraw our simple plot with our corrected right margin
plot(1:10)

#
# Quick example going the other way, "correcting" for par.restore = TRUE...
#

tinyplot(Sepal.Length ~ Petal.Length | Species, iris, restore.par = TRUE)
# Our added best lines will be wrong b/c of misaligned par
for (s in levels(iris$Species)) {
  abline(
    lm(Sepal.Length ~ Petal.Length, iris, subset = Species==s),
    col = which(levels(iris$Species)==s), lty = 2
  )
}
# grab the par settings from the _end_ of the preceding tinyplot call to fix
tpar(get_saved_par("after"))
# now the best lines are correct
for (s in levels(iris$Species)) {
  abline(
    lm(Sepal.Length ~ Petal.Length, iris, subset = Species==s),
    col = which(levels(iris$Species)==s)
  )
}

# reset again to original saved par settings before exit
tpar(sp)

Description

Function for formatting label appearance, e.g. axis ticks labels. This is what the top-level xaxl and yaxl arguments from tinyplot ultimately get passed to.

Usage

tinylabel(x, labeller = NULL, na.ignore = TRUE, na.rm = TRUE)

Arguments

Value

a character vector of the same length as x with the transformed labels.

See Also

tinyplot

Examples

x = 1e4
tinylabel(x, "comma")
tinylabel(x, ",") # same
tinylabel(x, "$") # or "dollar"

# invoke tinylabel from a parent tinyplot call...
#   => x/yaxl for adjusting axes tick labels
#   => legend = list(labeller = ...) for adjusting the legend labels
s77 = transform(data.frame(state.x77), Illiteracy = Illiteracy / 100)
tinyplot(Life.Exp ~ Income | Illiteracy, data = s77,
         xaxl = '$',
         legend = list(labeller = '%'))

# log example (combined with axis scaling)
tinyplot(x = 10^c(10:0), y = 0:10, type = "b",
         log = "x", xaxl = "log")

# combine with `x/yaxb` to adjust the actual tick marks ("break points")
# at the same time
tinyplot(x = 10^c(10:0), y = 0:10, type = "b",
         log = "x", xaxl = "log", xaxb = 10^c(1,3,5,7,9))

#
## custom function examples

## example I: date formatting

dat = data.frame(
  date = seq(as.Date("2000/1/1"), by = "month", length.out = 12),
  trend = 1:12 + rnorm(12, sd = 1)
)

tinyplot(trend ~ date, data = dat,
         xaxl = function(x) format(x, "%b, %Y"))

## example II: string wrapping

# create a "vectorised" version of `base::strwrap` that breaks long
# strings into new lines every 18 characters
strwrap18 = function(x) sapply(
  strwrap(x, width = 18, simplify = FALSE),
  paste,
  collapse = "\n"
)

# now demonstrate on a dataset with long y-tick labels
dat2 = data.frame(
  x = rep(rnorm(100), 3),
  y = c(
    "tinyplot is a lightweight extension of the base R graphics system.",
    "R is a language for statistical computing.",
    "Data visualization is an essential skill."
  )
)

tinyplot(y ~ x, data = dat2, type = "j",
         yaxl = strwrap18,
         theme = "bw") # use theme for horizontal labels + dynamic margin

Description

Enhances the base plot function. Supported features include automatic legends and facets for grouped data, additional plot types, theme customization, and so on. Users can call either tinyplot(), or its shorthand alias plt().

Usage

tinyplot(x, ...)

## Default S3 method:
tinyplot(
  x = NULL,
  y = NULL,
  xmin = NULL,
  xmax = NULL,
  ymin = NULL,
  ymax = NULL,
  by = NULL,
  facet = NULL,
  facet.args = NULL,
  data = NULL,
  type = NULL,
  legend = NULL,
  main = NULL,
  sub = NULL,
  cap = NULL,
  xlab = NULL,
  ylab = NULL,
  ann = par("ann"),
  xlim = NULL,
  ylim = NULL,
  axes = TRUE,
  xaxt = NULL,
  yaxt = NULL,
  xaxs = NULL,
  yaxs = NULL,
  xaxb = NULL,
  yaxb = NULL,
  xaxl = NULL,
  yaxl = NULL,
  log = "",
  flip = FALSE,
  frame.plot = NULL,
  grid = NULL,
  palette = NULL,
  pch = NULL,
  lty = NULL,
  lwd = NULL,
  col = NULL,
  bg = NULL,
  fill = NULL,
  alpha = NULL,
  cex = NULL,
  add = FALSE,
  draw = NULL,
  empty = FALSE,
  restore.par = FALSE,
  file = NULL,
  width = NULL,
  height = NULL,
  asp = NA,
  theme = NULL,
  ...
)

## S3 method for class 'formula'
tinyplot(
  x = NULL,
  data = parent.frame(),
  facet = NULL,
  facet.args = NULL,
  type = NULL,
  xmin = NULL,
  xmax = NULL,
  ymin = NULL,
  ymax = NULL,
  xlim = NULL,
  ylim = NULL,
  main = NULL,
  sub = NULL,
  cap = NULL,
  xlab = NULL,
  ylab = NULL,
  ann = par("ann"),
  axes = TRUE,
  frame.plot = NULL,
  asp = NA,
  grid = NULL,
  pch = NULL,
  col = NULL,
  lty = NULL,
  lwd = NULL,
  restore.par = FALSE,
  formula = NULL,
  subset = NULL,
  na.action = NULL,
  drop.unused.levels = TRUE,
  ...
)

## S3 method for class 'density'
tinyplot(x = NULL, type = c("l", "area"), ...)

plt(x, ...)

Arguments

Details

Disregarding the enhancements that it supports, tinyplot tries as far as possible to mimic the behaviour and syntax logic of the original base plot function. Users should therefore be able to swap out existing plot calls for tinyplot (or its shorthand alias plt), without causing unexpected changes to the output.

Value

No return value, called for side effect of producing a plot.

Examples

aq = transform(
  airquality,
  Month = factor(Month, labels = month.abb[unique(Month)])
)

# In most cases, `tinyplot` should be a drop-in replacement for regular
# `plot` calls. For example:

op = tpar(mfrow = c(1, 2))
plot(0:10, main = "plot")
tinyplot(0:10, main = "tinyplot")
tpar(op) # restore original layout

# Aside: `tinyplot::tpar()` is a (near) drop-in replacement for `par()`

# Unlike vanilla plot, however, tinyplot allows you to characterize groups
# using either the `by` argument or equivalent `|` formula syntax.

with(aq, tinyplot(Day, Temp, by = Month)) ## atomic method
tinyplot(Temp ~ Day | Month, data = aq) ## formula method

# (Notice that we also get an automatic legend.)

# You can also use the equivalent shorthand `plt()` alias if you'd like to
# save on a few keystrokes

plt(Temp ~ Day | Month, data = aq) ## shorthand alias

# Use standard base plotting arguments to adjust features of your plot.
# For example, change `pch` (plot character) to get filled points and `cex`
# (character expansion) to increase their size.

tinyplot(
  Temp ~ Day | Month,
  data = aq,
  pch = 16,
  cex = 2
)

# Use the special "by" convenience keyword if you would like to map these
# aesthetic features over groups too (i.e., in addition to the default
# colour grouping)

tinyplot(
  Temp ~ Day | Month,
  data = aq,
  pch = "by",
  cex = "by"
)

# We can add alpha transparency for overlapping points

tinyplot(
  Temp ~ Day | Month,
  data = aq,
  pch = 16,
  cex = 2,
  alpha = 0.3
)

# To get filled points with a common solid background color, use an
# appropriate plotting character (21:25) and combine with one of the special
# `bg`/`fill` convenience arguments.
tinyplot(
  Temp ~ Day | Month,
  data = aq,
  pch = 21, # use filled circles
  cex = 2,
  bg = 0.3, # numeric in [0,1] adds a grouped background fill with transparency
  col = "black" # override default color mapping; give all points a black border
)

# Aside: For "bubble" plots, pass an appropriate vector to the `cex` arg.
# This can be useful for depicting an additional dimension of the data (here:
# Wind).
tinyplot(
  Temp ~ Day | Month,
  data = aq,
  pch = 21,
  cex = aq$Wind, # map character size to another feature in the data
  bg = 0.3,
  col = "black"
)

# Converting to a grouped line plot is a simple matter of adjusting the
# `type` argument.

tinyplot(
  Temp ~ Day | Month,
  data = aq,
  type = "l"
)

# Similarly for other plot types, including some additional ones provided
# directly by tinyplot, e.g. density plots or internal plots (ribbons,
# pointranges, etc.)

tinyplot(
  ~ Temp | Month,
  data = aq,
  type = "density",
  fill = "by"
)

# Facet plots are supported too. Facets can be drawn on their own...

tinyplot(
  Temp ~ Day,
  facet = ~Month,
  data = aq,
  type = "area",
  main = "Temperatures by month"
)

# ... or combined/contrasted with the by (colour) grouping.

aq = transform(aq, Summer = Month %in% c("Jun", "Jul", "Aug"))
tinyplot(
  Temp ~ Day | Summer,
  facet = ~Month,
  data = aq,
  type = "area",
  palette = "dark2",
  main = "Temperatures by month and season"
)

# Users can override the default square window arrangement by passing `nrow`
# or `ncol` to the helper facet.args argument. Note that we can also reduce
# axis label repetition across facets by turning the plot frame off.

tinyplot(
  Temp ~ Day | Summer,
  facet = ~Month, facet.args = list(nrow = 1),
  data = aq,
  type = "area",
  palette = "dark2",
  frame = FALSE,
  main = "Temperatures by month and season"
)

# Use a two-sided formula to arrange the facet windows in a fixed grid.
# LHS -> facet rows; RHS -> facet columns

aq$hot = ifelse(aq$Temp >= 75, "hot", "cold")
aq$windy = ifelse(aq$Wind >= 15, "windy", "calm")
tinyplot(
  Temp ~ Day,
  facet = windy ~ hot,
  data = aq
)

# To add common elements to each facet, use the `draw` argument

tinyplot(
  Temp ~ Day,
  facet = windy ~ hot,
  data = aq,
  draw = abline(h = 75, lty = 2, col = "hotpink")
)

# The (automatic) legend position and look can be customized using
# appropriate arguments. Note the trailing "!" in the `legend` position
# argument below. This tells `tinyplot` to place the legend _outside_ the plot
# area.

tinyplot(
  Temp ~ Day | Month,
  data = aq,
  type = "l",
  legend = legend("bottom!", title = "Month of the year", bty = "o")
)

# Use legend = "direct" to place text labels at the last point of each
# group's data, coloured to match. Best suited to line-based plots with
# x-sorted data, where "last" corresponds to "rightmost". The right
# margin is automatically expanded to fit the labels. Pairs well with
# dynamic themes for tighter margins overall.

tinyplot(
  Temp ~ Day | Month,
  data = aq,
  type = "l",
  legend = "direct",
  theme = "clean2"
)

# Use `nudge_x/y`` to manually adjust label positions, or `repel` to
# auto-separate overlapping labels:
tinyplot(
  Temp ~ Day | Month,
  data = aq,
  type = "l",
  legend = legend("direct", nudge_y = c(May = -1, Jun = 2)),
  # legend = legend("direct", repel = TRUE), # another option
  theme = "clean2"
)

# The default group colours are inherited from either the "R4" or "Viridis"
# palettes, depending on the number of groups. However, all palettes listed
# by `palette.pals()` and `hcl.pals()` are supported as convenience strings,
# or users can supply a valid palette-generating function for finer control

tinyplot(
  Temp ~ Day | Month,
  data = aq,
  type = "l",
  palette = "tableau"
)

# It's possible to customize the look of your plots by setting graphical
# parameters (e.g., via `(t)par`)... But a more convenient way is to just use
# built-in themes (see `?tinytheme`).

tinyplot(
  Temp ~ Day | Month,
  data = aq,
  type = "b",
  alpha = 0.5,
  main = "Daily temperatures by month",
  sub = "Brought to you by tinyplot",
  cap = "Source: Base R airquality dataset",
  theme = "clean2"
)

# For more examples and a detailed walkthrough, please see the introductory
# tinyplot tutorial available online:
# https://grantmcdermott.com/tinyplot/vignettes/introduction.html

Description

This convenience function grabs the preceding tinyplot call and updates it with any new arguments that have been explicitly provided by the user. It then injects add=TRUE and evaluates the updated call, thereby drawing a new layer on top of the existing plot. plt_add() is a shorthand alias for tinyplot_add().

Usage

tinyplot_add(...)

plt_add(...)

Arguments

Value

No return value, called for side effect of producing a plot.

Limitations

• tinyplot_add() works reliably only when adding to a plot originally created using the tinyplot.formula method with a valid data argument. We cannot guarantee correct behavior if the original plot was created with the atomic tinyplot.default method, due to potential environment mismatches. (An exception is when the original plot arguments—x, y, etc.—are located in the global environment.)

• Automatic legends for the added elements will be turned off.

Examples

tinyplot(Sepal.Width ~ Sepal.Length | Species,
  facet = ~Species,
  data = iris)

tinyplot_add(type = "lm") ## or : plt_add(type = "lm")

## Note: the previous function is equivalent to (but much more convenient
## than) re-writing the full call with the new type and `add=TRUE`:

# tinyplot(Sepal.Width ~ Sepal.Length | Species,
#          facet = ~Species,
#          data = iris,
#          type = "lm",
#          add = TRUE)

Description

The tinytheme function sets or resets the theme for plots created with tinyplot. Themes control the appearance of plots, such as text alignment, font styles, axis labels, and even dynamic margin adjustment to reduce whitespace.

Usage

tinytheme(
  theme = c("default", "basic", "dynamic", "clean", "clean2", "bw", "linedraw",
    "classic", "minimal", "ipsum", "ipsum2", "dark", "socviz", "broadsheet", "nber",
    "web", "ridge", "ridge2", "tufte", "float", "void"),
  ...
)

Arguments

Details

Sets a list of graphical parameters using tpar()

Persistent vs. ephemeral themes. Calling tinytheme("<theme>") triggers a persistent theme, which will be applied to all subsequent graphics (incl. base plot). To reset the theme to your default settings, call tinytheme() without arguments. Alternatively, invoke the ⁠tinyplot(..., theme = <theme>)⁠ argument for an ephemeral theme that is automatically reset at the end of the plot call.

# Set a persistent theme
tinytheme("clean")
tinyplot(1:10)  # uses "clean"
tinyplot(10:1)  # still uses "clean"
tinytheme()     # reset to default

# Use an ephemeral theme for a single plot (incl. added components)
tinyplot(1:10, theme = "dark")  # uses "dark" ephemerally
tinyplot_add(type = "S")        # same plot, so retains theme
tinyplot(10:1)                  # new plot, so back to default

Custom overrides. To customize a theme's parameters (e.g., mar, las, etc.), either pass them directly as additional args to ⁠tinytheme(<theme>, ...)⁠ or as a list arguments to ⁠tinyplot(..., theme = list(<theme>, ...))⁠. Please note that passing overrides through tpar() or par() won't work, because themes work by installing a persistent hook, which means that an active theme will override any subsequent calls for parameters that the theme controls.

# Do this
tinytheme("clean", mar = c(5, 5, 2, 2))
<some plot>

# Or this (ephemeral version)
tinyplot(..., theme = list("clean", mar = c(5, 5, 2, 2)))

# Don't do this (the theme hook will overwrite your changes)
tinytheme("clean")
tpar(mar = c(5, 5, 2, 2))
<some plot>

Spacing primitives. Dynamic themes compute mgp (margin line positions) automatically from two spacing primitives, rather than requiring users to reason about how mar, mgp, and tcl combine:

• gap.axis: the gap in margin lines between the tick tip and the near edge of the tick label. Default 0.2.

• gap.lab: the gap in margin lines between the far edge of the tick label and the near edge of the axis title. Default 1.0.

These primitives scale automatically with cex.axis and cex.lab, so the visible spacing between elements remains constant regardless of text size. To adjust spacing, pass them as overrides:

# Tighter spacing between tick labels and axis titles
tinytheme("clean", gap.lab = 0.5)

# More room between ticks and tick labels
tinytheme("clean", gap.axis = 0.5)

If you supply an explicit mgp value, it is used as-is and the primitives are ignored.

Value

The function returns nothing. It is called for its side effects.

See Also

tpar which does the heavy lifting under the hood.

Examples

# Reusable plot function
p = function() tinyplot(
  lat ~ long | depth, data = quakes,
  main = "Earthquakes off Fiji",
  sub = "Data courtesy of the Harvard PRIM-H project"
)
p()

# Set a theme
tinytheme("dark")
p()

#  A set theme is persistent and will apply to subsequent plots
tinyplot(0:10)

# Try a different theme
tinytheme("clean")
p()
         
# Customize the theme by overriding default settings
tinytheme("clean",
          adj.xlab = 1, adj.ylab = 1,
          cex.lab = 0.75, cex.axis = 0.9,
          font.sub = 3,
          gap.axis = 0, gap.lab = 0.5,
          tcl = -0.1)
p()

# Another custom theme example, including a different font
tinytheme("bw", font.main = 2, col.axis = "darkcyan", family = "HersheyScript")
p()

# Aside: One or two specialized themes are only meant for certain plot types
tinytheme("ridge2")
tinyplot(I(cut(lat, 10)) ~ depth, data = quakes, type = "ridge")

# Reset the theme
tinytheme()
p()

# For an ephemeral theme, use `tinyplot(..., theme = <theme>)` directly
tinyplot(0:10, theme = "clean", main = "This theme is ephemeral")
tinyplot(10:0, main = "See, no more theme")

# Customize an ephemeral theme by passing arguments as a list
tinyplot(0:10, main = "Custom", theme = list("clean", grid.col = "hotpink"))

# Themes showcase
## We'll use a slightly more intricate plot (long y-axis labs and facets)
## to demonstrate dynamic margin adjustment etc.

thms = eval(formals(tinytheme)$theme)

for (thm in thms) {
  tinytheme(thm)
  tinyplot(
    I(Sepal.Length*1e4) ~ Petal.Length | Species, facet = "by", data = iris,
    yaxl = ",", 
    main = paste0('tinytheme("', thm, '")'),
    sub = "A subtitle",
    cap = "A caption"
  )
  box("outer", lty = 2)
}

# Reset
tinytheme()

Description

Extends par, serving as a (near) drop-in replacement for setting or querying graphical parameters. The key differences is that, beyond supporting the standard group of R graphical parameters in par, tpar also supports additional graphical parameters that are provided by tinyplot. Similar to par, parameters are set by passing appropriate key = value argument pairs, and multiple parameters can be set or queried at the same time.

Usage

tpar(..., hook = FALSE)

Arguments

Details

The tinyplot-specific parameters are saved in an internal environment called .tpar for performance and safety reasons. However, they can also be set at package load time via options, which may prove convenient for users that want to enable different default behaviour at startup (e.g., through an .Rprofile file). These options all take a ⁠tinyplot_*⁠ prefix, e.g. options(tinyplot_grid = TRUE, tinyplot_facet.bg = "grey90").

For their part, any "base" graphical parameters are caught dynamically and passed on to par as appropriate. Technically, only parameters that satisfy par(..., no.readonly = TRUE) are evaluated.

However, note the important distinction: tpar only evaluates parameters from par if they are passed explicitly by the user. This means that tpar should not be used to capture the (invisible) state of a user's entire set of graphics parameters, i.e. tpar() != par(). If you want to capture the all existing graphics settings, then you should rather use par() instead.

Value

When parameters are set, their previous values are returned in an invisible named list. Such a list can be passed as an argument to tpar to restore the parameter values.

When just one parameter is queried, the value of that parameter is returned as (atomic) vector. When two or more parameters are queried, their values are returned in a list, with the list names giving the parameters.

Note the inconsistency: setting one parameter returns a list, but querying one parameter returns a vector.

Additional Graphical Parameters

• adj.cap: Numeric value between 0 and 1 controlling the alignment of the plot caption. Defaults to 0.5 (centered) for the default theme, and 1 (right-aligned) for all other themes.

• adj.xlab: Numeric value between 0 and 1 controlling the alignment of the x-axis label.

• adj.ylab: Numeric value between 0 and 1 controlling the alignment of the y-axis label.

• cairo: Logical indicating whether cairo_pdf should be used when writing plots to PDF. If FALSE, then pdf will be used instead, with implications for embedding (non-standard) fonts. Only used if tinyplot(..., file = "<filename>.pdf") is called. Defaults to the value of capabilities("cairo").

• cex.cap: Numeric expansion factor for the plot caption text. Defaults to 1 for the default, basic, and dynamic themes, and 0.8 for clean/classic and their descendants.

• col.cap: Character specifying the colour of the plot caption. Defaults to "black".

• font.cap: Integer specifying the font face for the plot caption (1 = plain, 2 = bold, 3 = italic, 4 = bold italic). Defaults to 1.

• line.cap: Numeric specifying the margin line on which to draw the caption. If NULL (default), computed automatically based on the available bottom margin.

• dynmar: Logical indicating whether tinyplot should attempt dynamic adjustment of margins to reduce whitespace and/or account for spacing of text elements (e.g., long horizontal y-axis labels). Note that this parameter is tightly coupled to internal tinythemes() logic and should not be adjusted manually unless you really know what you are doing or don't mind risking unintended consequences to your plot.

• facet.bg: Character or integer specifying the facet background colour. If an integer, will correspond to the user's default colour palette (see palette). Passed to rect. Defaults to NULL (none).

• facet.border: Character or integer specifying the facet border colour. If an integer, will correspond to the user's default colour palette (see palette). Passed to rect. Defaults to NA (none).

• facet.cex: Expansion factor for facet titles. Defaults to 1.

• facet.col: Character or integer specifying the facet text colour. If an integer, will correspond to the user's default global colour palette (see palette). Defaults to NULL, which is equivalent to "black".

• facet.font: An integer corresponding to the desired font face for facet titles. For most font families and graphics devices, one of four possible values: 1 (regular), 2 (bold), 3 (italic), or 4 (bold italic). Defaults to NULL, which is equivalent to 1 (i.e., regular).

• file.height: Numeric specifying the height (in inches) of any plot that is written to disk using the tinyplot(..., file = X) argument. Defaults to 7.

• file.res: Numeric specifying the resolution (in dots per square inch) of any plot that is written to disk in bitmap format (i.e., PNG or JPEG) using the tinyplot(..., file = X) argument. Defaults to 300.

• file.width: Numeric specifying the width (in inches) of any plot that is written to disk using the tinyplot(..., file = X) argument. Defaults to 7.

• fmar: A numeric vector of form c(b,l,t,r) for controlling the (base) margin padding, in terms of lines, between the individual facets in a faceted plot. Defaults to c(1,1,1,1). If more than three facets are detected, the fmar parameter is scaled by 0.75 to reduce excess whitespace. For 2x2 plots, the padding better matches the cex expansion logic of base graphics.

• gap.main: Numeric giving the gap (in margin lines) from the main title baseline to the element below it (plot box when no subtitle; subtitle top when subtitle is present). Only used when dynmar = TRUE. Defaults to 0.7.

• gap.sub: Numeric giving the gap (in margin lines) from the subtitle baseline to the plot box. Only used when dynmar = TRUE and side.sub = 3. Defaults to 0.7.

• grid.col: Character or (integer) numeric that specifies the color of the panel grid lines. Defaults to "lightgray".

• grid.lty: Character or (integer) numeric that specifies the line type of the panel grid lines. Defaults to "dotted".

• grid.lwd: Non-negative numeric giving the line width of the panel grid lines. Defaults to 1.

• grid: Logical or character indicating whether a background panel grid should be added to plots automatically. Defaults to NULL, which is equivalent to FALSE. In addition to logical values, a character string can be used to control axis-specific grids: uppercase letters ("X", "Y", "XY") draw grid lines at the standard axis tick positions (equivalent to TRUE), while lowercase letters ("x", "y", "xy") draw a finer grid with additional lines at the midpoints between ticks.

• lmar: A numeric vector of form c(inner, outer) that gives the margin padding, in terms of lines, around the automatic tinyplot legend. Defaults to c(1.0, 0.1). The inner margin is the gap between the legend and the plot region, and the outer margin is the gap between the legend and the edge of the graphics device.

• palette.qualitative: Palette for qualitative colors. See the palette argument in ?tinyplot.

• palette.sequential: Palette for sequential colors. See the palette argument in ?tinyplot.

• ribbon.alpha: Numeric factor in the range ⁠[0,1]⁠ for modifying the opacity alpha of "ribbon" and "area" type plots. Default value is 0.2.

See Also

graphics::par which tpar builds on top of. get_saved_par is a convenience function for retrieving graphical parameters at different stages of a tinyplot call (and used for internal accounting purposes). tinytheme allows users to easily set a group of graphics parameters in a single function call, according to a variety of predefined themes.

Examples

# Return a list of existing base and tinyplot graphic params
tpar("las", "pch", "facet.bg", "facet.cex", "grid")

# Simple facet plot with these default values
tinyplot(mpg ~ wt, data = mtcars, facet = ~am)

# Set params to something new. Similar to graphics::par(), note that we save
# the existing values at the same time by assigning to an object.
op = tpar(
  las       = 1,
  pch       = 2,
  facet.bg  = "grey90",
  facet.cex = 2,
  grid      = TRUE
)

# Re-plot with these new params
tinyplot(mpg ~ wt, data = mtcars, facet = ~am)

# Reset back to original values
tpar(op)

# Important: tpar() only evalutes parameters that have been passed explicitly
#   by the user. So it it should not be used to query and set (restore)
#   parameters that weren't explicitly requested, i.e. tpar() != par().

# Note: The tinyplot-specific parameters can also be be set via `options`
#   with a `tinyplot_*` prefix, which can be convenient for enabling
#   different default behaviour at startup time (e.g., via an .Rprofile
#   file). Example:
# options(tinyplot_grid = TRUE, tinyplot_facet.bg = "grey90")

Description

These functions add straight line(s) through the current plot.

Usage

type_abline(a = 0, b = 1)

type_hline(h = 0)

type_vline(v = 0)

Arguments

Details

While type_abline, type_hline, and type_vline can be called in a base plot layer, we expect that they will typically be called as subsequent layers via tinyplot_add.

Recycling logic

The recycling behaviour of the line parameters (i.e., a, b, h, or v) is adaptive, depending on whether by or facet grouping is detected. While this leads to different recycling scenarios, the underlying code logic follows sensible heuristics designed to match user expectations.

Parameter lengths must equal one of four options:

1. Single value (i.e., length = 1), i.e. simplest case where the same line is applied uniformly across all groups and facets. Uses the default user colour (e.g. "black", or tpar("palette.qualitative")[1] if a theme is set).

2. Number of by groups, i.e. one parameter per group. For example, tinyplot(mpg ~ wt | factor(cyl), data = mtcars, type = type_hline(h = 21:23)) will give three horizontal lines, with colours matching the user's qualitative palette.

3. Number of facet groups, i.e. one parameter per facet panel. For example: tinyplot(mpg ~ wt, facet = ~am, data = mtcars, type = type_hline(h = c(20,30))) would give separate horizontal lines per facet, but both using the same default color.

4. Product of by and facet groups, i.e. one parameter for each unique by-facet combination. Orders over facets first and then, within that, by group. For example: tinyplot(mpg ~ wt | factor(cyl), facet = ~am, data = mtcars, type = type_hline(h = 21:26)) will give six separate lines, with the first three (21:23) coloured by group in the first facet, and second three (24:26) coloured by by group in the second facet.

Alongside these general rules, we also try to accomodate special cases when other aesthetic parameters like lwd or lty are invoked by the user. See Examples.

Examples

#
## abline

tinyplot(x = -10:10, y = rnorm(21) + -10:10, grid = TRUE)
tinyplot_add(type = "abline")
# same as...
# tinyplot_add(type = type_abline(a = 0, b = 1))

# customize by passing bespoke intercept and slope values
tinyplot_add(type = type_abline(a = -1, b = -0.5))

# note that calling as abline & co. as a base plot layer will still lead to
# axes limits that respect the range of the data
tinyplot(x = -10:10, y = -10:10, grid = TRUE, type = "abline")

#
## hline and vline

# Base plot layer
tinyplot(mpg ~ hp | cyl, facet = "by", data = mtcars, ylim = c(0, 40))

# Add horizontal lines at the (default) 0 y-intercept
tinyplot_add(type = "hline", col = "grey")

# Note that group+facet aesthetics will be inherited. We can use this to
# add customized lines (here: the mean `mpg` for each `cyl` group)
tinyplot_add(type = type_hline(with(mtcars, tapply(mpg, cyl, mean))), lty = 2)

# Similar idea for vline
tinyplot_add(type = type_vline(with(mtcars, tapply(hp, cyl, mean))), lty = 2)

#
## Recycling logic

# length(h) == no. of groups
tinyplot(mpg ~ wt | factor(cyl), data = mtcars, type = type_hline(h = 21:23))

# length(h) == no. of facets
tinyplot(mpg ~ wt, facet = ~am, data = mtcars, type = type_hline(h = c(20, 30)))

# length(h) == no. of groups x no. of facets
tinyplot(mpg ~ wt | factor(cyl),
  facet = ~am, data = mtcars,
  type = type_hline(h = 21:26))

# special adjustment case (here: lwd by group)
tinyplot(mpg ~ wt | factor(cyl),
  facet = ~am, data = mtcars,
  type = type_hline(c(20, 30)), lwd = c(21, 14, 7))

Description

Type constructor functions for producing polygon ribbons, which define a y interval (usually spanning from ymin to ymax) for each x value. Area plots are a special case of ribbon plot where ymin is set to 0 and ymax is set to y.

Usage

type_area(alpha = NULL)

type_ribbon(alpha = NULL, dodge = 0, fixed.dodge = FALSE)

Arguments

Dodging ribbon plots

We support dodging for grouped ribbon plots, enabling similar functionality to dodged errorbar and pointrange plots. However, it is strongly recommended that dodging is only implemented for cases where the x-axis comprises a limited number of discrete cases (e.g., coefficient or event-study plots). See Examples.

Examples

x = 1:100 / 10
y = sin(x)

#
## Ribbon plots

# "ribbon" convenience string
tinyplot(x = x, ymin = y - 1, ymax = y + 1, type = "ribbon")
# Same result with type_ribbon()
tinyplot(x = x, ymin = y-1, ymax = y+1, type = type_ribbon())

# y will be added as a line if it is specified
tinyplot(x = x, y = y, ymin = y-1, ymax = y+1, type = "ribbon")

#
## Area plots

# "area" type convenience string
tinyplot(x, y, type = "area")

# Same result with type_area()
tinyplot(x, y, type = type_area())

# Area plots are often used for time series charts
tinyplot(AirPassengers, type = "area")

#
## Dodged ribbon/area plots

# Dodged ribbon or area plots can be useful in cases where there is strong
# overlap across groups (and a limited number of discrete x-axis values).

dat = data.frame(
  x = rep(c("Before", "After"), each = 2),
  grp = rep(c("A", "B"), 2),
  y = c(10, 10.5, 15, 15.3),
  lwr = c(8, 8.5, 13, 13.3),
  upr = c(12, 12.5, 17, 17.3)
)

tinyplot(
  y ~ x | grp,
  data = dat,
  ymin = lwr, ymax = upr,
  type = type_ribbon(),
  main = "Overlappling ribbons"
)

tinyplot(
  y ~ x | grp,
  data = dat,
  ymin = lwr, ymax = upr,
  type = type_ribbon(dodge = 0.1),
  main = "Dodged ribbons"
)

Description

Type function for producing barplots. For formulas of type ~ x (without left-hand side) the barplot visualizes the counts (absolute frequencies) of the levels of x. For formulas of type y ~ x the value of y within each level of x is visualized, if necessary aggregated using some function (default: mean).

Usage

type_barplot(
  width = 5/6,
  beside = FALSE,
  center = FALSE,
  FUN = NULL,
  xlevels = NULL,
  xaxlabels = NULL,
  drop.zeros = FALSE
)

Arguments

Examples

# Basic examples of frequency tables (without y variable)
tinyplot(~ cyl, data = mtcars, type = "barplot")
tinyplot(~ cyl | vs, data = mtcars, type = "barplot")
tinyplot(~ cyl | vs, data = mtcars, type = "barplot", beside = TRUE)
tinyplot(~ cyl | vs, data = mtcars, type = "barplot", beside = TRUE, fill = 0.2)

# Reorder x variable categories either by their character levels or numeric indexes
tinyplot(~ cyl, data = mtcars, type = "barplot", xlevels = c("8", "6", "4"))
tinyplot(~ cyl, data = mtcars, type = "barplot", xlevels = 3:1)

# Note: Above we used automatic argument passing for `beside`. But this
# wouldn't work for `width`, since it would conflict with the top-level
# `tinyplot(..., width = <width>)` argument. It's safer to pass these args
# through the `type_barplot()` functional equivalent.
tinyplot(~ cyl | vs, data = mtcars, fill = 0.2,
  type = type_barplot(beside = TRUE, drop.zeros = TRUE, width = 0.65))

tinytheme("clean2")

# Example for numeric y aggregated by x (default: FUN = mean) + facets
tinyplot(extra ~ ID | group, facet = "by", data = sleep,
  type = "barplot", fill = 0.6)

# Fancy frequency table:
tinyplot(Freq ~ Sex | Survived, facet = ~ Class, data = as.data.frame(Titanic),
  type = "barplot", facet.args = list(nrow = 1), flip = TRUE, fill = 0.6)

# Centered barplot for conditional proportions of hair color (black/brown vs.
# red/blond) given eye color and sex
tinytheme("clean2", palette.qualitative = c("black", "sienna", "indianred", "goldenrod"))
hec = as.data.frame(proportions(HairEyeColor, 2:3))
tinyplot(Freq ~ Eye | Hair, facet = ~ Sex, data = hec, type = "barplot",
  center = TRUE, flip = TRUE, facet.args = list(ncol = 1), yaxl = "percent")

tinytheme()

Description

Type function for producing box-and-whisker plots. Arguments are passed to boxplot, although tinyplot scaffolding allows added functionality such as grouping and faceting. Box-and-whisker plots are the default plot type if x is a factor and y is numeric.

Usage

type_boxplot(
  range = 1.5,
  width = NULL,
  varwidth = FALSE,
  notch = FALSE,
  outline = TRUE,
  boxwex = 0.8,
  staplewex = 0.5,
  outwex = 0.5
)

Arguments

Examples

# "boxplot" type convenience string
tinyplot(count ~ spray, data = InsectSprays, type = "boxplot")

# Note: Specifying the type here is redundant. Like base plot, tinyplot
# automatically produces a boxplot if x is a factor and y is numeric
tinyplot(count ~ spray, data = InsectSprays)

# Grouped boxplot example
tinyplot(len ~ dose | supp, data = ToothGrowth, type = "boxplot")

# Use `type_boxplot()` to pass extra arguments for customization
tinyplot(
  len ~ dose | supp, data = ToothGrowth, lty = 1,
  type = type_boxplot(boxwex = 0.3, staplewex = 0, outline = FALSE)
)

Description

Type function for drawing convex hulls around grouped points. Uses chull to compute the convex hull of each group and draws the result as a polygon.

Usage

type_chull(density = NULL, angle = 45)

Arguments

Examples

# "chull" type convenience character string
tinyplot(Sepal.Length ~ Petal.Length | Species, data = iris, type = "chull")

# layer filled convex hull(s) on top of points
tinyplot(Sepal.Length ~ Petal.Length | Species, data = iris, theme = "basic")
tinyplot_add(type = "chull", fill = 0.2)

Description

Type function for density plots.

Usage

type_density(
  bw = "nrd0",
  joint.bw = c("mean", "full", "none"),
  adjust = 1,
  kernel = c("gaussian", "epanechnikov", "rectangular", "triangular", "biweight",
    "cosine", "optcosine"),
  n = 512,
  alpha = NULL
)

Arguments

Details

The algorithm used in density.default disperses the mass of the empirical distribution function over a regular grid of at least 512 points and then uses the fast Fourier transform to convolve this approximation with a discretized version of the kernel and then uses linear approximation to evaluate the density at the specified points.

The statistical properties of a kernel are determined by $\sigma^2_K = \int t^2 K(t) dt$ which is always $= 1$ for our kernels (and hence the bandwidth bw is the standard deviation of the kernel) and $R(K) = \int K^2(t) dt$.
MSE-equivalent bandwidths (for different kernels) are proportional to $\sigma_K R(K)$ which is scale invariant and for our kernels equal to $R(K)$. This value is returned when give.Rkern = TRUE. See the examples for using exact equivalent bandwidths.

Infinite values in x are assumed to correspond to a point mass at +/-Inf and the density estimate is of the sub-density on (-Inf, +Inf).

Bandwidth selection

While the choice of smoothing bandwidth will always stand to affect a density visualization, it gains an added importance when multiple densities are drawn simultaneously (e.g., for subgroups with respect to by or facet). Allowing each subgroup to compute its own separate bandwidth independently offers greater flexibility in capturing the unique characteristics of each subgroup, particularly when distributions differ substantially in location and/or scale. However, this approach may overemphasize small random variations and make it harder to visually compare densities across subgroups. Hence, it is often useful to employ the same ("joint") bandwidth across all subgroups. The following strategies are available via the joint.bw argument:

• The default joint.bw = "mean" first computes the individual bandwidths for each group but then computes their mean, weighted by the number of observations in each group. This will work well when all groups have similar amounts of scatter (similar variances), even when they have potentially rather different locations. The weighted averaging stabilizes potential fluctuations in the individual bandwidths, especially when some subgroups are rather small.

• Alternatively, joint.bw = "full" can be used to compute the joint bandwidth from the full joint distribution (merging all groups). This will yield an even more robust bandwidth, especially when the groups overlap substantially (i.e., have similar locations and scales). However, it may lead to too large bandwidths and thus too much smoothing, especially when the locations of the groups differ substantially.

• Finally, joint.bw = "none" disables the joint bandwidth so that each group just employs its individual bandwidth. This is often the best choice if the amounts of scatter differ substantially between the groups, thus necessitating different amounts of smoothing.

Titles

This tinyplot method for density plots differs from the base plot.density function in its treatment of titles. The x-axis title displays only the variable name, omitting details about the number of observations and smoothing bandwidth. Additionally, the main title is left blank by default for a cleaner appearance.

Examples

# "density" type convenience string
tinyplot(~Sepal.Length, data = iris, type = "density")

# grouped density example
tinyplot(~Sepal.Length | Species, data = iris, type = "density")

# use `bg = "by"` (or, equivalent `fill = "by"`) to get filled densities
tinyplot(~Sepal.Length | Species, data = iris, type = "density", fill = "by")

# use `type_density()` to pass extra arguments for customization
tinyplot(
  ~Sepal.Length | Species, data = iris,
  type = type_density(bw = "SJ"),
  main = "Bandwidth computed using Sheather & Jones (1991)"
)

# The default for grouped density plots is to use the mean of the
# individual subgroup bandwidths (weighted by group size) as the
# joint bandwidth. Alternatively, the bandwidth from the "full"
# data or separate individual bandwidths ("none") can be used.
tinyplot(~Sepal.Length | Species, data = iris,
    ylim = c(0, 1.25), type = "density")        # mean (default)
tinyplot_add(joint.bw = "full", lty = 2)        # full data
tinyplot_add(joint.bw = "none", lty = 3)        # none (individual)
legend("topright", c("Mean", "Full", "None"), lty = 1:3, bty = "n", title = "Joint BW")

Description

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

Usage

type_errorbar(length = 0.05, dodge = 0, fixed.dodge = FALSE)

type_pointrange(dodge = 0, fixed.dodge = FALSE)

Arguments

Examples

tinytheme("basic")

#
## 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 that applies horizontal axis tick labels

tinytheme("classic")
tinyplot(est ~ term, ymin = lwr, ymax = upr, data = coefs, type = "errorbar",
         flip = TRUE)
tinyplot_add(type = 'vline', lty = 2)

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)

tinytheme() # reset theme

Description

Plot a function

Usage

type_function(fun = dnorm, args = list(), n = 101, ...)

Arguments

Details

When using type_function() in a tinyplot() call, the x value indicates the range of values to plot on the x-axis.

Examples

# Plot the normal density (default function)
tinyplot(x = -4:4, type = "function")
# tinyplot(x = -4:4, type = type_function()) # same

# Customize by passing explicit arguments to your function
tinyplot(x = -1:10, type = type_function(
  fun = dnorm, args = list(mean = 3)
))

# Additional arguments are passed to the `lines()` function.
tinyplot(x = -4:4, type = type_function(
  fun = dnorm,
  col = "pink", type = "p", pch = 3
))

# Custom function example
## (Here using `function(x)`, but you could also use the shorter `\(x)`
## anonymous function syntax introduced in R 4.1.0)
tinyplot(x = -4:4, type = type_function(fun = function(x) 0.5 * exp(-abs(x))))

Description

Type function for plotting a generalized model fit. Arguments are passed to glm.

Usage

type_glm(family = "gaussian", se = TRUE, level = 0.95, type = "response")

Arguments

Examples

# "glm" type convenience string
tinyplot(am ~ mpg, data = mtcars, type = "glm")

# Use `type_glm()` to pass extra arguments for customization
tinyplot(am ~ mpg, data = mtcars, type = type_glm(family = "binomial"))

Description

Type function for histogram plots. type_hist is an alias for type_histogram.

Usage

type_histogram(
  breaks = "Sturges",
  freq = NULL,
  right = TRUE,
  free.breaks = FALSE,
  drop.zeros = TRUE
)

type_hist(
  breaks = "Sturges",
  freq = NULL,
  right = TRUE,
  free.breaks = FALSE,
  drop.zeros = TRUE
)

Arguments

Examples

# "histogram"/"hist" type convenience string(s)
tinyplot(Nile, type = "histogram")

# Use `type_histogram()` to pass extra arguments for customization
tinyplot(Nile, type = type_histogram(breaks = 30))
tinyplot(Nile, type = type_histogram(breaks = 30, freq = FALSE))
# etc.

# Grouped histogram example
tinyplot(
    ~ Petal.Width | Species,
    type = "histogram",
    data = iris
)

# Faceted version
tinyplot(
    ~Petal.Width,
    facet = ~Species,
    type = "histogram",
    data = iris
)

# For visualizing faceted histograms across varying scales, you may also wish
# to impose free histogram breaks too (i.e., calculate breaks separately for
# each group). Compare:

# free facet scales + shared histogram breaks, versus...
tinyplot(
    ~Petal.Width,
    facet = ~Species,
    facet.args = list(free = TRUE),
    type = type_histogram(),
    data = iris
)
# ... free facet scales + free histogram breaks
tinyplot(
    ~Petal.Width,
    facet = ~Species,
    facet.args = list(free = TRUE),
    type = type_histogram(free = TRUE),
    data = iris
)

Description

Type function for plotting jittered points. Arguments are passed to jitter.

Usage

type_jitter(factor = 1, amount = NULL)

Arguments

Details

The result of r <- x + amount * runif(n, -1, 1) where n <- length(x).

When amount is NULL (the default) amount <- factor * d/5 where d is about the smallest difference between adjacent unique (up to fuzz) x values.

If amount == 0, amount <- factor * (max(x) - min(x))/50, (using only finite x values), which is the same as in S and the references. In the above cases, the final amount is always ensured to be positive.

The short jitter() function is itself a succinct definition.

Examples

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

# Use `type_jitter()` to pass extra arguments for customization
tinyplot(Sepal.Length ~ Species, data = iris, type = type_jitter(factor = 0.5))

Description

Type function for plotting lines.

Usage

type_lines(type = "l", dodge = 0, fixed.dodge = FALSE)

Arguments

Examples

# "l" type convenience character string
tinyplot(circumference ~ age | Tree, data = Orange, type = "l")

# Use `type_lines()` to pass extra arguments for customization
tinyplot(circumference ~ age | Tree, data = Orange, type = type_lines(type = "s"))

# Direct legend labels are a good option for grouped lined plots (assuming
# there aren't too many groups and the data are sorted along the x-axis)
tinyplot(
  circumference ~ age | Tree, data = Orange, type = "l",
  legend = "direct"
)

# Fancier version(s) that use a theme and repel overlapping labels
Orange2 = transform(Orange, Tree = paste("Tree", Tree))
tinyplot(
  circumference ~ age | Tree, data = Orange2, type = "l",
  legend = list("direct", repel = TRUE), # auto repel
  theme = "socviz"
)
tinyplot(
  circumference ~ age | Tree, data = Orange2, type = "l",
  legend = list("direct", nudge_y = c("Tree 1" = 3, "Tree 3" = -5)), # manual
  theme = "socviz"
)

Description

Type function for plotting a linear model fit. Arguments are passed to lm.

Usage

type_lm(se = TRUE, level = 0.95)

Arguments

Examples

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

# Grouped model fits (here: illustrating an example of Simpson's paradox)
tinyplot(Sepal.Width ~ Petal.Width | Species, data = iris, type = "lm")
tinyplot_add(type = "p")

# Use `type_lm()` to pass extra arguments for customization
tinyplot(Sepal.Width ~ Petal.Width, data = iris, type = type_lm(level = 0.8))

Description

Type function for plotting a LOESS (LOcal regrESSion) fit. Arguments are passed to loess.

Usage

type_loess(
  span = 0.75,
  degree = 2,
  family = "gaussian",
  control = loess.control(),
  se = TRUE,
  level = 0.95
)

Arguments

Examples

# "loess" type convenience string
tinyplot(dist ~ speed, data = cars, type = "loess")

# Use `type_loess()` to pass extra arguments for customization
tinyplot(dist ~ speed, data = cars, type = type_loess(span = 0.5, degree = 1))

Description

Type function for plotting points, i.e. a scatter plot.

Usage

type_points(clim = c(0.5, 2.5), dodge = 0, fixed.dodge = FALSE)

Arguments

Examples

# "p" type convenience character string
tinyplot(Sepal.Length ~ Petal.Length, data = iris, type = "p")

# Same result with type_points()
tinyplot(Sepal.Length ~ Petal.Length, data = iris, type = type_points())

# Note: Specifying the type here is redundant. Like base plot, tinyplot
# automatically produces a scatter plot if x and y are numeric
tinyplot(Sepal.Length ~ Petal.Length, data = iris)

# Grouped scatter plot example
tinyplot(Sepal.Length ~ Petal.Length | Species, data = iris)

# Continuous grouping (with gradient legend)
tinyplot(Sepal.Length ~ Petal.Length | Sepal.Width, data = iris, pch = 19)

# Bubble chart version
tinyplot(Sepal.Length ~ Petal.Length, data = iris, cex = iris$Sepal.Width)

# Fancier version with dual legends and extra customization
tinyplot(Sepal.Length ~ Petal.Length | Species,
  data = iris,
  cex = iris$Sepal.Width, clim = c(1, 5),
  pch = 21, fill = 0.3)

Description

Type function for plotting polygons. Arguments are passed to polygon.

Usage

type_polygon(density = NULL, angle = 45)

Arguments

Examples

# "polygon" type convenience character string
tinyplot(1:9, c(2,1,2,1,NA,2,1,2,1), type = "polygon")

# Use `type_polygon()` to pass extra arguments for customization
tinyplot(1:9, c(2,1,2,1,NA,2,1,2,1), type = type_polygon(density = c(10, 20)))

Description

Type function for plotting polygons. Arguments are passed to polypath.

Usage

type_polypath(rule = "winding")

Arguments

Examples

# "polypath" type convenience character string
tinyplot(
    c(.1, .1, .6, .6, NA, .4, .4, .9, .9),
    c(.1, .6, .6, .1, NA, .4, .9, .9, .4),
    type = "polypath", fill = "grey"
)

# Use `type_polypath()` to pass extra arguments for customization
tinyplot(
    c(.1, .1, .6, .6, NA, .4, .4, .9, .9),
    c(.1, .6, .6, .1, NA, .4, .9, .9, .4),
    type = type_polypath(rule = "evenodd"), fill = "grey"
)

Description

Plots the theoretical quantiles of x on the horizontal axis against observed values of x on the vertical axis.

Usage

type_qq(distribution = qnorm)

Arguments

Examples

tinyplot(~mpg, data = mtcars, type = type_qq())

# suppress the line
tinyplot(~mpg, data = mtcars, lty = 0, type = type_qq())

Description

Type function for plotting rectangles.

Usage

type_rect()

Details

Contrary to base rect, rectangles in tinyplot must be specified using the xmin, ymin,xmax, and ymax arguments.

Examples

i = 4*(0:10)

# "rect" type convenience character string
tinyplot(
  xmin = 100+i, ymin = 300+i, xmax = 150+i, ymax = 380+i,
  by = i, fill = 0.2,
  type = "rect"
)

# Same result with type_rect()
tinyplot(
  xmin = 100+i, ymin = 300+i, xmax = 150+i, ymax = 380+i,
  by = i, fill = 0.2,
  type = type_rect()
)

Description

Type function for producing ridge plots (also known as joy plots), which display density distributions for multiple groups with vertical offsets. This function uses tinyplot scaffolding, which enables added functionality such as grouping and faceting.

The line color is controlled by the col argument in the tinyplot() call. The fill color is controlled by the bg argument in the tinyplot() call.

Usage

type_ridge(
  scale = 1.5,
  joint.max = c("all", "facet", "by"),
  breaks = NULL,
  probs = NULL,
  ylevels = NULL,
  bw = "nrd0",
  joint.bw = c("mean", "full", "none"),
  adjust = 1,
  kernel = c("gaussian", "epanechnikov", "rectangular", "triangular", "biweight",
    "cosine", "optcosine"),
  n = 512,
  gradient = FALSE,
  raster = FALSE,
  col = NULL,
  alpha = NULL
)

Arguments

Technical note on gradient fills

tinyplot uses two basic approaches for drawing gradient fills in ridge line plots, e.g., if type_ridge(gradient = TRUE).

The first (and default) polygon-based approach involves dividing up the main density region into many smaller polygons along the x-axis. Each of these smaller polygons inherits a different color "segment" from the underlying palette swatch, which in turn creates the effect of a continuous gradient when they are all plotted together. Internally, this polygon-based approach is vectorized (i.e., all of the sub-polygons are plotted simultaneously). It is thus efficient from a plotting perspective and generally also performs well from an aesthetic perspective. However, it can occasionally produce undesirable plotting artifacts on some graphics devices—e.g., thin but visible vertical lines—if alpha transparency is being used at the same time.

For this reason, we also offer an alternative raster-based approach for gradient fills that users can invoke via type_ridge(gradient = TRUE, raster = TRUE). The essential idea is that we coerce the density polygon into a raster representation (using rasterImage) and achieve the gradient effect via color interpolation. The trade-off this time is potential smoothness artifacts around the top of the ridge densities at high resolutions, since we have converted a vector object into a raster object.

Again, we expect that the choice between these two approaches will only matter for ridge plots that combine gradient fills with alpha transparency (and on certain graphics devices). We recommend that users experiment to determine which approach is optimal for their device.

Examples

aq = transform(
  airquality,
  Month = factor(month.abb[Month], levels = month.abb[5:9]),
  Month2 = factor(month.name[Month], levels = month.name[5:9]),
  Late = ifelse(Day > 15, "Late", "Early")
  )

# default ridge plot (using the "ridge" convenience string)
tinyplot(Month ~ Temp, data = aq, type = "ridge")

# for ridge plots, we recommend pairing with the dedicated theme(s), which
# facilitate nicer y-axis labels, grid lines, etc.

tinytheme("ridge")
tinyplot(Month ~ Temp, data = aq, type = "ridge")

tinytheme("ridge2") # removes the plot frame (but keeps x-axis line)
tinyplot(Month ~ Temp, data = aq, type = "ridge")

# the "ridge(2)" themes are especially helpful for long y labels, due to
# dyanmic plot adjustment
tinyplot(Month2 ~ Temp, data = aq, type = "ridge")

# pass customization arguments through type_ridge()... for example, use
# the scale argument to change/avoid overlap of densities (more on scaling
# further below)

tinyplot(Month ~ Temp, data = aq, type = type_ridge(scale = 1))
  
## by grouping is also supported. two special cases of interest:

# 1) by == y (color by y groups)
tinyplot(Month ~ Temp | Month, data = aq, type = "ridge")

# 2) by == x (gradient coloring along x)
tinyplot(Month ~ Temp | Temp, data = aq, type = "ridge")

# aside: pass explicit `type_ridge(col = <col>)` arg to set a different
# border color
tinyplot(Month ~ Temp | Temp, data = aq, type = type_ridge(col = "white"))

# gradient coloring along the x-axis can also be invoked manually without
# a legend (the next two tinyplot calls are equivalent)

# tinyplot(Month ~ Temp, data = aq, type = type_ridge(gradient = "agsunset"))
tinyplot(Month ~ Temp, data = aq, type = type_ridge(gradient = TRUE))

# aside: when combining gradient fill with alpha transparency, it may be
# better to use the raster-based approach (test on your graphics device)

tinyplot(Month ~ Temp, data = aq,
  type = type_ridge(gradient = TRUE, alpha = 0.5),
  main = "polygon fill (default)")
tinyplot(Month ~ Temp, data = aq,
  type = type_ridge(gradient = TRUE, alpha = 0.5, raster = TRUE),
  main = "raster fill")

# highlighting only the center 50% of the density (i.e., 25%-75% quantiles)
tinyplot(Month ~ Temp, data = aq, type = type_ridge(
  gradient = hcl.colors(3, "Dark Mint")[c(2, 1, 2)],
  probs = c(0.25, 0.75), col = "white"))

# highlighting the probability distribution by color gradient
# (darkest point = median)
tinyplot(Month ~ Temp, data = aq, type = type_ridge(
  gradient = hcl.colors(250, "Dark Mint")[c(250:1, 1:250)],
  probs = 0:500/500))

# faceting also works, although we recommend switching (back) to the "ridge"
# theme for faceted ridge plots

tinytheme("ridge")
tinyplot(Month ~ Ozone, facet = ~ Late, data = aq,
  type = type_ridge(gradient = TRUE))

## use the joint.max argument to vary the maximum density used for
## determining relative scaling...

# jointly across all densities (default) vs. per facet
tinyplot(Month ~ Temp, facet = ~ Late, data = aq,
  type = type_ridge(scale = 1))
tinyplot(Month ~ Temp, facet = ~ Late, data = aq,
  type = type_ridge(scale = 1, joint.max = "facet"))

# jointly across all densities (default) vs. per by row
tinyplot(Month ~ Temp | Late, data = aq,
  type = type_ridge(scale = 1))
tinyplot(Month ~ Temp | Late, data = aq,
  type = type_ridge(scale = 1, joint.max = "by"))
  
# restore the default theme
tinytheme()

Description

Adds a rug representation (1-d plot) of the data to the plot.

Usage

type_rug(
  ticksize = 0.03,
  side = 1,
  quiet = getOption("warn") < 0,
  jitter = FALSE,
  amount = NULL
)

Arguments

Details

This function should only be used as part of tinyplot_add(), i.e. adding to an existing plot.

In most cases, determining which variable receives the rug representation will be based on the side argument (i.e., x-variable if side is 1 or 3, and y-variable if side is 2 or 4). An exception is if the preceding plot type was either "density" or "histogram"; for these latter cases, the x-variable will always be used. See Examples.

Examples

tinyplot(~wt | am, data = mtcars, type = "density", facet = "by", fill = "by")
tinyplot_add(type = "rug")
# use type_rug() to pass extra options
tinyplot_add(type = type_rug(side = 3, ticksize = 0.05))

# For ties, use jittering
tinyplot(eruptions ~ waiting, data = faithful, type = "lm")
tinyplot_add(type = type_rug(jitter = TRUE, amount = 0.3))
tinyplot_add(type = type_rug(jitter = TRUE, amount = 0.1, side = 2))
# Add original points just for reference
tinyplot_add(type = "p")

Description

Type function for plotting line segments.

Usage

type_segments()

Details

Contrary to base segments, line segments in tinyplot must be specified using the xmin, ymin,xmax, and ymax arguments.

Examples

# "segments" type convenience character string
tinyplot(
  xmin = c(0,.1), ymin = c(.2,1), xmax = c(1,.9), ymax = c(.75,0),
  type = "segments"
)

# Same result with type_segments()
tinyplot(
  xmin = c(0,.1), ymin = c(.2,1), xmax = c(1,.9), ymax = c(.75,0),
  type = type_segments()
)

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,
  ylevels = NULL,
  col = NULL,
  xaxlabels = NULL,
  yaxlabels = NULL,
  weights = NULL
)

Arguments

Examples

# "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))

p = palette.colors(3, "Pastel 1")
tinyplot(Species ~ Sepal.Width, data = iris, type = type_spineplot(breaks = 4, col = p))
rm(p)

# 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)

tinyplot(
  Survived ~ Sex, facet = ~ Class, data = ttnc,
  type = type_spineplot(weights = ttnc$Freq)
)

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

# Fancier version. Note the smart inheritance of spacing etc.
tinyplot(
  Survived ~ Sex | Class, facet = "by", data = ttnc,
  type = type_spineplot(weights = ttnc$Freq),
  palette = "Dark 2", facet.args = list(nrow = 1), axes = "t"
)

# Reorder x and y variable categories either by their character levels or numeric indexes
tinyplot(
  Survived ~ Sex, facet = ~ Class, data = ttnc,
  type = type_spineplot(weights = ttnc$Freq, xlevels = c("Female", "Male"), ylevels = 2:1)
)

# Note: 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 = type_spineplot(weights = ttnc$Freq), alpha = 0.3
)

Description

Type function for plotting a cubic (or Hermite) spline interpolation. Arguments are passed to spline; see this latter function for default argument values.

Usage

type_spline(
  n = NULL,
  method = "fmm",
  xmin = NULL,
  xmax = NULL,
  xout = NULL,
  ties = mean
)

Arguments

Details

See spline for further details on the available interpolation methods.

Examples

# "spline" type convenience string
tinyplot(dist ~ speed, data = cars, type = "spline")

# Use `type_spline()` to pass extra arguments for customization
tinyplot(dist ~ speed,
    data = cars, type = type_spline(method = "natural", n = 25),
    add = TRUE, lty = 2)

Description

Applies a summary function to y along unique values of x. For example, plot the mean y value for each x value. Internally, type_summary() applies a thin wrapper around ave and then passes the result to type_lines for drawing.

Usage

type_summary(fun = mean, ...)

Arguments

See Also

ave which performs the summarizing (averaging) behind the scenes.

Examples

# Plot the mean chick weight over time
tinyplot(weight ~ Time, data = ChickWeight, type = "summary")

# Note: "mean" is the default function, so these are also equivalent:
# tinyplot(weight ~ Time, data = ChickWeight, type = type_summary())
# tinyplot(weight ~ Time, data = ChickWeight, type = type_summary(mean))

# Plot the median instead
tinyplot(weight ~ Time, data = ChickWeight, type = type_summary(median))

# Works with groups and/or facets too
tinyplot(weight ~ Time | Diet, facet = "by", data = ChickWeight, type = "summary")

# Custom/complex function example
tinyplot(
  weight ~ Time | Diet,
  facet = "by", data = ChickWeight,
  type = type_summary(function(y) quantile(y, probs = 0.9) / max(y))
)

Description

Type function for adding text annotations to a plot at the specified (x,y) coordinates.

Usage

type_text(
  labels = NULL,
  adj = NULL,
  pos = NULL,
  offset = 0.5,
  family = NULL,
  font = NULL,
  vfont = NULL,
  xpd = NULL,
  srt = 0,
  clim = c(0.5, 2.5)
)

Arguments

Examples

# simplest case (no labels), will auto revert to y labels
tinyplot(1:12, type = "text")

# pass explicit `labels` arg if you want specific text
tinyplot(1:12, type = "text", labels = month.abb)

# for advanced customization, it's safer to pass args through `type_text()`
tinyplot(1:12, type = type_text(
  labels = month.abb, family = "HersheyScript", srt = -20))

# same principles apply to grouped and/or facet data
tinyplot(mpg ~ hp | factor(cyl),
  data = mtcars,
  type = type_text(
    labels = row.names(mtcars),
    family = "HersheySans",
    font = 2,
    adj = 0
  )
)

# tip: use `xpd = NA` to avoid clipping text at the plot region
tinyplot(mpg ~ hp | factor(cyl),
  data = mtcars,
  type = type_text(
    labels = row.names(mtcars),
    family = "HersheySans",
    font = 2,
    adj = 0,
    xpd = NA
  )
)