ggpackets: Package Plot Layers for Easier Portability and Modularization

Description

Create groups of ggplot layers that can be easily migrated from one plot to another, reducing redundant code and improving the ability to format many plots that draw from the same source ggpacket layers.

Author(s)

Maintainer: Doug Kelkhoff doug.kelkhoff@gmail.com

See Also

Useful links:

• https://github.com/dgkf/ggpackets

• https://dgkf.github.io/ggpackets/

• Report bugs at https://github.com/dgkf/ggpackets/issues

Examples

library(ggplot2)

# Prep a tidy data.frame to plot with
airquality_long <- rbind(
  data.frame(
    airquality[,c("Month", "Day")],
    Variable = "Temp",
    Measurement = airquality$Temp),
  data.frame(
    airquality[,c("Month", "Day")],
    Variable = "Ozone",
    Measurement = airquality$Ozone))

# Build our new composite ggplot geom
geom_error_line <- ggpacket() %+%
  geom_ribbon(
    .id = "box",
    mapping = aes(fill = ..color..),
    stat = 'summary',
    fun = mean,
    fun.min = ~mean(.) - sd(.),
    fun.max = ~mean(.) + sd(.),
    alpha = 0.15,
    color = NA) %+%
  geom_line(
    .id = "line",
    stat = 'summary',
    fun = mean,
    alpha = 0.8)

# Try it out!
ggplot(airquality_long) +
  aes(x = round((Month * 30 + Day) / 4), y = Measurement, color = Variable) +
  geom_error_line(na.rm = TRUE, line.size = 1.5) +
  scale_y_log10() +
  labs(x = "Week")

# for further examples, check out the vignettes
vignette(package = "ggpackets")

Lazy handler for ggplot addition

Description

Lazy handler for ggplot addition

Usage

e1 %+% e2

Arguments

Value

A new ggpacket object with e2 appended as an additional layer or layers.

Extracted .all_aesthetics from internal ggplot2 with hardcoded fallback

Description

Extracted .all_aesthetics from internal ggplot2 with hardcoded fallback

Usage

.all_aesthetics()

Index into a ggpacket object

Description

Index into a ggpacket object

Usage

## S4 method for signature 'ggpacket'
x[i, j, ..., drop = TRUE]

Arguments

Subset a ggpacket for a selection of ggcalls

Description

Subset a ggpacket for a selection of ggcalls

Usage

## S3 method for class 'ggpacket'
x[i, ...]

Arguments

Index into a ggpacket object

Description

Index into a ggpacket object

Usage

## S4 method for signature 'ggpacket'
x[[i, j, ...]]

Arguments

Subset a ggpacket for a selection of ggcalls

Description

Subset a ggpacket for a selection of ggcalls

Usage

## S3 method for class 'ggpacket'
x[[i, ...]]

Arguments

Convert a ggpacket to a list of ggcalls

Description

Convert a ggpacket to a list of ggcalls

Usage

## S4 method for signature 'ggpacket'
as.list(x, ...)

Arguments

Convert an expression into a call as a list of quosure components

Description

Convert an expression into a call as a list of quosure components

Usage

as_gg_call(x, which = 3L)

Arguments

Collapse data arguments

Description

Reduce data arguments using update_data

Usage

collapse_data(args)

Arguments

Collapse aesthetic mappings arguments

Description

Reduce aesthetic mapping arguments using update_mapping

Usage

collapse_mappings(args)

Arguments

Remove arguments with duplciated names

Description

Remove arguments with duplciated names

Usage

deduplicate_params(args)

Arguments

Expand dot arguments into named arguments

Description

Expand dot arguments into named arguments

Usage

expand_dots(expr, envir = parent.frame(2L))

Arguments

Filter a named list by ids

Description

Filter a named list (often an aesthetic mapping or argument list) for only unprefixed elements, elements which don't match any of all_ids and those which match one of call_ids. For those that match, remove the id prefix.

Usage

filter_by_ggcall_ids(x, call_ids, all_ids)

Arguments

Add a gg object to a ggpacket object

Description

Add a gg object to a ggpacket object

Usage

gg_plus_ggpacket(e1, e2)

Arguments

A container for lazy ggplot layers

Description

ggpackets present a mechanism for easily collecting loose ggplot layers into objects that can be reused across multiple plots, as well as handling of hierarchical argument propegation, as well as data and aesthetic scoping.

Usage

ggpacket(...)

Arguments

Details

The ggpacket object behaves like a function, returning an updated ggpacket. As well, it contains a few slots which can be used for programmatically accessing the lazy ggplot calls.

Within ggpacket and subsequent ggplot layer calls, aesthetic mappings can contain references to previously mapped aesthetics using the double-dot keywords (e.g. ..x..). In addition, the keyword ..reset.. can be used to revert aesthetics within the ggpacket or layer to an un-specified state.

Because ggpackets will tolerate a more flexible syntax for layer specifications, it's preferrable to use the ggplot composition operator %+% (instead of +). This allows for duplicate argument names and non-standard aesthetics to be passed, which are both handled internally within the ggpacket call, but will trigger warnings when using a bare +.

Value

A new ggpacket object

Slots

data

A lazy reference to the data parameter of the ggpacket, allowing for scoping the data used by a block of ggplot layers.

