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 axes.

- `render_axis_v`: Renders the vertical axes.

- `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.

### Facets

All `facet_*` functions returns a `Facet` object or an object of a `Facet` subclass. This object describes how to assign data to different panels, how to apply positional scales and how to lay out the panels, once rendered.

Extending facets can range from the simple modifications of current facets, to very laborious rewrites with a lot of `gtable` manipulation. For some examples of both, please see the extension vignette.

`Facet` subclasses, like other extendible ggproto classes, have a range of methods that can be modified. Some of these are required for all new subclasses, while other only need to be modified if need arises.

The required methods are:

- `compute_layout`: Based on layer data compute a mapping between panels, axes, and potentially other parameters such as faceting variable level etc. This method must return a data.frame containing at least the columns `PANEL`, `SCALE_X`, and `SCALE_Y` each containing integer keys mapping a PANEL to which axes it should use. In addition the data.frame can contain whatever other information is necessary to assign observations to the correct panel as well as determining the position of the panel.

- `map_data`: This method is supplied the data for each layer in turn and is expected to supply a `PANEL` column mapping each row to a panel defined in the layout. Additionally this method can also add or subtract data points as needed e.g. in the case of adding margins to `facet_grid`.

- `draw_panels`: This is where the panels are assembled into a `gtable` object. The method recieves, among others, a list of grobs defining the content of each panel as generated by the Geoms and Coord objects. The responsibility of the method is to decorate the panels with axes and strips as needed, as well as position them relative to each other in a gtable. For some of the automatic functions to work correctly, each panel, axis, and strip grob name must be prefixed with "panel", "axis", and "strip" respectively.

In addition to the methods described above, it is also possible to override the default behaviour of one or more of the following methods:

- `setup_params`:

- `init_scales`: Given a master scale for x and y, create panel specific scales for each panel defined in the layout. The default is to simply clone the master scale.

- `train_scales`: Based on layer data train each set of panel scales. The default is to train it on the data related to the panel.

- `finish_data`: Make last-minute modifications to layer data before it is rendered by the Geoms. The default is to not modify it.

- `draw_back`: Add a grob in between the background defined by the Coord object (usually the axis grid) and the layer stack. The default is to return an empty grob for each panel.

- `draw_front`: As above except the returned grob is placed between the layer stack and the foreground defined by the Coord object (usually empty). The default is, as above, to return an empty grob.

- `draw_labels`: Given the gtable returned by `draw_panels`, add axis titles to the gtable. The default is to add one title at each side depending on the position and existance of axes.

All extension methods recieve the content of the params field as the params argument, so the constructor function will generally put all relevant information into this field. The only exception is the `shrink` parameter which is used to determine if scales are retrained after Stat transformations has been applied.

### 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()`.

- `finish_layer(data, params)`: called once for each layer. Used to modify the data after scales has been applied, but before the data is handed of to the geom for rendering. The default is to not modify the data. Use this hook if the stat needs access to the actual aesthetic values rather than the values that are mapped to the aesthetic.

- `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.2.1 Index]