Package 'papersize'

Horizontal range the wave spans.

Baseline (vertical center) the wave oscillates around, Default: 0

Height of the wave above and below y, Default: 1

Horizontal distance the wave takes to complete one full cycle, Default: 2

Horizontal shift of the wave, in radians, Default: 0

Number of points used to draw the curve. Higher values produce a smoother "wave" curve. Ignored for "zigzag", Default: 200

Aesthetics passed to ggplot2::geom_line(), Default: "black", 1, and "round"

Either "wave" for a smooth sine curve or "zigzag" for an angular zigzag (triangle wave) between the same peaks and troughs, Default: "wave"

Additional arguments passed to ggplot2::annotate().

Aspect ratio of width to height as a numeric value (e.g. 0.33) or characters separated by a colon (e.g. "1:3"). If numeric, as_asp() returns the value of asp without modification.

If character, page is passed as the name parameter to get_page_size().

Page orientation, Default: NULL. Supported options are "portrait", "landscape", or "square".

If TRUE, return aspect ratio of height to width (y / x), instead of width to height.

Separator character to use if asp is a character vector. Defaults to ":".

Length 2 character vector with column names for page dimensions. Defaults to c("width", "height").

Arguments passed on to get_page_size

name

Page name, e.g. "letter", not case sensitive, Default: NULL

width

Page width in "in", "px" or "mm" units. Default: NULL

height

Page height in "in", "px" or "mm" units. Default: NULL

reorient

If TRUE and orientation is not NULL, flip width and height dimensions for any pages that do not match the provided orientation. Set reorient = FALSE to filter pages by orientation.

type

Page type, Options include "paper", "social", "postcard", "print", "card", or "screen". Default: NULL

ignore.case

If FALSE, filtering for page and type are case sensitive. Defaults to TRUE.

arg,call

Passed to cli_abort() to improve internal error messages.

units

Units to convert page dimensions to using convert_unit_type().

valueOnly

Passed to valueOnly parameter of grid::convertUnit(). Defaults to FALSE.

A character vector passed to the name parameter of get_page_size(), a named list of vector passed to dims for make_page_size(), or a length 2 numeric vector passed as the width and height parameter to make_page_size(). If x is a character string that does not match any of the names in paper_sizes, x is passed as the name parameter to make_page_size()

Arguments passed on to make_page_size

width,height

Page width and height. Both are required, if asp is NULL. Default to NULL.

units

Units for width and height. Required unless units is included in dims or require_units = FALSE. Passed to as_unit_type() to validate.

asp

Aspect ratio. Required if only one of width or height are provided.

name

Optional name for paper size. Recommend avoiding duplication with existing names in paper_sizes.

dims

A list or data.frame that can be used to set width, height, units, and/or asp.

orientation

Page orientation, Default: NULL. Supported options are "portrait", "landscape", or "square". If width and height suggest a portrait orientation when orientation = "landscape", the dimensions are reversed so the page dimensions match the provided orientation.

require_units

If TRUE (default), units must be supplied (either directly or via dims) or the function errors. Set require_units = FALSE to allow units to be omitted, e.g. for use by get_page_dims() where a unitless width and height are valid input. If units is omitted and require_units = FALSE, the returned page has no units column.

valid_units

Character vector with name or symbols for valid units. Defaults to NULL but any other unit name or symbol, e.g. "px", is permitted.

call

The execution environment of a currently running function, e.g. call = caller_env(). The corresponding function call is retrieved and mentioned in error messages as the source of the error.

You only need to supply call when throwing a condition from a helper function which wouldn't be relevant to mention in the message.

Can also be NULL or a defused function call to respectively not display any call or hard-code a code to display.

For more information about error calls, see Including function calls in error messages.

Column names to use for width and height columns. Defaults to c("width", "height"). Must be length 2 and the first value is always used as as the width name and the second as the height.

Class of return object: "data.frame" (default) or "list" (only supported when input page size is a single row).

Not used.

Number of sheets or cards in the stack. Ignored if x is supplied. Either n or x must be supplied.

Caliper thickness of a single sheet or card, in points (1/1000 in). Ignored if x is supplied. Default: 10, a typical thickness for a playing card.

Optional. A known stack thickness (numeric or unit object). If supplied, n and pt are ignored.

A character vector specifying the units for the corresponding numeric values.

A numeric vector.

For is.unit, any R object.

A character vector specifying the units for the corresponding numeric values.

This argument is used to supply extra information for special unit types.

Whether to recurse into complex units.

Passed to cli_abort() to improve internal error messages.

The execution environment of a currently running function, e.g. call = caller_env(). The corresponding function call is retrieved and mentioned in error messages as the source of the error.

You only need to supply call when throwing a condition from a helper function which wouldn't be relevant to mention in the message.

Can also be NULL or a defused function call to respectively not display any call or hard-code a code to display.

For more information about error calls, see Including function calls in error messages.

Character vector with name or symbols for valid units. Defaults to NULL but any other unit name or symbol, e.g. "px", is permitted.

Unit to convert from. If NULL and x is not a units object, convert to to units with a warning.

Unit to convert to. Passed to unitTo parameter of grid::convertUnit(). If NULL, return x as is.

Passed to typeFrom parameter of grid::convertUnit(). Defaults to "dimension".

Passed to valueOnly parameter of grid::convertUnit(). Defaults to FALSE.

Arguments passed on to grid::convertUnit

axisFrom

Either "x" or "y" to indicate whether the unit object represents a value in the x- or y-direction.

axisTo

Same as axisFrom, but applies to the unit object that is to be created.

typeTo

Same as typeFrom, but applies to the unit object that is to be created.

Object to compare to x.

distance to convert. If paper is provided, dist is optional and paper width and height are used as dist.

Scale name from standard_scales[["scale"]].

Scale standard. Options include "USGS", "Engineering", or "Architectural".

Map series from standard_scales[["series"]]. Series is only available for USGS scales.

"mm" (converted to cm by dividing by 10), "cm", "px" (converted to inches by dividing by dpi), or "in".

factor for converting from scale_unit to actual_unit, e.g. if 1" = 1', the scale factor is 12. optional if scale if provided; defaults to NULL.

any unit supported by convert_dist_units()

dots per square inch (used as conversion factor for "px" to "in")

Name of paper passed to get_paper()

