geom_debug_panel: Geoms that print input data to console.

Description

The debug geoms are used to print to the console a summary of the object being received by geoms' draw functions as input data and parameters objects.

Usage

geom_debug_panel(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  dbgfun.data = "head",
  dbgfun.data.args = list(),
  dbgfun.params = "summary",
  dbgfun.params.args = list(),
  dbgfun.print = "print",
  dbgfun.print.args = list(),
  parse = NULL,
  orientation = NULL,
  nudge_x = 0,
  nudge_y = 0,
  position = "identity",
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE,
  ...
)
geom_debug(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  summary.fun = "head",
  summary.fun.args = list(),
  parse = NULL,
  orientation = NULL,
  nudge_x = 0,
  nudge_y = 0,
  position = "identity",
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE,
  ...
)
geom_debug_group(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  dbgfun.data = "head",
  dbgfun.data.args = list(),
  dbgfun.params = "summary",
  dbgfun.params.args = list(),
  dbgfun.print = "print",
  dbgfun.print.args = list(),
  parse = NULL,
  orientation = NULL,
  nudge_x = 0,
  nudge_y = 0,
  position = "identity",
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE,
  ...
)

Value

The panel function of this geometry always returns a

nullGrob, the legend is is also set to

nullGrob. This geometry used for its text printing side effect.

Arguments

mapping

Set of aesthetic mappings created by aes or aes_. If specified and inherit.aes = TRUE (the default), is combined with the default mapping at the top level of the plot. You only need to supply mapping if there isn't a mapping defined for the plot.

data

A data frame. If specified, overrides the default data frame defined at the top level of the plot.

stat

The statistical transformation to use on the data for this layer, as a string.

dbgfun.data, dbgfun.params, summary.fun

The functions as character strings giving their names or as named or anonymous function objects, to be used to summarize the data and the params objects received as input by the geometry.

dbgfun.data.args, dbgfun.params.args, summary.fun.args

A named list of additional arguments to be passed to dbgfun.data and dbgfun.params.

dbgfun.print

A function used to print the data object received as input.

dbgfun.print.args

A named list. Currently ignored!

parse, orientation

Ignored. Helps avoid warnings.

nudge_x, nudge_y

Horizontal and vertical adjustments to nudge the starting position. The units for nudge_x and nudge_y are the same as for the data units on the x-axis and y-axis.

position

Position adjustment, either as a string, or the result of a call to a position adjustment function.

na.rm

If FALSE (the default), removes missing values with a warning. If TRUE silently removes missing values.

show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes.

inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders.

...

other arguments passed on to layer. There are three types of arguments you can use here:

Aesthetics: to set an aesthetic to a fixed value, like color = "red" or size = 3.
Other arguments to the layer, for example you override the default stat associated with the layer.
Other arguments passed on to the stat.

Details

It can be useful when debugging the code of statistics or to learn how the stats and geoms work in 'ggplot2' (>= 3.0.0).

The intended use of geom_debug_panel() and geom_debug_group() is to explore the data as they are used in a plot layer to produce graphical output. Geometries can be defined using draw functions that receive as input data corresponding to a single group at a time, or draw functions that receive as input all data to be drawn in a panel at a time, possibly including multiple groups. Function geom_debug() is identical to geom_debug_panel(), and included for backwards compatibility.

These debug geoms are very unusual in that they do not produce visible graphic output. They "draw" a grid.null() grob (graphical object) when the plot is rendered. Also, differently to normal geometries, they print the data and params objects or a summary of them to the R console. The summary is obtained using the functions passed as arguments to their formal parameter dbgfun.data and dbgfun.params. The data and params objects are passed as the first positional argument to these functions and the values they return are printed.

If dbgfun.data = "I" is passed, the data object is printed as is. In contrast, if dbgfun.data = NULL is passed, the data object summary and its printing are not skipped. The mechanism is identical for dbgfun.params and params.

Nudging with nudge_x and nudge_y behave as in geom_text. Arguments passed to position are obeyed. So the effects of positions are reflected in the data object printed or summarized to the R console. The arguments passed to parse and orientation are currently ignored.

Many aesthetics are defined as optional so that they are accepted silently by geom_debug() and handled by 'ggplot2' as usual. Given the number available extensions to 'ggplot2', it is likely that some are missing.

The names of dbgfun.data() and dbgfun.params() are included in the section headers of the printout, together with panels and groups.

In most cases, the definitions of the debug and print functions must be available when the "gg" object is printed and the plot rendered.

Examples

Run this code

# echo to the R console \code{data} as received by geoms
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug_panel()

ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug_group()

ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug_panel(dbgfun.params = NULL)

ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug_panel(dbgfun.data = NULL)

ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug_panel(dbgfun.data = "head", dbgfun.data.args = list(n = 3))

ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug_panel(dbgfun.data = "nrow", dbgfun.params = "length")

ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug_panel(dbgfun.data = "attributes", dbgfun.params = "attributes")

ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug_panel(dbgfun.data = "I", dbgfun.params = NULL)

# echo to the R console \code{data} as received by geoms
ggplot(mtcars, aes(cyl, mpg, colour = factor(cyl))) +
  stat_summary(fun.data = "mean_se") +
  stat_summary(geom = "debug_panel", fun.data = "mean_se")

ggplot(mtcars, aes(cyl, mpg, colour = factor(cyl))) +
  stat_summary(fun.data = "mean_se") +
  stat_summary(geom = "debug_panel", fun.data = "mean_se", dbgfun.params = NULL)

# shape data is not passed to geometries or statistics
if (requireNamespace("sf", quietly = TRUE)) {
  nc <-
    sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)

  ggplot(data = nc) +
    geom_sf(color = "darkblue", fill = "white") +
    geom_debug_panel()
}

# backwards compatibility
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
  geom_point() +
  geom_debug()

ggplot(mtcars, aes(cyl, mpg, colour = factor(cyl))) +
  stat_summary(fun.data = "mean_se") +
  stat_summary(geom = "debug", fun.data = "mean_se")