tpar: Set or query graphical parameters
In tinyplot: Lightweight Extension of the Base R Graphics System
tpar R Documentation
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(...)
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.
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
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.
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")
tinyplot documentation built on Sept. 11, 2024, 7:12 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| tpar | R Documentation |
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(...)
Arguments
... |
arguments of the form |
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
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. |
|
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")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.