Page orientation, Default: NULL. Supported options are "portrait", "landscape", or "square".

Arguments passed on to get_paper

name

Page name, e.g. "letter", not case sensitive, Default: NULL

width

Page width in "in", "px" or "mm" units. Default: NULL

height

Page height in "in", "px" or "mm" units. Default: NULL

reorient

If TRUE and orientation is not NULL, flip width and height dimensions for any pages that do not match the provided orientation. Set reorient = FALSE to filter pages by orientation.

type

Page type, Options include "paper", "social", "postcard", "print", "card", or "screen". Default: NULL

ignore.case

If FALSE, filtering for page and type are case sensitive. Defaults to TRUE.

page

Used by get_page_dims(), page is either a character vector passed to the name parameter of get_page_size(), a data.frame with column names matching the cols parameter, or a length 2 numeric vector with the page width and height.

cols

Length 2 character vector with column names for page dimensions. Defaults to c("width", "height").

arg,call

Passed to cli_abort() to improve internal error messages.

units

Units to convert page dimensions to using convert_unit_type().

valueOnly

Passed to valueOnly parameter of grid::convertUnit(). Defaults to FALSE.

Numeric or units object

Existing unit for dist, Default: NULL. If dist is a units object, the numerator is used as "from"

Unit to convert distance to, Default: 'meter'

If TRUE, return numeric. If FALSE, return class units object.

Number of digits to include in result; defaults to NULL.

Page name, e.g. "letter", not case sensitive, Default: NULL

Page width in "in", "px" or "mm" units. Default: NULL

Page height in "in", "px" or "mm" units. Default: NULL

Page orientation, Default: NULL. Supported options are "portrait", "landscape", or "square".

If TRUE and orientation is not NULL, flip width and height dimensions for any pages that do not match the provided orientation. Set reorient = FALSE to filter pages by orientation.

Units to convert page dimensions to using convert_unit_type().

Page type, Options include "paper", "social", "postcard", "print", "card", or "screen". Default: NULL

If FALSE, filtering for page and type are case sensitive. Defaults to TRUE.

Used by get_page_dims(), page is either a character vector passed to the name parameter of get_page_size(), a data.frame with column names matching the cols parameter, or a length 2 numeric vector with the page width and height.

Length 2 character vector with column names for page dimensions. Defaults to c("width", "height").

Passed to cli_abort() to improve internal error messages.

Additional parameters passed by get_page_dims() to get_page_size() if page is a character object.

Passed to valueOnly parameter of grid::convertUnit(). Defaults to FALSE.

Scale name from standard_scales[["scale"]].

Scale standard. Options include "USGS", "Engineering", or "Architectural".

Map series from standard_scales[["series"]]. Series is only available for USGS scales.

Image size name, Default: NULL

Social media platform, "Instagram", "Facebook", or "Twitter", Default: NULL

Image format, "post", "story", or "cover", Default: NULL

Image orientation, Default: NULL.

Plot to save, defaults to last plot displayed. If plot is an "magick-image" class object, it is converted to a plot using magick::image_ggplot()

Plot name, used to create filename (if filename is NULL) using filenamr::make_filename()

Label to combine with name converted to snake case with janitor::make_clean_names(). The label is designed to identify the area or other shared characteristics across multiple data files, maps, or plots. label is ignored if name is NULL or if name includes a file extension.

File name prefix. "date" adds a date prefix, "time" adds a date/time prefix; defaults to NULL.

File name postfix; defaults to NULL.

If TRUE, increment digits in string by 1. If numeric, increment digits in string by value. If NULL, 0, or if no digits are present in string, return string as is.

File name to create on disk.

Device to use. Can either be a device function (e.g. png), or one of "eps", "ps", "tex" (pictex), "pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only). If NULL (default), the device is guessed based on the filename extension.

File type or extension. Optional if filename or path include a file extension.

File type (used if fileext is NULL).

Path of the directory to save plot to: path and filename are combined to create the fully qualified file name. Defaults to the working directory.

Paper matching name from paper_sizes (e.g. "letter"). Not case sensitive.

Page orientation ("portrait", "landscape", or "square").

Plot size in units expressed by the units argument. If not supplied, uses the size of the current graphics device.

Numeric aspect ratio used to determine width or height if only one of the two arguments is provided; defaults to NULL.

One of the following units in which the width and height arguments are expressed: "in", "cm", "mm" or "px".

Multiplicative scaling factor.

Plot resolution. Also accepts a string input: "retina" (320), "print" (300), or "screen" (72). Only applies when converting pixel units, as is typical for raster output types.

Background color to optionally override plot.background theme element.

If TRUE, the EXIF metadata for the exported file is updated with the exifr package; defaults to FALSE.

Title to add to file metadata with exiftoolr, Default: NULL.

Author to add to file metadata to the "Author" and "XMP-dc:creator" tags. Default: NULL.

Keyword(s) added to file metadata to "IPTC:Keywords" and "XMP-dc:Subject" tags. Defaults to NULL.

Alternate arguments passed to exiftoolr::exif_call(). Other tag parameters are appended to args if they are not NULL.

If TRUE (default), overwrite any existing file with the same name or ask to overwrite if ask = TRUE. Passed to filenamr::check_file_overwrite().

If TRUE, ask before overwriting file with the same name. Defaults to FALSE. Passed to filenamr::check_file_overwrite().

If TRUE, open saved file in default system application. Based on ggpreview from tjmisc package.

When TRUE (the default), ggsave() will not save images larger than 50x50 inches, to prevent the common error of specifying dimensions in pixels.

If TRUE (default), suppress function messages.

Arguments passed on to ggplot2::ggsave

create.dir

Whether to create new directories if a non-existing directory is specified in the filename or path (TRUE) or return an error (FALSE, default). If FALSE and run in an interactive session, a prompt will appear asking to create a new directory when necessary.

Image name passed to name parameter of get_social_size().

Social media platform, "Instagram", "Facebook", or "Twitter", Default: NULL

Image format, "post", "story", or "cover", Default: NULL

If TRUE, use gridExtra::arrangeGrob() to create an arrangelist class object that ggplot2::ggsave() can save as a single multi-page file. Note: this does not work with plots modified with patchwork including inset maps created with the maplayer::layer_inset() function.

A grob, ggplot, patchwork, formula, raster, nativeRaster, or gt object to add as an inset

