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,
...
)Arguments
- mapping
Set of aesthetic mappings created by
aesoraes_. If specified andinherit.aes = TRUE(the default), is combined with the default mapping at the top level of the plot. You only need to supplymappingif 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
dataand theparamsobjects 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.dataanddbgfun.params.- dbgfun.print
A function used to print the
dataobject 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_xandnudge_yare 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. IfTRUEsilently removes missing values.- show.legend
logical. Should this layer be included in the legends?
NA, the default, includes if any aesthetics are mapped.FALSEnever includes, andTRUEalways 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"orsize = 3.Other arguments to the layer, for example you override the default
statassociated with the layer.Other arguments passed on to the stat.
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.
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.
Note
geom_debug() is a synonym of geom_debug_panel(), for
backwards compatibility. Not to be used in new code.
See also
To access data, scales and grobs in a built ggplot, see
ggplot_build.
Examples
# echo to the R console \code{data} as received by geoms
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug_panel()
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'data' (head):"
#> colour x y PANEL group
#> 1 #00BA38 6 21.0 1 2
#> 2 #00BA38 6 21.0 1 2
#> 3 #F8766D 4 22.8 1 1
#> 4 #00BA38 6 21.4 1 2
#> 5 #619CFF 8 18.7 1 3
#> 6 #00BA38 6 18.1 1 2
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'params' (summary):"
#> Length Class Mode
#> x 11 ViewScale environment
#> x.sec 11 ViewScale environment
#> x.range 2 -none- numeric
#> y 11 ViewScale environment
#> y.sec 11 ViewScale environment
#> y.range 2 -none- numeric
#> guides 4 Guides environment
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug_group()
#> [1] "PANEL 1; group(s) 1; 'draw_group()' input 'data' (head):"
#> colour x y PANEL group
#> 3 #F8766D 4 22.8 1 1
#> 8 #F8766D 4 24.4 1 1
#> 9 #F8766D 4 22.8 1 1
#> 18 #F8766D 4 32.4 1 1
#> 19 #F8766D 4 30.4 1 1
#> 20 #F8766D 4 33.9 1 1
#> [1] "PANEL 1; group(s) 1; 'draw_group()' input 'params' (summary):"
#> Length Class Mode
#> x 11 ViewScale environment
#> x.sec 11 ViewScale environment
#> x.range 2 -none- numeric
#> y 11 ViewScale environment
#> y.sec 11 ViewScale environment
#> y.range 2 -none- numeric
#> guides 4 Guides environment
#> [1] "PANEL 1; group(s) 2; 'draw_group()' input 'data' (head):"
#> colour x y PANEL group
#> 1 #00BA38 6 21.0 1 2
#> 2 #00BA38 6 21.0 1 2
#> 4 #00BA38 6 21.4 1 2
#> 6 #00BA38 6 18.1 1 2
#> 10 #00BA38 6 19.2 1 2
#> 11 #00BA38 6 17.8 1 2
#> [1] "PANEL 1; group(s) 2; 'draw_group()' input 'params' (summary):"
#> Length Class Mode
#> x 11 ViewScale environment
#> x.sec 11 ViewScale environment
#> x.range 2 -none- numeric
#> y 11 ViewScale environment
#> y.sec 11 ViewScale environment
#> y.range 2 -none- numeric
#> guides 4 Guides environment
#> [1] "PANEL 1; group(s) 3; 'draw_group()' input 'data' (head):"
#> colour x y PANEL group
#> 5 #619CFF 8 18.7 1 3
#> 7 #619CFF 8 14.3 1 3
#> 12 #619CFF 8 16.4 1 3
#> 13 #619CFF 8 17.3 1 3
#> 14 #619CFF 8 15.2 1 3
#> 15 #619CFF 8 10.4 1 3
#> [1] "PANEL 1; group(s) 3; 'draw_group()' input 'params' (summary):"
#> Length Class Mode
#> x 11 ViewScale environment
#> x.sec 11 ViewScale environment
#> x.range 2 -none- numeric
#> y 11 ViewScale environment
#> y.sec 11 ViewScale environment
#> y.range 2 -none- numeric
#> guides 4 Guides environment
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug_panel(dbgfun.params = NULL)
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'data' (head):"
#> colour x y PANEL group
#> 1 #00BA38 6 21.0 1 2
#> 2 #00BA38 6 21.0 1 2
#> 3 #F8766D 4 22.8 1 1
#> 4 #00BA38 6 21.4 1 2
#> 5 #619CFF 8 18.7 1 3
#> 6 #00BA38 6 18.1 1 2
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug_panel(dbgfun.data = NULL)
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'params' (summary):"
#> Length Class Mode
#> x 11 ViewScale environment
#> x.sec 11 ViewScale environment
#> x.range 2 -none- numeric
#> y 11 ViewScale environment
#> y.sec 11 ViewScale environment
#> y.range 2 -none- numeric
#> guides 4 Guides environment
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug_panel(dbgfun.data = "head", dbgfun.data.args = list(n = 3))
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'data' (head):"
#> colour x y PANEL group
#> 1 #00BA38 6 21.0 1 2
#> 2 #00BA38 6 21.0 1 2
#> 3 #F8766D 4 22.8 1 1
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'params' (summary):"
#> Length Class Mode
#> x 11 ViewScale environment
#> x.sec 11 ViewScale environment
#> x.range 2 -none- numeric
#> y 11 ViewScale environment
#> y.sec 11 ViewScale environment
#> y.range 2 -none- numeric
#> guides 4 Guides environment
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug_panel(dbgfun.data = "nrow", dbgfun.params = "length")
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'data' (nrow):"
#> [1] 32
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'params' (length):"
#> [1] 7
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug_panel(dbgfun.data = "attributes", dbgfun.params = "attributes")
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'data' (attributes):"
#> $names
#> [1] "colour" "x" "y" "PANEL" "group"
#>
#> $class
#> [1] "data.frame"
#>
#> $row.names
#> [1] 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
#> [26] 26 27 28 29 30 31 32
#>
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'params' (attributes):"
#> $names
#> [1] "x" "x.sec" "x.range" "y" "y.sec" "y.range" "guides"
#>
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug_panel(dbgfun.data = "I", dbgfun.params = NULL)
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'data' (I):"
#> colour x y PANEL group
#> 1 #00BA38 6 21.0 1 2
#> 2 #00BA38 6 21.0 1 2
#> 3 #F8766D 4 22.8 1 1
#> 4 #00BA38 6 21.4 1 2
#> 5 #619CFF 8 18.7 1 3
#> 6 #00BA38 6 18.1 1 2
#> 7 #619CFF 8 14.3 1 3
#> 8 #F8766D 4 24.4 1 1
#> 9 #F8766D 4 22.8 1 1
#> 10 #00BA38 6 19.2 1 2
#> 11 #00BA38 6 17.8 1 2
#> 12 #619CFF 8 16.4 1 3
#> 13 #619CFF 8 17.3 1 3
#> 14 #619CFF 8 15.2 1 3
#> 15 #619CFF 8 10.4 1 3
#> 16 #619CFF 8 10.4 1 3
#> 17 #619CFF 8 14.7 1 3
#> 18 #F8766D 4 32.4 1 1
#> 19 #F8766D 4 30.4 1 1
#> 20 #F8766D 4 33.9 1 1
#> 21 #F8766D 4 21.5 1 1
#> 22 #619CFF 8 15.5 1 3
#> 23 #619CFF 8 15.2 1 3
#> 24 #619CFF 8 13.3 1 3
#> 25 #619CFF 8 19.2 1 3
#> 26 #F8766D 4 27.3 1 1
#> 27 #F8766D 4 26.0 1 1
#> 28 #F8766D 4 30.4 1 1
#> 29 #619CFF 8 15.8 1 3
#> 30 #00BA38 6 19.7 1 2
#> 31 #619CFF 8 15.0 1 3
#> 32 #F8766D 4 21.4 1 1
# 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")
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_function()' input 'data' (head):"
#> colour x group y ymin ymax PANEL flipped_aes orientation
#> 1 #F8766D 4 1 26.66364 25.30387 28.02340 1 FALSE NA
#> 2 #00BA38 6 2 19.74286 19.19346 20.29225 1 FALSE NA
#> 3 #619CFF 8 3 15.10000 14.41580 15.78420 1 FALSE NA
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)
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_function()' input 'data' (head):"
#> colour x group y ymin ymax PANEL flipped_aes orientation
#> 1 #F8766D 4 1 26.66364 25.30387 28.02340 1 FALSE NA
#> 2 #00BA38 6 2 19.74286 19.19346 20.29225 1 FALSE NA
#> 3 #619CFF 8 3 15.10000 14.41580 15.78420 1 FALSE NA
# 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()
}
#> [1] "PANEL 1; group(s) -1; 'draw_panel()' input 'data' (head):"
#> PANEL group
#> 1 1 -1
#> 2 1 -1
#> 3 1 -1
#> 4 1 -1
#> 5 1 -1
#> 6 1 -1
#> [1] "PANEL 1; group(s) -1; 'draw_panel()' input 'params' (summary):"
#> Length Class Mode
#> x_range 2 -none- numeric
#> y_range 2 -none- numeric
#> graticule 11 sf list
#> crs 2 crs list
#> default_crs 0 -none- NULL
#> x 13 ViewScale environment
#> y 13 ViewScale environment
#> x.sec 13 ViewScale environment
#> y.sec 13 ViewScale environment
#> guides 4 Guides environment
# backwards compatibility
ggplot(mtcars, aes(cyl, mpg, color = factor(cyl))) +
geom_point() +
geom_debug()
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_panel()' input 'data' (head):"
#> colour x y PANEL group
#> 1 #00BA38 6 21.0 1 2
#> 2 #00BA38 6 21.0 1 2
#> 3 #F8766D 4 22.8 1 1
#> 4 #00BA38 6 21.4 1 2
#> 5 #619CFF 8 18.7 1 3
#> 6 #00BA38 6 18.1 1 2
ggplot(mtcars, aes(cyl, mpg, colour = factor(cyl))) +
stat_summary(fun.data = "mean_se") +
stat_summary(geom = "debug", fun.data = "mean_se")
#> [1] "PANEL 1; group(s) 1, 2, 3; 'draw_function()' input 'data' (head):"
#> colour x group y ymin ymax PANEL flipped_aes orientation
#> 1 #F8766D 4 1 26.66364 25.30387 28.02340 1 FALSE NA
#> 2 #00BA38 6 2 19.74286 19.19346 20.29225 1 FALSE NA
#> 3 #619CFF 8 3 15.10000 14.41580 15.78420 1 FALSE NA