Extending ggplot2: How to build a geom and stat?

Question

I am in the early stages of learning how to extend ggplot2. I would like to create a custom geom and associated stat. My starting point was the vignette. In addition, I have benefited from this and this. I'm trying to put together a template to teach myself and hopefully others.

Main question:

Inside my function calculate_shadows() the needed parameter params$anchor is NULL. How can I access it?

The goal described below is intended solely for learning how to create custom stat and geom functions, it's not a real goal: as you can see from the screenshots, I do know how to leverage the power of ggplot2 to make the graphs.

1. The geom will read the data and for the supplied variables ("x", "y") will plot (for want of a better word) shadows: a horizontal line min(x)--max(x) at the default y=0 and a vertical line min(y)--max(y) at the default x=0. If an option is supplied, these "anchors" could be changed, e.g. if the user supplies x = 35, y = 1, the horizontal line would be drawn at the intercept y = 1 while the vertical line would be drawn at the intercept x = 35. Usage:

   library(ggplot2)
   ggplot(data = mtcars, aes(x = mpg, y = wt)) + 
       geom_point() +
       geom_shadows(x = 35, y = 1) 
   

2. The stat will read the data and for the supplied variables ("x", "y") will compute shadows according to the value of stat. For instance, by passing stat = "identity", the shadows would be computed for the min and max of the data (as done by geom_shadows). But by passing stat = "quartile", the shadows would be computed for first and third quartile. More generally, one could pass a function like stats::quantile with arguments args = list(probs = c(0.10, 0.90), type = 6), to compute shadows using the 10th and 90th percentiles and the quantile method of type 6. Usage:

   ggplot(data = mtcars, aes(x = mpg, y = wt)) + 
       geom_point() +
       stat_shadows(stat = "quartile") 
   

Unfortunately, my lack of familiarity with extending ggplot2 stopped me well short of my objective. These plots were "faked" with geom_segment. Based on the tutorial and discussions cited above and inspecting existing code like stat-qq or stat-smooth, I have put together a basic architecture for this goal. It must contain many mistakes, I would be grateful for guidance. Also, note that either of these approaches would be fine: geom_shadows(anchor = c(35, 1)) or geom_shadows(x = 35, y = 1).

Now here are my efforts. First, geom-shadows.r to define geom_shadows(). Second, stat-shadows.r to define stat_shadows(). The code doesn't work as is. But if I execute its content, it does produce the desired statistics. For clarity, I have removed most of the calculations in stat_shadows(), such as quartiles, to focus on essentials. Any obvious mistake in the layout?

geom-shadows.r

#' documentation ought to be here
geom_shadows <- function(
  mapping = NULL, 
  data = NULL, 
  stat = "shadows", 
  position = "identity", 
  ...,
  anchor = list(x = 0, y = 0),
  shadows = list("x", "y"), 
  type = NULL,
  na.rm = FALSE,
  show.legend = NA, 
  inherit.aes = TRUE) {
    layer(
      data = data,
      mapping = mapping,
      stat = stat,
      geom = GeomShadows,
      position = position,
      show.legend = show.legend,
      inherit.aes = inherit.aes,
      params = list(
        anchor = anchor,
        shadows = shadows,
        type = type,  
        na.rm = na.rm,
        ...
    )
  )
}

GeomShadows <- ggproto("GeomShadows", Geom, 

  # set up the data, e.g. remove missing data
  setup_data = function(data, params) { 
    data 
  }, 

  # set up the parameters, e.g. supply warnings for incorrect input
  setup_params = function(data, params) {
    params
  },

  draw_group = function(data, panel_params, coord, anchor, shadows, type) { 
    # draw_group uses stats returned by compute_group

    # set common aesthetics
    geom_aes <- list(
      alpha = data$alpha,
      colour = data$color,
      size = data$size,
      linetype = data$linetype,
      fill = alpha(data$fill, data$alpha),
      group = data$group
    )

    # merge aesthetics with data calculated in setup_data
    geom_stats <- new_data_frame(c(list(
          x = c(data$x.xmin, data$y.xmin),
          xend = c(data$x.xmax, data$y.xmax),
          y = c(data$x.ymin, data$y.ymin),
          yend = c(data$x.ymax, data$y.ymax),
          alpha = c(data$alpha, data$alpha) 
        ), geom_aes
      ), n = 2) 

    # turn the stats data into a GeomPath
    geom_grob <- GeomSegment$draw_panel(unique(geom_stats), 
        panel_params, coord) 

    # pass the GeomPath to grobTree
    ggname("geom_shadows", grobTree(geom_grob)) 
  },

  # set legend box styles
  draw_key = draw_key_path,

  # set default aesthetics 
  default_aes = aes(
    colour = "blue",
    fill = "red",
    size = 1,
    linetype = 1,
    alpha = 1
  )

)