Page size data.frame to use for inset, Default: NULL

numerics or units giving the location of the outer bounds. If given as numerics and inset_page is NULL, they will be converted to npc units. All four are required if inset_page is NULL. If inset_page is provided, top or bottom and left or right must be provided as the inset element is expected to be the width and height defined by inset_page.

Specifies what left, bottom, etc should be relative to. Either 'panel' (default), 'plot', or 'full'.

Logical. Should the inset be placed on top of the other plot or below (but above the background)?

Logical. Should clipping be performed on the inset?

Logical. Should autotagging ignore the inset?

Arguments passed on to convert_unit_type

arg

Passed to cli_abort() to improve internal error messages.

valid_units

Character vector with name or symbols for valid units. Defaults to NULL but any other unit name or symbol, e.g. "px", is permitted.

from

Unit to convert from. If NULL and x is not a units object, convert to to units with a warning.

to

Unit to convert to. Passed to unitTo parameter of grid::convertUnit(). If NULL, return x as is.

typeFrom

Passed to typeFrom parameter of grid::convertUnit(). Defaults to "dimension".

valueOnly

Passed to valueOnly parameter of grid::convertUnit(). Defaults to FALSE.

y

Object to compare to x.

x

A numeric vector.

For is.unit, any R object.

units

A character vector specifying the units for the corresponding numeric values.

data

This argument is used to supply extra information for special unit types.

call

The execution environment of a currently running function, e.g. call = caller_env(). The corresponding function call is retrieved and mentioned in error messages as the source of the error.

You only need to supply call when throwing a condition from a helper function which wouldn't be relevant to mention in the message.

Can also be NULL or a defused function call to respectively not display any call or hard-code a code to display.

For more information about error calls, see Including function calls in error messages.

recurse

Whether to recurse into complex units.

objects to check

Used internally and passed to rlang::arg_match() as error arg or used by cli::cli_abort() to improve error messages.

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

Distance units to convert to. Must be one of dist_unit_options or area_unit_options.

File path or data.frame from filenamr::read_exif()

Image dimensions in same dimensions as page. Required.

The dimensions of the grid to create. If both are NULL, dims will be used or dims will be determined based on the plot dimensions.

Template for caption, passed to glue::glue_data() using the images data.frame as .x. Note that this template may vary if you are using a custom tags parameter or modify the "filenamr.exif_xwalk" option. See filenamr::read_exif() for more details. Default: "{file_name}\n{date_created}"

Caption size, passed to ggplot2::element_text() for plot.caption for theme, Default: 12

Caption position, passed to plot.caption.position for theme, Default: 'panel'

Image margin passed Default: margins(0.1, unit = "in")

Paper name or a data.frame with width and height columns. Optional if width and height are both provided, Default: NULL. If ncol and nrow are also supplied, page is not used to determine the grid size — but if margin or marks are used, page must still be set to the exact final output size (the same width/height you plan to pass to ggplot2::ggsave()), not just the combined size of the grid of plots. See margin and marks for why this matters.

Paper orientation, Optional if width and height are both provided, Default: 'landscape'

Maximum number of images to use for contact sheets.

Passed to fileext parameter of filenamr::read_exif(), Default: NULL

List of EXIF tags to read from files. If NULL (default), set to option "filenamr.exif_tags" or default default_exif_tags.

Time zone to pass to lubridate::ymd_hms() if format_exif is TRUE. Typically set to Sys.timezone() to convert date/time columns.

If TRUE, save contact sheet to a file. filename may be required if save is TRUE. Default: FALSE

File name to create on disk.

Additional parameters passed to map_ggsave_ext() excluding width, height, and units.

Page width and height. Both are required, if asp is NULL. Default to NULL.

Units for width and height. Required unless units is included in dims or require_units = FALSE. Passed to as_unit_type() to validate.

Aspect ratio. Required if only one of width or height are provided.

Page orientation, Default: NULL. Supported options are "portrait", "landscape", or "square". If width and height suggest a portrait orientation when orientation = "landscape", the dimensions are reversed so the page dimensions match the provided orientation.

Optional name for paper size. Recommend avoiding duplication with existing names in paper_sizes.

A list or data.frame that can be used to set width, height, units, and/or asp.

Character vector with name or symbols for valid units. Defaults to NULL but any other unit name or symbol, e.g. "px", is permitted.

Column names to use for width and height columns. Defaults to c("width", "height"). Must be length 2 and the first value is always used as as the width name and the second as the height.

Class of return object: "data.frame" (default) or "list" (only supported when input page size is a single row).

If TRUE (default), units must be supplied (either directly or via dims) or the function errors. Set require_units = FALSE to allow units to be omitted, e.g. for use by get_page_dims() where a unitless width and height are valid input. If units is omitted and require_units = FALSE, the returned page has no units column.

The execution environment of a currently running function, e.g. call = caller_env(). The corresponding function call is retrieved and mentioned in error messages as the source of the error.

You only need to supply call when throwing a condition from a helper function which wouldn't be relevant to mention in the message.

Can also be NULL or a defused function call to respectively not display any call or hard-code a code to display.

For more information about error calls, see Including function calls in error messages.

A numeric list or vector or a margin class object. For get_margin() only, margin can be a margin name from page_extras[["margins"]]. Defaults to NULL.

Additional numeric values combined with margin if provided.

Default units for margins (ignored if margin is a margin class object). Passed to as_unit_type() so units class objects as well as unit names supported grid::unit() are allowed. Defaults to "in" except for margin() where unit defaults to "pt" to match ggplot2::margin().

Object to check for class margin and unit

Page name, a data.frame with width and height columns, or a list of ggplot2 objects with card plots. Default: NULL

Paper name or a data.frame with width and height columns. Optional if width and height are both provided, Default: NULL. If ncol and nrow are also supplied, page is not used to determine the grid size — but if margin or marks are used, page must still be set to the exact final output size (the same width/height you plan to pass to ggplot2::ggsave()), not just the combined size of the grid of plots. See margin and marks for why this matters.

Paper width and height, Default: NULL

Paper orientation, Optional if width and height are both provided, Default: 'landscape'

Analogous to byrow in matrix(). If FALSE the plots will be filled in in column-major order

