ggplot2-ggproto {ggplot2} | R Documentation

## Base ggproto classes for ggplot2

### Description

If you are creating a new geom, stat, position, or scale in another package, you'll need to extend from `ggplot2::Geom`, `ggplot2::Stat`, `ggplot2::Position`, or `ggplot2::Scale`.

### Geoms

All `geom_*` functions (like `geom_point`) return a layer that contains a `Geom*` object (like `GeomPoint`). The `Geom*` object is responsible for rendering the data in the plot.

Each of the `Geom*` objects is a `ggproto` object, descended from the top-level `Geom`, and each implements various methods and fields. To create a new type of Geom object, you typically will want to implement one or more of the following:

Compared to `Stat` and `Position`, `Geom` is a little different because the execution of the setup and compute functions is split up. `setup_data` runs before position adjustments, and `draw_layer` is not run until render time, much later. This means there is no `setup_params` because it's hard to communicate the changes.

- Override either `draw_panel(self, data, panel_scales, coord)` or `draw_group(self, data, panel_scales, coord)`. `draw_panel` is called once per panel, `draw_group` is called once per group.

  Use `draw_panel` if each row in the data represents a single element. Use `draw_group` if each group represents an element (e.g. a smooth, a violin).

  `data` is a data frame of scaled aesthetics. `panel_scales` is a list containing information about the scales in the current panel. `coord` is a coordinate specification. You'll need to call `coord$transform(data, panel_scales)` to work with non-Cartesian coords. To work with non-linear coordinate systems, you typically need to convert into a primitive geom (e.g. point, path or polygon), and then pass on to the corresponding draw method for munching.

  Must return a grob. Use `zeroGrob` if there's nothing to draw.

- `draw_key`: Renders a single legend key.

- `required_aes`: A character vector of aesthetics needed to render the geom.

- `default_aes`: A list (generated by `aes()` of default values for aesthetics.

- `reparameterise`: Converts width and height to xmin and xmax, and ymin and ymax values. It can potentially set other values as well.

### Coordinate systems

All `coord_*` functions (like `coord_trans`) return a `Coord*` object (like `CoordTrans`). The `Coord*` object is responsible for adjusting the position of overlapping geoms.

The way that the `coord_*` functions work is slightly different from the `geom_*` and `stat_*` functions, because a `coord_*` function actually "instantiates" the `Coord*` object by creating a descendant, and returns that.

Each of the `Coord*` objects is a `ggproto` object, descended from the top-level `Coord`. To create a new type of Coord object, you typically will want to implement one or more of the following:

- `aspect`: Returns the desired aspect ratio for the plot.

- `labels`: Returns a list containing labels for x and y.

- `render_fg`: Renders foreground elements.

- `render_bg`: Renders background elements.

- `render_axis_h`: Renders the horizontal axis.

- `render_axis_v`: Renders the vertical axis.

- `range`: Returns the x and y ranges

- `train`: Return the trained scale ranges.

- `transform`: Transforms x and y coordinates.

- `distance`: Calculates distance.

- `is_linear`: Returns `TRUE` if the coordinate system is linear; `FALSE` otherwise.

### Stats

All `stat_*` functions (like `stat_bin`) return a layer that contains a `Stat*` object (like `StatBin`). The `Stat*` object is responsible for rendering the data in the plot.

Each of the `Stat*` objects is a `ggproto` object, descended from the top-level `Stat`, and each implements various methods and fields. To create a new type of Stat object, you typically will want to implement one or more of the following:

- Override one of : `compute_layer(self, data, scales, ...)`, `compute_panel(self, data, scales, ...)`, or `compute_group(self, data, scales, ...)`.

  `compute_layer()` is called once per layer, `compute_panel_()` is called once per panel, and `compute_group()` is called once per group. All must return a data frame.

  It's usually best to start by overriding `compute_group`: if you find substantial performance optimisations, override higher up. You'll need to read the source code of the default methods to see what else you should be doing.

  `data` is a data frame containing the variables named according to the aesthetics that they're mapped to. `scales` is a list containing the `x` and `y` scales. There functions are called before the facets are trained, so they are global scales, not local to the individual panels.`...` contains the parameters returned by `setup_params()`.

- `setup_params(data, params)`: called once for each layer. Used to setup defaults that need to complete dataset, and to inform the user of important choices. Should return list of parameters.

- `setup_data(data, params)`: called once for each layer, after `setp_params()`. Should return modified `data`. Default methods removes all rows containing a missing value in required aesthetics (with a warning if `!na.rm`).

- `required_aes`: A character vector of aesthetics needed to render the geom.

- `default_aes`: A list (generated by `aes()` of default values for aesthetics.

### Positions

All `position_*` functions (like `position_dodge`) return a `Position*` object (like `PositionDodge`). The `Position*` object is responsible for adjusting the position of overlapping geoms.

The way that the `position_*` functions work is slightly different from the `geom_*` and `stat_*` functions, because a `position_*` function actually "instantiates" the `Position*` object by creating a descendant, and returns that.

Each of the `Position*` objects is a `ggproto` object, descended from the top-level `Position`, and each implements the following methods:

- `compute_layer(self, data, params, panel)` is called once per layer. `panel` is currently an internal data structure, so this method should not be overriden.

- `compute_panel(self, data, params, panel)` is called once per panel and should return a modified data frame.

  `data` is a data frame containing the variables named according to the aesthetics that they're mapped to. `scales` is a list containing the `x` and `y` scales. There functions are called before the facets are trained, so they are global scales, not local to the individual panels. `params` contains the parameters returned by `setup_params()`.

- `setup_params(data, params)`: called once for each layer. Used to setup defaults that need to complete dataset, and to inform the user of important choices. Should return list of parameters.

- `setup_data(data, params)`: called once for each layer, after `setp_params()`. Should return modified `data`. Default checks that required aesthetics are present.

And the following fields

- `required_aes`: a character vector giving the aesthetics that must be present for this position adjustment to work.

### Scales

All `scale_*` functions (like `scale_x_continuous`) return a `Scale*` object (like `ScaleContinuous`). The `Scale*` object represents a single scale.

Each of the `Scale*` objects is a `ggproto` object, descended from the top-level `Scale`.

### See Also

ggproto

[Package ggplot2 version 2.1.0 Index]