mapping

A lazy reference to the mapping parameter of the ggpacket, allowing for scoping of aesthetic mappings over a block of ggplot layers.

dots

Quosures representing arguments to be passed to all of the ggpacket's ggplot layers.

ggcalls

A list containing the layers stored within the ggpacket

Examples

library(ggplot2)

# create a ggpacket directly, setting some fixed argument settings
ggpk_simple <- ggpacket() %+% geom_line(color = "red") %+% geom_point()
ggplot(mtcars, aes(x = wt, y = mpg)) + ggpk_simple()

# any non-fixed arguments can be modified in the ggpacket call
ggplot(mtcars, aes(x = wt, y = mpg)) + ggpk_simple(color = "green")

# arguments can be specified for only specific layers by prefixing them
ggplot(mtcars, aes(x = wt, y = mpg)) + ggpk_simple(point.size = 5)

# allow masking of preset arguments by wrapping the ggpacket in a function
ggpk_func <- function(...) {
  ggpacket() %+%
    geom_line(...) %+%
    geom_point(color = "red", ...)
}

ggplot(mtcars, aes(x = wt, y = mpg)) +
  ggpk_func(color = "purple", line.linewidth = 2, point.size = 4)

A ggpacket object

Description

A ggpacket object

Add a ggpacket object to another, arbitrary object

Display contents of a ggpacket

Usage

## S4 method for signature 'ggpacket,ANY'
e1 + e2

## S4 method for signature 'ggpacket'
show(object)

Arguments

Slots

data

A dataset or waiver to use within the ggpacket ggcalls.

mapping

A ggplot aesthetic mapping to use within the ggpacket ggcalls.

dots

Arguments which should be passed before prespecified arguments to each ggcall.

ggcalls

A list of lazily evaluated ggplot layer construction expressions.

The function used when a ggpacket is called as a function

Description

The function used when a ggpacket is called as a function

Usage

ggpacket_call(mapping = NULL, data = NULL, ..., .id = character(0L))

Arguments

Value

A new ggpacket object with the new defaults applied

Swallow calls when a ggpacket is added to any expression

Description

Swallow calls when a ggpacket is added to any expression

Usage

ggpacket_plus_ANY(e1, e2)

Arguments

Specific handling of ..reset.. aesthetic

Description

Specific handling of ..reset.. aesthetic

Usage

handle_reset_mapping(mapping)

Arguments

Convert ggplot geom layers to friendly names

Description

Convert ggplot geom layers to friendly names

Usage

infer_ggcall_id(x)

Arguments

Label ggcall with function name if it can be deduced

Description

Label ggcall with function name if it can be deduced

Usage

infer_ggcall_name(expr)

Arguments

Get the number of ggcalls within a ggpacket

Description

Get the number of ggcalls within a ggpacket

Usage

## S4 method for signature 'ggpacket'
length(x)

Arguments

Match unnamed arguments

Description

Similar to match.call, but without evaluating arguments, avoiding possible syntactic errors that would arise due to ggpackets-specific syntax.

Usage

match_unnamed_args(f, args, envir = parent.frame())

Arguments

Fetch the ids associated with each ggcall

Description

Fetch the ids associated with each ggcall

Usage

## S4 method for signature 'ggpacket'
names(x)

Arguments

Filter for only arguments that can be accepted by a given function

Description

Filter for only arguments that can be accepted by a given function

Usage

only_formals_and_dots(f, args)

Arguments

Check a ggpacket object for required aesthetic arguments

Description

Check a ggpacket object for required aesthetic arguments

Usage

required_aesthetics(x)

Arguments

Returning the calling object from within a function

Description

Used for retrieving an S4 object being called as though it is a function

Usage

self(which = -1L)

Arguments

Mimic ggplot2 behavior of intelligently interpretting first layer argument

Description

Like ggplot, if the first argument doesn't appear to be an aesthetic mapping, despite mappings being appropriately passed in the first argument, swap the first two arguments.

Usage

smart_swap_mapping_data(args)

Arguments

Substitute a ggcall's dot aesthetics with their redirected values

Description

Substitute a ggcall's dot aesthetics with their redirected values

Usage

substitute_ggcall_dot_aes(mapping, ggcall, envir = parent.frame())

Arguments

Substitute a quoted expression in a given environmment

Description

Substitute a quoted expression in a given environmment

Usage

substitute_quote(q, env = parent.frame())

Arguments

Reduce data parameters, iteratively applying functions or masking

Description

Reduce data parameters, iteratively applying functions or masking

Usage

update_data(d1, d2, ...)

Arguments

Reduce a list of mappings, iteratively routing aesthetics

Description

Reduce a list of mappings, iteratively routing aesthetics

Usage

update_mapping(...)

Arguments

Evaluate an expression, ignoring warnings about unknown parameters

Description

Evaluate an expression, ignoring warnings about unknown parameters

Usage

with_ignore_unknown_params(expr, envir = parent.frame())

Arguments

Evaluate a call, ignore base R errors for unused arguments

Description

In actuality, the expression is repeatedly called while catching errors and removing error-causing arguments.

Usage

with_ignore_unused_argument(call, envir = parent.frame())

Arguments