A string specifying how guides should be treated in the layout. 'collect' will collect guides below to the given nesting level, removing duplicates. 'keep' will stop collection at this level and let guides be placed alongside their plot. auto will allow guides to be collected if a upper level tries, but place them alongside the plot if not. If you modify default guide "position" with theme(legend.position=...) while also collecting guides you must apply that change to the overall patchwork (see example).

A string ('keep' or 'new') to indicate how auto-tagging should behave. See plot_annotation().

Specification of the location of areas in the layout. Can either be specified as a text string or by concatenating calls to area() together. See the examples for further information on use.

If TRUE, create a list of patchwork objects when the number of plots is greater than the number of spaces in the plot layout. Default to TRUE.

The dimensions of the grid to create. If both are NULL, dims will be used or dims will be determined based on the plot dimensions.

Optional. Plot dimensions. Ignored if ncol and nrow are supplied. Otherwise, if NULL (default), dims are inferred based on the dimensions of the first plot in plots.

Optional. Spacing to add between plots in the grid, as a single number (used for both row and column spacing), a length-2 numeric vector c(row, col), or a named vector or list with row and col elements. Interpreted in unit. Implemented by adding half of gutter to the interior-facing sides of each plot's own plot.margin (so two adjacent plots each contribute half, summing to the full gutter between them) based on its row/column position in the ncol x nrow grid — this replaces each plot's existing plot.margin. Plots on the outer edge of the grid are not padded on their outward-facing side; use margin for space around the outside of the whole grid. Default: NULL (no extra spacing).

gutter changes the total size of the combined grid (adding (ncol - 1) * col_gutter and (nrow - 1) * row_gutter), which marks accounts for automatically — the automatic ncol/nrow calculation from page/dims also reserves room for it, so fewer plots may fit per page than with gutter = 0.