stat-shadows.r

#' documentation ought to be here
stat_shadows <-  
  function(mapping = NULL, 
           data = NULL,
           geom = "shadows", 
           position = "identity",
           ...,
           # do I need to add the geom_shadows arguments here?
           anchor = list(x = 0, y = 0),
           shadows = list("x", "y"), 
           type = NULL,
           na.rm = FALSE,
           show.legend = NA,
           inherit.aes = TRUE) {
  layer(
    stat = StatShadows,  
    data = data,
    mapping = mapping,
    geom = geom,
    position = position,
    show.legend = show.legend,
    inherit.aes = inherit.aes,
    params = list(
      # geom_shadows argument repeated here?
      anchor = anchor,  
      shadows = shadows,
      type = type,
      na.rm = na.rm,
      ...
    )
  )
}

StatShadows <- 
  ggproto("StatShadows", Stat,

    # do I need to repeat required_aes?
    required_aes = c("x", "y"), 

    # set up the data, e.g. remove missing data
    setup_data = function(data, params) {
      data
    },

    # set up parameters, e.g. unpack from list
    setup_params = function(data, params) {
      params
    },

    # calculate shadows: returns data_frame with colnames: xmin, xmax, ymin, ymax 
    compute_group = function(data, scales, anchor = list(x = 0, y = 0), shadows = list("x", "y"), type = NULL, na.rm = TRUE) {

      .compute_shadows(data = data, anchor = anchor, shadows = shadows, type = type)

  }
)

# Calculate the shadows for each type / shadows / anchor
.compute_shadows <- function(data, anchor, shadows, type) {

# Deleted all type-checking, etc. for MWE
# Only 'type = c(double, double)' accepted, e.g. type = c(0, 1)

qs <- type

# compute shadows along the x-axis
if (any(shadows == "x")) {
    shadows.x <- c(
    xmin = as.numeric(stats::quantile(data[, "x"], qs[[1]])),
    xmax = as.numeric(stats::quantile(data[, "x"], qs[[2]])),
    ymin = anchor[["y"]], 
    ymax = anchor[["y"]]) 
}

# compute shadows along the y-axis
if (any(shadows == "y")) {
    shadows.y <- c(
    xmin = anchor[["x"]], 
    xmax = anchor[["x"]], 
    ymin = as.numeric(stats::quantile(data[, "y"], qs[[1]])),
    ymax = as.numeric(stats::quantile(data[, "y"], qs[[2]])))
} 

# store shadows in one data_frame
stats <- new_data_frame(c(x = shadows.x, y = shadows.y))

# return the statistics
stats
}

.

Answer 1

Until a more thorough answer comes along: You are missing

extra_params = c("na.rm", "shadows", "anchor", "type"),

inside GeomShadows <- ggproto("GeomShadows", Geom,

and possibly also inside StatShadows <- ggproto("StatShadows", Stat,.

Inside geom-.r and stat-.r there are many very useful comments that clarify how geoms and stats work. In particular (hat tips Claus Wilke over at github issues):

# Most parameters for the geom are taken automatically from draw_panel() or
# draw_groups(). However, some additional parameters may be needed
# for setup_data() or handle_na(). These can not be imputed automatically,
# so the slightly hacky "extra_params" field is used instead. By
# default it contains `na.rm`
extra_params = c("na.rm"),