ggplot2-ggproto: 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.

Arguments

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.