Optional. A margin to add around the outside of the combined grid of plots, e.g. so the grid can be centered on a larger sheet of paper when saved with ggplot2::ggsave(). Passed to get_margin() with unit. The margin pads the composed page rather than the individual plots in plots, and does not affect the number of rows and columns in the grid. Default: NULL, which computes a margin from position whenever plot dimensions are known (supplied via dims, or auto-detected from the first plot) — see position. Set margin explicitly to override that (or to add a margin when dimensions aren't known, e.g. ncol/ nrow supplied without dims).

margin itself always renders correctly regardless of page, because it is applied as a fixed absolute-unit margin around whatever canvas size ggplot2::ggsave() is eventually called with. marks, below, is the one that depends on page being set correctly — see marks.

Where to place plots on page when they don't fill it completely — e.g. fewer plots than the page has room for, or a remainder page when paginate splits a longer list. One of "top-left" (default), "top", "top-right", "left", "center", "right", "bottom-left", "bottom", or "bottom-right". Only takes effect when plot dimensions are known (see margin) and margin isn't supplied directly; the grid is first shrunk to just the rows/columns needed for the plots being placed (rather than the full page capacity), then the leftover page space is split into a margin that pushes that grid toward the requested anchor — "center" splits leftover space evenly on both axes, "top-left" (matching the pre-existing default behavior) assigns it all to the bottom/right, and so on.

Unit used for gutter, and for margin if margin is a bare numeric vector or list (ignored for margin if it is a unit class object; gutter does not support unit class objects). Default: "in".

If TRUE, add crop marks in the margin area showing where to cut the page into individual plots. Requires margin. Marks are placed assuming the grid of plots exactly fills the page after subtracting margin, i.e. the same assumption margin itself relies on. Default: FALSE.

Unlike margin, marks reads page (via get_page_dims()) to work out where the margin area is, so page must equal the exact final output size — the same width/height you pass to ggsave() — even if ncol/nrow are supplied directly and page would otherwise be unused. Passing just the combined size of the grid of plots (i.e. page without margin added on) will place the marks in the wrong location, because ggplot2::ggsave() will render a larger canvas than marks was calculated for.

Not yet implemented. If TRUE and dims is NULL, the input plots are assumed to be plots created with magick::image_ggplot() and dpi is used to infer dimensions.

Not yet implemented. Resolution.

Optional. Column widths and row heights passed to patchwork::wrap_plots(). By default (NULL), and whenever plot dimensions are known (supplied via dims, or auto-detected from the first plot), each column/row is pinned to that exact size — so plots keep their true physical size instead of patchwork's own proportional division of space, which only happens to line up with each plot's true size when plots exactly fills every cell of the grid with same-sized content. Pass widths/heights explicitly (as unit objects, one per column/row) to override this.

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

A page size data.frame from get_page_size() or a data.frame or list from make_page_size().

A numeric list or vector or a margin class object. Defaults to NULL. margins are removed from the overall layout width and height.

Optional. An additional page data.frame where the region width and height are used as the column width and row height.

An integer describing the number of columns in the layout.

An integer describing the number of rows in the layout.

Gutter width/height. Not yet implemented.

A numeric vector or unit object describing the widths of the columns in the layout.

A numeric vector or unit object describing the heights of the rows in the layout.

Passed to default.units parameter of grid::grid.layout().

A logical value or a numeric matrix. If a logical, this indicates whether row heights and column widths should respect each other. If a matrix, non-zero values indicate that the corresponding row and column should be respected (see examples below).

A string or numeric vector specifying how the layout should be justified if it is not the same size as its parent viewport. If there are two values, the first value specifies horizontal justification and the second value specifies vertical justification. Possible string values are: "left", "right", "centre", "center", "bottom", and "top". For numeric values, 0 means left alignment and 1 means right alignment. NOTE that in this context, "left", for example, means align the left edge of the left-most layout column with the left edge of the parent viewport.

Column names to use for width and height columns. Defaults to c("width", "height"). Must be length 2 and the first value is always used as as the width name and the second as the height.

A page data.frame from get_page_size() or make_page_size().

A character value to uniquely identify the viewport once it has been pushed onto the viewport tree.

Column names to use for width and height columns. Defaults to c("width", "height"). Must be length 2 and the first value is always used as as the width name and the second as the height.

Arguments passed on to grid::viewport

x

A numeric vector or unit object specifying x-location.

y

A numeric vector or unit object specifying y-location.

just

A string or numeric vector specifying the justification of the viewport relative to its (x, y) location. If there are two values, the first value specifies horizontal justification and the second value specifies vertical justification. Possible string values are: "left", "right", "centre", "center", "bottom", and "top". For numeric values, 0 means left alignment and 1 means right alignment.

gp

An object of class "gpar", typically the output from a call to the function gpar. This is basically a list of graphical parameter settings.

clip

One of "on", "inherit", or "off", indicating whether to clip to the extent of this viewport, inherit the clipping region from the parent viewport, or turn clipping off altogether. For back-compatibility, a logical value of TRUE corresponds to "on" and FALSE corresponds to "inherit".

May also be a grob (or a gTree) that describes a clipping path or the result of a call to as.path.

mask

One of "none" (or FALSE) or "inherit" (or TRUE) or a grob (or a gTree) or the result of call to as.mask. This specifies that the viewport should have no mask, or it should inherit the mask of its parent, or it should have its own mask, as described by the grob.

xscale

A numeric vector of length two indicating the minimum and maximum on the x-scale. The limits may not be identical.

yscale

A numeric vector of length two indicating the minimum and maximum on the y-scale. The limits may not be identical.

angle

A numeric value indicating the angle of rotation of the viewport. Positive values indicate the amount of rotation, in degrees, anticlockwise from the positive x-axis.

layout

A Grid layout object which splits the viewport into subregions.

layout.pos.row

A numeric vector giving the rows occupied by this viewport in its parent's layout.

layout.pos.col

A numeric vector giving the columns occupied by this viewport in its parent's layout.

parent

A grid viewport object.

children

A vpList object.

Paper, page, or card name, or a data.frame with width and height columns (as returned by get_page_size() or make_page_size()), passed to as_page(). Sets the width and height of the stack of cards or paper the band wraps around.

Band orientation, either "horizontal" or "vertical". "horizontal" wraps the band left-to-right, crossing the middle of the stack, so the band's panels use the width of paper and the band's own height is set by band_width. "vertical" wraps the band top-to-bottom instead, so the panels use height and the band's own width is set by band_width. Default: "horizontal"

Passed to as_thickness() to calculate the thickness of the stack. Ignored if thickness is supplied. pt is also used to add a small ease allowance (the caliper of a single sheet or card) to the folded side segments of the band, since a flat band can't wrap tightly around a stack at its exact thickness. Ignored if thickness is supplied.

Optional. A unit object or number (in the units of paper) with the thickness of the stack, overriding n, pt, and x. If supplied, no ease allowance is added and thickness sets the folded side segments of the band exactly. Default: NULL

Distance the band extends past the far edge of the stack, forming a segment that can be glued or taped closed. A unit object or a number (in the units of paper). Default: NULL, which uses 40% of the width of paper (if orientation is "horizontal") or 40% of the height of paper (if orientation is "vertical") — i.e. 40% of whichever dimension of paper the band wraps around.

Height of the band if orientation is "horizontal", or width of the band if orientation is "vertical" — the dimension of the band perpendicular to the direction it wraps around the stack. A unit object or a number (in the units of paper). Default: NULL, which uses 40% of the height of paper (if orientation is "horizontal") or 40% of the width of paper (if orientation is "vertical").

Fill, outline color, and outline linewidth for the band, Default: "white", "black", and 0.5

Fill color used to distinguish the overlapping segment of the band set by overlap, Default: "grey85"

Linetype and linewidth for the lines marking where the band should be folded, Default: "dashed" and linewidth / 2

Paper, page, or card name, or a data.frame with width and height columns (as returned by get_page_size() or make_page_size()), passed to as_page(). Sets the width and height of the stack of cards or paper the band wraps around.

Band orientation, either "horizontal" or "vertical". "horizontal" wraps the band left-to-right, crossing the middle of the stack, so the band's panels use the width of paper and the band's own height is set by band_width. "vertical" wraps the band top-to-bottom instead, so the panels use height and the band's own width is set by band_width. Default: "horizontal"

Passed to as_thickness() to calculate the thickness of the stack. Ignored if thickness is supplied. pt is also used to add a small ease allowance (the caliper of a single sheet or card) to the folded side segments of the band, since a flat band can't wrap tightly around a stack at its exact thickness. Ignored if thickness is supplied.

Optional. A unit object or number (in the units of paper) with the thickness of the stack, overriding n, pt, and x. If supplied, no ease allowance is added and thickness sets the folded side segments of the band exactly. Default: NULL

Distance the band extends past the far edge of the stack, forming a segment that can be glued or taped closed. A unit object or a number (in the units of paper). Default: NULL, which uses 40% of the width of paper (if orientation is "horizontal") or 40% of the height of paper (if orientation is "vertical") — i.e. 40% of whichever dimension of paper the band wraps around.

Height of the band if orientation is "horizontal", or width of the band if orientation is "vertical" — the dimension of the band perpendicular to the direction it wraps around the stack. A unit object or a number (in the units of paper). Default: NULL, which uses 40% of the height of paper (if orientation is "horizontal") or 40% of the width of paper (if orientation is "vertical").

Paper, page, or card name, or a data.frame with width and height columns (as returned by get_page_size() or make_page_size()), passed to as_page(). Sets the width and height of the stack of cards or paper the band wraps around.

Band orientation, either "horizontal" or "vertical". "horizontal" wraps the band left-to-right, crossing the middle of the stack, so the band's panels use the width of paper and the band's own height is set by band_width. "vertical" wraps the band top-to-bottom instead, so the panels use height and the band's own width is set by band_width. Default: "horizontal"

Passed to as_thickness() to calculate the thickness of the stack. Ignored if thickness is supplied. pt is also used to add a small ease allowance (the caliper of a single sheet or card) to the folded side segments of the band, since a flat band can't wrap tightly around a stack at its exact thickness. Ignored if thickness is supplied.

Optional. A unit object or number (in the units of paper) with the thickness of the stack, overriding n, pt, and x. If supplied, no ease allowance is added and thickness sets the folded side segments of the band exactly. Default: NULL

Distance the band extends past the far edge of the stack, forming a segment that can be glued or taped closed. A unit object or a number (in the units of paper). Default: NULL, which uses 40% of the width of paper (if orientation is "horizontal") or 40% of the height of paper (if orientation is "vertical") — i.e. 40% of whichever dimension of paper the band wraps around.

Height of the band if orientation is "horizontal", or width of the band if orientation is "vertical" — the dimension of the band perpendicular to the direction it wraps around the stack. A unit object or a number (in the units of paper). Default: NULL, which uses 40% of the height of paper (if orientation is "horizontal") or 40% of the width of paper (if orientation is "vertical").

Fill, outline color, and outline linewidth for the band, Default: "white", "black", and 0.5

Fill color used to distinguish the overlapping segment of the band set by overlap, Default: "grey85"

Linetype and linewidth for the lines marking where the band should be folded, Default: "dashed" and linewidth / 2

Paper name or a data.frame with width and height columns, passed to page_layout(). Default: "letter"

Page orientation, passed to page_layout()'s orientation parameter (kept as a separate parameter here to avoid a name clash with the band's own orientation). Default: NULL, which uses page as supplied without reorienting it (unlike page_layout() itself, which defaults to "landscape").

