Title: | Lightweight Extension of the Base R Graphics System |
---|---|
Description: | Lightweight extension of the base R graphics system, with support for automatic legends, facets, and various other enhancements. |
Authors: | Grant McDermott [aut, cre] |
Maintainer: | Grant McDermott <[email protected]> |
License: | Apache License (>= 2) |
Version: | 0.2.1.99 |
Built: | 2024-09-06 18:17:21 UTC |
Source: | https://github.com/grantmcdermott/tinyplot |
Internal function used to calculate the placement of (including outside the plotting area) and drawing of legend.
draw_legend( legend = NULL, legend_args = NULL, by_dep = NULL, lgnd_labs = NULL, type = NULL, pch = NULL, lty = NULL, lwd = NULL, col = NULL, bg = NULL, cex = NULL, gradient = FALSE, lmar = NULL, has_sub = FALSE, new_plot = TRUE )
draw_legend( legend = NULL, legend_args = NULL, by_dep = NULL, lgnd_labs = NULL, type = NULL, pch = NULL, lty = NULL, lwd = NULL, col = NULL, bg = NULL, cex = NULL, gradient = FALSE, lmar = NULL, has_sub = FALSE, new_plot = TRUE )
legend |
Legend placement keyword or list, passed down from tinyplot. |
legend_args |
Additional legend arguments to be passed to |
by_dep |
The (deparsed) "by" grouping variable name. |
lgnd_labs |
The labels passed to |
type |
Plotting type(s), passed down from tinyplot. |
pch |
Plotting character(s), passed down from tinyplot. |
lty |
Plotting linetype(s), passed down from tinyplot. |
lwd |
Plotting line width(s), passed down from tinyplot. |
col |
Plotting colour(s), passed down from tinyplot. |
bg |
Plotting character background fill colour(s), passed down from tinyplot. |
cex |
Plotting character expansion(s), passed down from tinyplot. |
gradient |
Logical indicating whether a continuous gradient swatch should be used to represent the colors. |
lmar |
Legend margins (in lines). Should be a numeric vector of the form
|
has_sub |
Logical. Does the plot have a sub-caption. Only used if keyword position is "bottom!", in which case we need to bump the legend margin a bit further. |
new_plot |
Logical. Should we be calling plot.new internally? |
No return value, called for side effect of producing a(n empty) plot with a legend in the margin.
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)
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)
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.
get_saved_par(when = c("before", "after"))
get_saved_par(when = c("before", "after"))
when |
character. From when should the saved parameters be retrieved?
Either "before" (the default) or "after" the preceding |
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.
A list of par
settings.
# # 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)
# # 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)
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()
.
tinyplot(x, ...) ## Default S3 method: tinyplot( x = NULL, y = NULL, by = NULL, facet = NULL, facet.args = NULL, data = NULL, type = NULL, xlim = NULL, ylim = NULL, log = "", main = NULL, sub = NULL, xlab = NULL, ylab = NULL, ann = par("ann"), axes = TRUE, frame.plot = NULL, asp = NA, grid = NULL, palette = NULL, legend = NULL, pch = NULL, lty = NULL, lwd = NULL, col = NULL, bg = NULL, fill = NULL, alpha = NULL, cex = 1, restore.par = FALSE, xmin = NULL, xmax = NULL, ymin = NULL, ymax = NULL, ribbon.alpha = NULL, add = FALSE, file = NULL, width = NULL, height = NULL, empty = FALSE, xaxt = NULL, yaxt = NULL, ... ) ## S3 method for class 'formula' tinyplot( x = NULL, data = parent.frame(), facet = NULL, facet.args = NULL, type = NULL, xlim = NULL, ylim = NULL, main = NULL, sub = 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, ... ) plt(x, ...) ## S3 method for class 'density' tinyplot( x = NULL, by = NULL, facet = NULL, facet.args = NULL, type = c("l", "area"), xlim = NULL, ylim = NULL, main = NULL, sub = NULL, xlab = NULL, ylab = NULL, ann = par("ann"), axes = TRUE, frame.plot = axes, asp = NA, grid = NULL, pch = NULL, col = NULL, lty = NULL, lwd = NULL, bg = NULL, fill = NULL, restore.par = FALSE, ... )
tinyplot(x, ...) ## Default S3 method: tinyplot( x = NULL, y = NULL, by = NULL, facet = NULL, facet.args = NULL, data = NULL, type = NULL, xlim = NULL, ylim = NULL, log = "", main = NULL, sub = NULL, xlab = NULL, ylab = NULL, ann = par("ann"), axes = TRUE, frame.plot = NULL, asp = NA, grid = NULL, palette = NULL, legend = NULL, pch = NULL, lty = NULL, lwd = NULL, col = NULL, bg = NULL, fill = NULL, alpha = NULL, cex = 1, restore.par = FALSE, xmin = NULL, xmax = NULL, ymin = NULL, ymax = NULL, ribbon.alpha = NULL, add = FALSE, file = NULL, width = NULL, height = NULL, empty = FALSE, xaxt = NULL, yaxt = NULL, ... ) ## S3 method for class 'formula' tinyplot( x = NULL, data = parent.frame(), facet = NULL, facet.args = NULL, type = NULL, xlim = NULL, ylim = NULL, main = NULL, sub = 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, ... ) plt(x, ...) ## S3 method for class 'density' tinyplot( x = NULL, by = NULL, facet = NULL, facet.args = NULL, type = c("l", "area"), xlim = NULL, ylim = NULL, main = NULL, sub = NULL, xlab = NULL, ylab = NULL, ann = par("ann"), axes = TRUE, frame.plot = axes, asp = NA, grid = NULL, pch = NULL, col = NULL, lty = NULL, lwd = NULL, bg = NULL, fill = NULL, restore.par = FALSE, ... )
x , y
|
the x and y arguments provide the x and y coordinates for the
plot. Any reasonable way of defining the coordinates is acceptable; most
likely the names of existing vectors or columns of data frames. See the
'Examples' section below, or the function
|
... |
other graphical parameters (see |
by |
grouping variable(s). The default behaviour is for groups to be
represented in the form of distinct colours, which will also trigger an
automatic legend. (See |
facet |
the faceting variable(s) that you want arrange separate plot windows by. Can be specified in various ways:
|
facet.args |
an optional list of arguments for controlling faceting
behaviour. (Ignored if
|
data |
a data.frame (or list) from which the variables in formula should be taken. A matrix is converted to a data frame. |
type |
character string giving the type of plot desired. If no argument
is provided, then the plot type will default to something sensible for the
type of
|
xlim |
the x limits (x1, x2) of the plot. Note that x1 > x2 is allowed
and leads to a ‘reversed axis’. The default value, NULL, indicates that
the range of the |
ylim |
the y limits of the plot. |
log |
a character string which contains "x" if the x axis is to be logarithmic, "y" if the y axis is to be logarithmic and "xy" or "yx" if both axes are to be logarithmic. |
main |
a main title for the plot, see also |
sub |
a subtitle for the plot. |
xlab |
a label for the x axis, defaults to a description of x. |
ylab |
a label for the y axis, defaults to a description of y. |
ann |
a logical value indicating whether the default annotation (title and x and y axis labels) should appear on the plot. |
axes |
logical or character. Should axes be drawn ( |
frame.plot |
a logical indicating whether a box should be drawn around
the plot. Can also use |
asp |
the y/xy/x aspect ratio, see |
grid |
argument for plotting a background panel grid, one of either:
|
palette |
one of the following options:
|
legend |
one of the following options:
|
pch |
plotting "character", i.e., symbol to use. Character, integer, or
vector of length equal to the number of categories in the |
lty |
line type. Character, integer, or vector of length equal to the
number of categories in the |
lwd |
line width. Numeric scalar or vector of length equal to the
number of categories in the |
col |
plotting color. Character, integer, or vector of length equal to
the number of categories in the |
bg |
background fill color for the open plot symbols 21:25 (see
For both of these convenience arguments, note that the (grouped) |
fill |
alias for |
alpha |
a numeric in the range |
cex |
character expansion. A numerical vector (can be a single value) giving the amount by which plotting characters and symbols should be scaled relative to the default. Note that NULL is equivalent to 1.0, while NA renders the characters invisible. |
restore.par |
a logical value indicating whether the
|
xmin , xmax , ymin , ymax
|
minimum and maximum coordinates of relevant area
or interval plot types. Only used when the |
ribbon.alpha |
numeric factor modifying the opacity alpha of any ribbon
shading; typically in |
add |
logical. If TRUE, then elements are added to the current plot rather than drawing a new plot window. Note that the automatic legend for the added elements will be turned off. |
file |
character string giving the file path for writing a plot to disk.
If specified, the plot will not be displayed interactively, but rather sent
to the appropriate external graphics device (i.e.,
|
width |
numeric giving the plot width in inches. Together with |
height |
numeric giving the plot height in inches. Same considerations as
|
empty |
logical indicating whether the interior plot region should be
left empty. The default is |
xaxt , yaxt
|
character specifying the type of x-axis and y-axis, respectively.
See |
formula |
a |
subset , na.action , drop.unused.levels
|
arguments passed to |
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.
No return value, called for side effect of producing a plot.
#' 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 ) # 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` 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 ) # 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 ) # 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") ) # 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 further customize the look of you plots using familiar # arguments and base plotting theme settings (e.g., via `(t)par`). op = tpar(family = "HersheySans", las = 1) tinyplot( Temp ~ Day | Month, data = aq, type = "b", pch = 16, palette = "tableau", alpha = 0.5, main = "Daily temperatures by month", frame = FALSE, grid = TRUE ) tpar(op) # restore original graphics parameters # Note: For more examples and a detailed walkthrough, please see the # introductory tinyplot tutorial available online: # https://grantmcdermott.com/tinyplot/vignettes/intro_tutorial.html
#' 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 ) # 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` 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 ) # 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 ) # 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") ) # 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 further customize the look of you plots using familiar # arguments and base plotting theme settings (e.g., via `(t)par`). op = tpar(family = "HersheySans", las = 1) tinyplot( Temp ~ Day | Month, data = aq, type = "b", pch = 16, palette = "tableau", alpha = 0.5, main = "Daily temperatures by month", frame = FALSE, grid = TRUE ) tpar(op) # restore original graphics parameters # Note: For more examples and a detailed walkthrough, please see the # introductory tinyplot tutorial available online: # https://grantmcdermott.com/tinyplot/vignettes/intro_tutorial.html
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.
tpar(...)
tpar(...)
... |
arguments of the form |
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.
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.
facet.cex |
Expansion factor for facet titles. Defaults to 1 . |
|
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.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.bg |
Character or integer specifying the facet background colour. If an integer, will correspond to the user's default colour palette (see palette ). Passed rect . Defaults to NULL (none). |
|
facet.border |
Character or integer specifying the facet border colour. If an integer, will correspond to the users default colour palette (see palette ). Passed rect . Defaults to NA (none). |
|
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.width |
Numeric specifying the width (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. |
|
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) , i.e. a single line of padding around each facet. If more that three facets are detected, the fmar parameter is scaled by 0.75 (i.e., three-quarters) to reduce the excess whitespace that would otherwise arise due to the absent axes lines and labels. (An exception is made for 2x2 plots to better match the cex expansion logic of the base graphics system under this particular layout.) Similarly, note that an extra 0.5 lines is subtracted from each side of the facet padding for plots that aren't framed, to reduce excess whitespace. |
|
grid |
Logical indicating whether a background panel grid should be added to plots automatically. Defaults to NULL, which is equivalent to FALSE . |
|
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) , where the first number represents the "inner" margin between the legend and the plot region, and the second number represents the "outer" margin between the legend and edge of the graphics device. (Note that an exception for the definition of the "outer" legend margin occurs when the legend placement is "top!" , since the legend is placed above the plot region but below the main title. In such cases, the outer margin is relative to the existing gap between the title and the plot region, which is itself determined by par("mar")[3] .) |
|
ribbon.alpha |
Numeric factor in the range [0,1] for modifying the opacity alpha of "ribbon" and "area" (and alike) type plots. Default value is 0.2 . |
|
# 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")
# 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")