ggghost: Capture the spirit of your ggplot calls

Description

Creates a reproducible container for ggplot, storing the data and calls required to produce a plot.

Details

ggplot2 stores the information needed to build the graph as a grob, but that's what the computer needs to know about in order to build the graph. As humans, we're more interested in what commands were issued in order to build the graph. For good reproducibility, the calls need to be applied to the relevant data. While this is somewhat available by deconstructing the grob, it's not the simplest approach.

Here is one option that solves that problem.

ggghost stores the data used in a ggplot() call, and collects ggplot commands (usually separated by +) as they are applied, in effect lazily collecting the calls. Once the object is requested, the print method combines the individual calls back into the total plotting command and executes it. This is where the call would usually be discarded. Instead, a "ghost" of the commands lingers in the object for further investigation, subsetting, adding to, or subtracting from.

Author(s)

Maintainer: Jonathan Carroll rpkg@jcarroll.com.au

See Also

Useful links:

• https://github.com/jonocarroll/ggghost

• Report bugs at https://github.com/jonocarroll/ggghost/issues

Begin constructing a ggghost cache

Description

The data and initial ggpot() call are stored as a list (call) with attribute (data).

Usage

lhs %g<% rhs

Arguments

Details

The data must be passed into the ggplot call directly. Passing this in via a magrittr pipe remains as a future improvement. The newly created ggghost object is a list of length 1 containing the ggplot call, with attribute data; another list, containing the data_name and data itself.

Value

Assigns the ggghost structure to the lhs symbol.

Examples

## create a ggghost object
tmpdata <- data.frame(x = 1:100, y = rnorm(100))

z %g<% ggplot(tmpdata, aes(x,y))

Add a New ggplot Component to a ggghost Object

Description

This operator allows you to add objects to a ggghost object in the style of @hrbrmstr.

Usage

## S3 method for class 'gg'
e1 + e2

Arguments

Value

Appends the e2 call to the ggghost structure

Examples

#' ## create a ggghost object
tmpdata <- data.frame(x = 1:100, y = rnorm(100))

z %g<% ggplot(tmpdata, aes(x,y))
z <- z + geom_point(col = "steelblue")
z <- z + theme_bw()
z <- z + labs(title = "My cool ggplot")
z <- z + labs(x = "x axis", y = "y axis")
z <- z + geom_smooth()

Remove a call from a ggghost object

Description

Calls can be removed from the ggghost object via regex matching of the function name. All matching calls will be removed based on the match to the string up to the first bracket, so any arguments are irrelevant.

Usage

## S3 method for class 'gg'
e1 - e2

Arguments

Details

For example, subtracting geom_line() will remove all calls matching geom_line regardless of their arguments.

labs() has been identified as a special case, as it requires an argument in order to be recognised as a valid function. Thus, trying to remove it with an empty argument will fail. That said, the argument doesn't need to match, so it can be populated with a dummy string or anything that evaluates in scope. See examples.

Value

A ggghost structure with calls (text) matching e2 removed, otherwise the same as e1

Examples

## create a ggghost object
tmpdata <- data.frame(x = 1:100, y = rnorm(100))

z %g<% ggplot(tmpdata, aes(x,y))
z <- z + geom_point(col = "steelblue")
z <- z + theme_bw()
z <- z + labs(title = "My cool ggplot")
z <- z + labs(x = "x axis", y = "y axis")
z <- z + geom_smooth()

z - "labs"        # removes all labs
z - "title"       # removes just the title
z - "axis"        # removes the axis labels
z - geom_point()  # removes points
z - theme_bw()    # removes theme_bw()

Identify the data passed to ggplot

Description

Duplicate arguments to ggplot2::ggplot with the intent that the data argument can be captured and identified.

Usage

identify_data(
  data,
  mapping = ggplot2::aes(),
  ...,
  environment = parent.frame()
)

Arguments

Value

Name of the data.frame passed to ggplot

Reports whether x is a ggghost object

Description

Reports whether x is a ggghost object

Usage

is.ggghost(x)

Arguments

Value

logical; TRUE if x inherits class ggghost

Collect ggghost calls and produce the ggplot output

Description

Collect ggghost calls and produce the ggplot output

Usage

## S3 method for class 'ggghost'
print(x, ...)

Arguments

Value

The ggplot plot data (invisibly). Used for the side-effect of producing a ggplot plot.

Bring a ggplot to life (re-animate)

Description

Creates an animation showing the stepwise process of building up a ggplot. Successively adds calls from a ggghost object and then combines these into an animated GIF.

Usage

reanimate(
  object,
  gifname = "ggghost.gif",
  interval = 1,
  ani.width = 600,
  ani.height = 600
)

lazarus(
  object,
  gifname = "ggghost.gif",
  interval = 1,
  ani.width = 600,
  ani.height = 600
)

Arguments

Value

TRUE if it gets that far

Examples

## Not run: 
## create an animation showing the process of building up a plot
reanimate(z, "mycoolplot.gif")

## End(Not run)

Recover data Stored in a ggghost object

Description

The data used to generate a plot is an essential requirement for a reproducible graphic. This is somewhat available from a ggplot grob (in raw form) but it it not easily accessible, and isn't named the same way as the original call.

Usage

recover_data(x, supp = TRUE)

Arguments

Details

This function retrieves the data from the ggghost object as it was when it was originally called.

If supplementary data has also been attached using supp_data then this will also be recovered (if requested).

When used interactively, a warning will be produced if the data to be extracted exists in the workspace but not identical to the captured version.

Value

A data.frame of the original data, named as it was when used in ggplot(data)

Extract a subset of a ggghost object

Description

Alternative to subtracting calls using -.gg, this method allows one to select the desired components of the available calls and have those evaluated.

Usage

## S3 method for class 'ggghost'
subset(x, ...)

Arguments

Value

Another ggghost object containing only the calls selected.

Examples

## create a ggghost object
tmpdata <- data.frame(x = 1:100, y = rnorm(100))

z %g<% ggplot(tmpdata, aes(x,y))
z <- z + geom_point(col = "steelblue")
z <- z + theme_bw()
z <- z + labs(title = "My cool ggplot")
z <- z + labs(x = "x axis", y = "y axis")
z <- z + geom_smooth()

## remove the labels and theme
subset(z, c(1,2,6))
## or
subset(z, c(TRUE,TRUE,FALSE,FALSE,FALSE,TRUE))

List the calls contained in a ggghost object

Description

Summarises a ggghost object by presenting the contained calls in the order they were added. Optionally concatenates these into a single ggplot call.

Usage

## S3 method for class 'ggghost'
summary(object, ...)

Arguments

Details

The data is also included in ggghost objects. If this is also desired in the output, use str. See example.

Value

Either a list of ggplot calls or a string of such concatenated with " + "

Examples

## present the ggghost object as a list
tmpdata <- data.frame(x = 1:100, y = rnorm(100))

z %g<% ggplot(tmpdata, aes(x,y))
z <- z + geom_point(col = "steelblue")
summary(z)

## present the ggghost object as a string
summary(z, combine = TRUE) # Note, value of 'combine' is arbitrary

## to inspect the data structure also captured, use str()
str(z)

Inspect the supplementary data attached to a ggghost object

Description

Inspect the supplementary data attached to a ggghost object

Usage

supp_data(x)

Arguments

Value

A list with two elements: the name of the supplementary data, and the supplementary data itself

Attach supplementary data to a ggghost object

Description

Attach supplementary data to a ggghost object

Usage

supp_data(x) <- value

Arguments

Value

The original object with suppdata attribute