Number of copies of the band to arrange on page. Default: 1

The dimensions of the grid to create. If both are NULL, dims will be used or dims will be determined based on the plot dimensions.

Analogous to byrow in matrix(). If FALSE the plots will be filled in in column-major order

Optional. Spacing to add between plots in the grid, as a single number (used for both row and column spacing), a length-2 numeric vector c(row, col), or a named vector or list with row and col elements. Interpreted in unit. Implemented by adding half of gutter to the interior-facing sides of each plot's own plot.margin (so two adjacent plots each contribute half, summing to the full gutter between them) based on its row/column position in the ncol x nrow grid — this replaces each plot's existing plot.margin. Plots on the outer edge of the grid are not padded on their outward-facing side; use margin for space around the outside of the whole grid. Default: NULL (no extra spacing).

gutter changes the total size of the combined grid (adding (ncol - 1) * col_gutter and (nrow - 1) * row_gutter), which marks accounts for automatically — the automatic ncol/nrow calculation from page/dims also reserves room for it, so fewer plots may fit per page than with gutter = 0.

Optional. A margin to add around the outside of the combined grid of plots, e.g. so the grid can be centered on a larger sheet of paper when saved with ggplot2::ggsave(). Passed to get_margin() with unit. The margin pads the composed page rather than the individual plots in plots, and does not affect the number of rows and columns in the grid. Default: NULL, which computes a margin from position whenever plot dimensions are known (supplied via dims, or auto-detected from the first plot) — see position. Set margin explicitly to override that (or to add a margin when dimensions aren't known, e.g. ncol/ nrow supplied without dims).

margin itself always renders correctly regardless of page, because it is applied as a fixed absolute-unit margin around whatever canvas size ggplot2::ggsave() is eventually called with. marks, below, is the one that depends on page being set correctly — see marks.

Where to place the bands on page when n_bands doesn't fill it completely. Passed to page_layout()'s position parameter, but defaults to "center" here rather than page_layout()'s own "top-left" default.

Unit used for gutter, and for margin if margin is a bare numeric vector or list (ignored for margin if it is a unit class object; gutter does not support unit class objects). Default: "in".

If TRUE, add crop marks in the margin area showing where to cut the page into individual plots. Requires margin. Marks are placed assuming the grid of plots exactly fills the page after subtracting margin, i.e. the same assumption margin itself relies on. Default: FALSE.

Unlike margin, marks reads page (via get_page_dims()) to work out where the margin area is, so page must equal the exact final output size — the same width/height you pass to ggsave() — even if ncol/nrow are supplied directly and page would otherwise be unused. Passing just the combined size of the grid of plots (i.e. page without margin added on) will place the marks in the wrong location, because ggplot2::ggsave() will render a larger canvas than marks was calculated for.

If TRUE, create a list of patchwork objects when the number of plots is greater than the number of spaces in the plot layout. Default to TRUE.

Card name or data.frame with width and height columns.

Number of cards to plot, Default: 1

Card orientation, Default: 'portrait'

If TRUE, add a number to each card, Default: FALSE

Color for number, text, and border, Default: 'white'

Font size for number and text, Default: 5

Font family for number and text, Default: 'Georgia'

Length 1 or 2 character vector with color name. If length 2, the first value is assumed to be the card fill and the second value is assumed to be the inset border fill. Default: 'gray20'

If TRUE, add a border to the card. Default: FALSE

Unit or numeric vector with inset distance for card border, Default: grid::unit(c(5, 5), "mm"). If inset is a numeric vector, it is expected to be a percent relative to the card width and height.

linetype for card border, Default: 'dashed'

linewidth for card border, Default: 2

Character vector with card text, Default: NULL

Position of card center, Default: c(0, 0)

Plot to display

A page data.frame from get_page_size() or make_page_size().

draw new (empty) page first?

viewport to draw plot in

Arguments passed on to page_to_viewport, page_to_layout

name

A character value to uniquely identify the viewport once it has been pushed onto the viewport tree.

cols

Column names to use for width and height columns. Defaults to c("width", "height"). Must be length 2 and the first value is always used as as the width name and the second as the height.

margins

A numeric list or vector or a margin class object. Defaults to NULL. margins are removed from the overall layout width and height.

region

Optional. An additional page data.frame where the region width and height are used as the column width and row height.

gutter

Gutter width/height. Not yet implemented.

units

Passed to default.units parameter of grid::grid.layout().

widths

A numeric vector or unit object describing the widths of the columns in the layout.

heights

A numeric vector or unit object describing the heights of the rows in the layout.

respect

A logical value or a numeric matrix. If a logical, this indicates whether row heights and column widths should respect each other. If a matrix, non-zero values indicate that the corresponding row and column should be respected (see examples below).

just

A string or numeric vector specifying how the layout should be justified if it is not the same size as its parent viewport. If there are two values, the first value specifies horizontal justification and the second value specifies vertical justification. Possible string values are: "left", "right", "centre", "center", "bottom", and "top". For numeric values, 0 means left alignment and 1 means right alignment. NOTE that in this context, "left", for example, means align the left edge of the left-most layout column with the left edge of the parent viewport.

Row and column position. If nrow is smaller than row_position or ncol is smaller than col_position, row_position is used for nrow or col_position is used for ncol instead.

Row height and column width.

An integer describing the number of rows in the layout.

An integer describing the number of columns in the layout.

Passed to page_to_viewport() with layout_position as layout.pos.row and layout.pos.col if provided. Defaults to NULL where layout is defined by page_to_layout using ncol, nrow, page and any additional parameters passed to ...

A grid viewport object.

A vpList object.

File name to create on disk.

If character, page is passed as the name parameter to get_page_size().

A vector or list with values in the same order as cols (defaults to ⁠c(<width>, <height>)⁠ to match cols).

Page width and height. Both are required, if asp is NULL. Default to NULL.

Units for width and height. Required unless units is included in dims or require_units = FALSE. Passed to as_unit_type() to validate.

Column names to use for width and height columns. Defaults to c("width", "height"). Must be length 2 and the first value is always used as as the width name and the second as the height.

Page orientation, Default: NULL. Supported options are "portrait", "landscape", or "square". If width and height suggest a portrait orientation when orientation = "landscape", the dimensions are reversed so the page dimensions match the provided orientation.

Positive numeric value above or below 1 used to determine if an aspect ratio is square, landscape, or portrait.

If TRUE, return aspect ratio of height to width (y / x), instead of width to height.

A character vector with a page size name or a data.frame. Passed to x parameter of as_page().

Passed to get_margin() with unit value.

Unit used for the margin. If margin is a unit object, unit is ignored. If page uses different units, the margins are converted into the page units for consistency.

Column names to use for width and height columns. Defaults to c("width", "height"). Must be length 2 and the first value is always used as as the width name and the second as the height.

Passed to as_page() with page and cols.

If character, page is passed as the name parameter to get_page_size().

Page orientation, Default: NULL. Supported options are "portrait", "landscape", or "square".

Arguments passed on to ggplot2::theme

line

all line elements (element_line())

rect

all rectangular elements (element_rect())

text

all text elements (element_text())

title

all title elements: plot, axes, legends (element_text(); inherits from text)

point

all point elements (element_point())

polygon

all polygon elements (element_polygon())

geom

defaults for geoms (element_geom())

spacing

all spacings (unit())

margins

all margins (margin())

aspect.ratio

aspect ratio of the panel

axis.title,axis.title.x,axis.title.y,axis.title.x.top,axis.title.x.bottom,axis.title.y.left,axis.title.y.right

labels of axes (element_text()). Specify all axes' labels (axis.title), labels by plane (using axis.title.x or axis.title.y), or individually for each axis (using axis.title.x.bottom, axis.title.x.top, axis.title.y.left, axis.title.y.right). ⁠axis.title.*.*⁠ inherits from ⁠axis.title.*⁠ which inherits from axis.title, which in turn inherits from text

axis.text,axis.text.x,axis.text.y,axis.text.x.top,axis.text.x.bottom,axis.text.y.left,axis.text.y.right,axis.text.theta,axis.text.r

tick labels along axes (element_text()). Specify all axis tick labels (axis.text), tick labels by plane (using axis.text.x or axis.text.y), or individually for each axis (using axis.text.x.bottom, axis.text.x.top, axis.text.y.left, axis.text.y.right). ⁠axis.text.*.*⁠ inherits from ⁠axis.text.*⁠ which inherits from axis.text, which in turn inherits from text

axis.ticks,axis.ticks.x,axis.ticks.x.top,axis.ticks.x.bottom,axis.ticks.y,axis.ticks.y.left,axis.ticks.y.right,axis.ticks.theta,axis.ticks.r

tick marks along axes (element_line()). Specify all tick marks (axis.ticks), ticks by plane (using axis.ticks.x or axis.ticks.y), or individually for each axis (using axis.ticks.x.bottom, axis.ticks.x.top, axis.ticks.y.left, axis.ticks.y.right). ⁠axis.ticks.*.*⁠ inherits from ⁠axis.ticks.*⁠ which inherits from axis.ticks, which in turn inherits from line

axis.minor.ticks.x.top,axis.minor.ticks.x.bottom,axis.minor.ticks.y.left,axis.minor.ticks.y.right,axis.minor.ticks.theta,axis.minor.ticks.r

minor tick marks along axes (element_line()). ⁠axis.minor.ticks.*.*⁠ inherit from the corresponding major ticks ⁠axis.ticks.*.*⁠.

axis.ticks.length,axis.ticks.length.x,axis.ticks.length.x.top,axis.ticks.length.x.bottom,axis.ticks.length.y,axis.ticks.length.y.left,axis.ticks.length.y.right,axis.ticks.length.theta,axis.ticks.length.r

length of tick marks (unit). axis.ticks.length inherits from spacing.

axis.minor.ticks.length,axis.minor.ticks.length.x,axis.minor.ticks.length.x.top,axis.minor.ticks.length.x.bottom,axis.minor.ticks.length.y,axis.minor.ticks.length.y.left,axis.minor.ticks.length.y.right,axis.minor.ticks.length.theta,axis.minor.ticks.length.r

length of minor tick marks (unit), or relative to axis.ticks.length when provided with rel().

axis.line,axis.line.x,axis.line.x.top,axis.line.x.bottom,axis.line.y,axis.line.y.left,axis.line.y.right,axis.line.theta,axis.line.r

lines along axes (element_line()). Specify lines along all axes (axis.line), lines for each plane (using axis.line.x or axis.line.y), or individually for each axis (using axis.line.x.bottom, axis.line.x.top, axis.line.y.left, axis.line.y.right). ⁠axis.line.*.*⁠ inherits from ⁠axis.line.*⁠ which inherits from axis.line, which in turn inherits from line

legend.background

background of legend (element_rect(); inherits from rect)

legend.margin

the margin around each legend (margin()); inherits from margins.

legend.spacing,legend.spacing.x,legend.spacing.y

the spacing between legends (unit). legend.spacing.x & legend.spacing.y inherit from legend.spacing or can be specified separately. legend.spacing inherits from spacing.

legend.key

background underneath legend keys (element_rect(); inherits from rect)

legend.key.size,legend.key.height,legend.key.width

size of legend keys (unit); key background height & width inherit from legend.key.size or can be specified separately. In turn legend.key.size inherits from spacing.

legend.key.spacing,legend.key.spacing.x,legend.key.spacing.y

spacing between legend keys given as a unit. Spacing in the horizontal (x) and vertical (y) direction inherit from legend.key.spacing or can be specified separately. legend.key.spacing inherits from spacing.

legend.key.justification

Justification for positioning legend keys when more space is available than needed for display. The default, NULL, stretches keys into the available space. Can be a location like "center" or "top", or a two-element numeric vector.

legend.frame

frame drawn around the bar (element_rect()).

legend.ticks

tick marks shown along bars or axes (element_line())

legend.ticks.length

length of tick marks in legend (unit()); inherits from legend.key.size.

legend.axis.line

lines along axes in legends (element_line())

legend.text

legend item labels (element_text(); inherits from text)

legend.text.position

placement of legend text relative to legend keys or bars ("top", "right", "bottom" or "left"). The legend text placement might be incompatible with the legend's direction for some guides.

legend.title

title of legend (element_text(); inherits from title)

legend.title.position

placement of legend title relative to the main legend ("top", "right", "bottom" or "left").

legend.position

the default position of legends ("none", "left", "right", "bottom", "top", "inside")

legend.position.inside

A numeric vector of length two setting the placement of legends that have the "inside" position.

legend.direction

layout of items in legends ("horizontal" or "vertical")

legend.byrow

whether the legend-matrix is filled by columns (FALSE, the default) or by rows (TRUE).

legend.justification

anchor point for positioning legend inside plot ("center" or two-element numeric vector) or the justification according to the plot area when positioned outside the plot

legend.justification.top,legend.justification.bottom,legend.justification.left,legend.justification.right,legend.justification.inside

Same as legend.justification but specified per legend.position option.

legend.location

Relative placement of legends outside the plot as a string. Can be "panel" (default) to align legends to the panels or "plot" to align legends to the plot as a whole.

legend.box

arrangement of multiple legends ("horizontal" or "vertical")

legend.box.just

justification of each legend within the overall bounding box, when there are multiple legends ("top", "bottom", "left", "right", "center" or "centre")

legend.box.margin

margins around the full legend area, as specified using margin(); inherits from margins.

legend.box.background

background of legend area (element_rect(); inherits from rect)

legend.box.spacing

The spacing between the plotting area and the legend box (unit); inherits from spacing.

panel.background

background of plotting area, drawn underneath plot (element_rect(); inherits from rect)

panel.border

border around plotting area, drawn on top of plot so that it covers tick marks and grid lines. This should be used with fill = NA (element_rect(); inherits from rect)

panel.spacing,panel.spacing.x,panel.spacing.y

spacing between facet panels (unit). panel.spacing.x & panel.spacing.y inherit from panel.spacing or can be specified separately. panel.spacing inherits from spacing.

panel.grid,panel.grid.major,panel.grid.minor,panel.grid.major.x,panel.grid.major.y,panel.grid.minor.x,panel.grid.minor.y

grid lines (element_line()). Specify major grid lines, or minor grid lines separately (using panel.grid.major or panel.grid.minor) or individually for each axis (using panel.grid.major.x, panel.grid.minor.x, panel.grid.major.y, panel.grid.minor.y). Y axis grid lines are horizontal and x axis grid lines are vertical. ⁠panel.grid.*.*⁠ inherits from ⁠panel.grid.*⁠ which inherits from panel.grid, which in turn inherits from line

panel.ontop

option to place the panel (background, gridlines) over the data layers (logical). Usually used with a transparent or blank panel.background.

panel.widths,panel.heights

Sizes for panels (units). Can be a single unit to set the total size for the panel area, or a unit vector to set the size of individual panels. Using this setting overrides the aspect ratio set by the theme, coord or facets. An exception is made when the plot has a single panel and exactly one of the width or height is set, in which case an attempt is made to preserve the aspect ratio.

plot.background

background of the entire plot (element_rect(); inherits from rect)

plot.title

plot title (text appearance) (element_text(); inherits from title) left-aligned by default

plot.title.position,plot.caption.position

Alignment of the plot title/subtitle and caption. The setting for plot.title.position applies to both the title and the subtitle. A value of "panel" (the default) means that titles and/or caption are aligned to the plot panels. A value of "plot" means that titles and/or caption are aligned to the entire plot (minus any space for margins and plot tag).

plot.subtitle

plot subtitle (text appearance) (element_text(); inherits from title) left-aligned by default

plot.caption

caption below the plot (text appearance) (element_text(); inherits from title) right-aligned by default

plot.tag

upper-left label to identify a plot (text appearance) (element_text(); inherits from title) left-aligned by default

plot.tag.position

The position of the tag as a string ("topleft", "top", "topright", "left", "right", "bottomleft", "bottom", "bottomright") or a coordinate. If a coordinate, can be a numeric vector of length 2 to set the x,y-coordinate relative to the whole plot. The coordinate option is unavailable for plot.tag.location = "margin".

plot.tag.location

The placement of the tag as a string, one of "panel", "plot" or "margin". Respectively, these will place the tag inside the panel space, anywhere in the plot as a whole, or in the margin around the panel space.

plot.margin

margin around entire plot (unit with the sizes of the top, right, bottom, and left margins); inherits from margin.

strip.background,strip.background.x,strip.background.y

background of facet labels (element_rect(); inherits from rect). Horizontal facet background (strip.background.x) & vertical facet background (strip.background.y) inherit from strip.background or can be specified separately

strip.clip

should strip background edges and strip labels be clipped to the extend of the strip background? Options are "on" to clip, "off" to disable clipping or "inherit" (default) to take the clipping setting from the parent viewport.

strip.placement

placement of strip with respect to axes, either "inside" or "outside". Only important when axes and strips are on the same side of the plot.

strip.text,strip.text.x,strip.text.y,strip.text.x.top,strip.text.x.bottom,strip.text.y.left,strip.text.y.right

facet labels (element_text(); inherits from text). Horizontal facet labels (strip.text.x) & vertical facet labels (strip.text.y) inherit from strip.text or can be specified separately. Facet strips have dedicated position-dependent theme elements (strip.text.x.top, strip.text.x.bottom, strip.text.y.left, strip.text.y.right) that inherit from strip.text.x and strip.text.y, respectively. As a consequence, some theme stylings need to be applied to the position-dependent elements rather than to the parent elements

strip.switch.pad.grid,strip.switch.pad.wrap

space between strips and axes when strips are switched (unit); inherits from spacing.

complete

set this to TRUE if this is a complete theme, such as the one returned by theme_grey(). Complete themes behave differently when added to a ggplot object. Also, when setting complete = TRUE all elements will be set to inherit from blank elements.

validate

TRUE to run check_element(), FALSE to bypass checks.