Set or query graphical parameters

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

…	arguments of the form key = value. This includes all of the parameters typically supported by par, as well as the tinyplot-specific ones described in the ‘Graphical Parameters’ section below.
hook	Logical. If TRUE, base graphical parameters persist across plots via a hook applied before each new plot (see ?setHook).

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.

• cex.xaxs, cex.yaxs: Numeric expansion factors for the x- and y-axis tick labels, respectively. Both default to NULL, whereby the shared cex.axis value is used instead (which in turn falls back to par(“cex.axis”)). Set one of them to size a single axis’ tick labels independently of the other, e.g. cex.yaxs to shrink a long list of category names on the y-axis without also shrinking the x-axis. Compare cex.xlab and cex.ylab, which do the same for the axis titles.

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

• col.xaxs, col.yaxs: Characters (or integers) specifying the colour of the x- and y-axis tick labels, respectively. Both default to NULL, whereby the shared col.axis value is used instead.

• col.default: Default colour for single-group displays (i.e. plots without a by grouping). Can be NULL, a length-1 character colour, or a length-1 numeric index into palette.qualitative. Defaults to NULL, in which case the first colour of the active qualitative palette is used (or base palette()[1], typically black, if no theme is set). A character value sets the single-group colour independently of the multi-group palette. A numeric value i selects the ith colour of palette.qualitative as the single-group default; a negative index additionally drops that colour from the palette used for grouped plots. For example, col.default = -1 paired with palette.qualitative = “Okabe-Ito” uses black (the leading palette colour) for single-group plots and an Okabe-Ito-minus-black palette for grouped plots, avoiding the need to maintain a separate "no-black" palette.

• 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.axes: Character string controlling which facets draw their own axes: “all” (each facet), “outer” (only facets on the outer edge of the facet grid, dropping redundant interior axes), or “none”. Defaults to NULL, whereby the choice is inferred from whether the plot is framed (see the axes argument of facet.args). Equivalent to setting tinyplot(…, facet.args = list(axes = X)), but globally, which also makes it available to themes.

• facet.drop: Logical indicating whether facet levels that no observation uses should be dropped, rather than drawing an empty panel. Defaults to FALSE. Equivalent to setting tinyplot(…, facet.args = list(drop = X)), but globally, which also makes it available to themes.

• facet.drop.levels: Logical indicating whether each free facet (facet.args = list(free = TRUE)) should keep only the categories of a categorical axis that it actually uses, re-levelled as if that panel’s data had been passed through factor() on its own. Defaults to FALSE, i.e. every panel shows the full set of categories. Equivalent to setting tinyplot(…, facet.args = list(drop.levels = X)), but globally, which also makes it available to themes.

• 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).

• facet.labeller: A formatting function (or tinylabel convenience string, e.g. “percent”) applied to the facet titles, or a list of them (or a character vector of convenience strings), optionally named for the facet variables they apply to, for formatting each facet variable differently. Note that this per-variable naming claims the same slot that a tinylabel dictionary would, so a dictionary has to be nested inside it, e.g. facet.labeller = list(Species = c(setosa = “SET”)). Defaults to NULL (no formatting). Applied to the underlying facet values, i.e. before any facet.prefix name is added. Equivalent to setting tinyplot(…, facet.args = list(labeller = X)), but globally.

• facet.prefix: Logical or character controlling whether facet titles are prefixed with their variable name, e.g. “vs = 0” rather than just “0”. TRUE uses the variable name(s), while a character string—or a vector or list of them, one element per facet variable, optionally named for the variables they apply to—supplies custom name(s) instead. Defaults to NULL, which is equivalent to FALSE (no prefix). Equivalent to setting tinyplot(…, facet.args = list(prefix = X)), but globally.

• facet.sep: Character string separating the individual variables of a multi-variable facet title, e.g. “” to stack them on separate lines. Ignored for single-variable facets. Defaults to NULL, i.e. the “:” that the variables were combined with, or “,” if they are prefixed via facet.prefix (above). Equivalent to setting tinyplot(…, facet.args = list(sep = X)), but globally.

• 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.

• lty.xaxs, lty.yaxs: Line types for the x- and y-axis lines, respectively. Both default to NULL, whereby the shared lty.axis value is used instead.

• lwd.xaxs, lwd.yaxs: Line widths for the x- and y-axis lines, respectively. Both default to NULL, whereby the shared lwd.axis value is used instead.

• 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.

• xaxr, yaxr: Numeric giving the rotation of the x- and y-axis tick labels, in degrees counter-clockwise; NULL (the default) leaves them unrotated. Unlike las, which is limited to the four right angles, any angle is permitted. Setting one overrides las for that axis alone, leaving the other axis under las as usual, and 0 (or any multiple of 360) counts as no rotation at all. Sets the default for the xaxr and yaxr arguments of tinyplot(), which take precedence. Two caveats follow from tinyplot drawing rotated labels itself rather than deferring to base axis(). First, margins are only resized to fit them under a theme with dynmar = TRUE (see tinytheme); under the default theme the margins are left alone, so a long rotated label will be clipped unless you widen mar yourself. Second, rotated labels do not inherit the thinning that axis() applies via gap.axis, so they start to overlap once the spacing between ticks falls below line height / sin(srt).

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

library("tinyplot")

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

$las
[1] 0

$pch
[1] 1

$facet.bg
NULL

$facet.cex
[1] 1

$grid
[1] FALSE

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