Base ggproto classes for ggplot2

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.

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.

To create a new type of Geom object, you typically will want to override one or more of the following:

• Either draw_panel(self, data, panel_params, coord) or draw_group(self, data, panel_params, 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_params is a set of per-panel parameters for the coord. Generally, you should consider panel_params to be an opaque data structure that you pass along whenever you call a coord method.

  You must always call coord$transform(data, panel_params) to get the (position) scaled data for plotting. 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.

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

See also the new geoms section of the online ggplot2 book.

Coordinate systems

All coord_*() functions (like coord_trans()) return a Coord* object (like CoordTrans).

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.

• backtransform_range(panel_params): Extracts the panel range provided in panel_params (created by setup_panel_params(), see below) and back-transforms to data coordinates. This back-transformation can be needed for coords such as coord_trans() where the range in the transformed coordinates differs from the range in the untransformed coordinates. Returns a list of two ranges, x and y, and these correspond to the variables mapped to the x and y aesthetics, even for coords such as coord_flip() where the x aesthetic is shown along the y direction and vice versa.

• range(panel_params): Extracts the panel range provided in panel_params (created by setup_panel_params(), see below) and returns it. Unlike backtransform_range(), this function does not perform any back-transformation and instead returns final transformed coordinates. Returns a list of two ranges, x and y, and these correspond to the variables mapped to the x and y aesthetics, even for coords such as coord_flip() where the x aesthetic is shown along the y direction and vice versa.

• transform: Transforms x and y coordinates.

• distance: Calculates distance.

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

• is_free: Returns TRUE if the coordinate system supports free positional scales; FALSE otherwise.

• setup_panel_params(scale_x, scale_y, params): Determines the appropriate x and y ranges for each panel, and also calculates anything else needed to render the panel and axes, such as tick positions and labels for major and minor ticks. Returns all this information in a named list.

• setup_data(data, params): Allows the coordinate system to manipulate the plot data. Should return list of data frames.

• setup_layout(layout, params): Allows the coordinate system to manipulate the layout data frame which assigns data to panels and scales.

See also the new coords section of the online ggplot2 book.

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 receives, 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 existence of axes.

All extension methods receive 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.

See also the new facets section of the online ggplot2 book.

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 override one or more of the following:

• 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 setup_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.

• dropped_aes is a vecor of aesthetic names that are safe to drop after statistical transformation. A classic example is the weight aesthetic that is consumed during computation of the stat.

See also the new stats section of the online ggplot2 book.

Guides

The guide_*() functions, such as guide_legend() return an object that is responsible for displaying how objects in the plotting panel are related to actual values.

Each of the Guide* object is a ggproto() object, descended from the top-level Guide, and each implements their own methods for drawing.

To create a new type of Guide object, you typically will want to override one or more of the following:

Properties:

• available_aes A character vector with aesthetics that this guide supports. The value "any" indicates all non-position aesthetics.

• params A named list of parameters that the guide needs to function. It has the following roles:

  • params provides the defaults for a guide.

  • names(params) determines what are valid arguments to new_guide(). Some parameters are required to render the guide. These are: title, name, position, direction, order and hash.

  • During build stages, params holds information about the guide.

• elements A named list of characters, giving the name of theme elements that should be retrieved automatically, for example "legend.text".

• hashables An expression that can be evaluated in the context of params. The hash of the evaluated expression determines the merge compatibility of guides, and is stored in params$hash.

Methods:

• extract_key() Returns a data.frame with (mapped) breaks and labels extracted from the scale, which will be stored in params$key.

• extract_decor() Returns a data.frame containing other structured information extracted from the scale, which will be stored in params$decor. The decor has a guide-specific meaning: it is the bar in guide_colourbar(), but specifies the axis.line in guide_axis().

• extract_params() Updates the params with other, unstructured information from the scale. An example of this is inheriting the guide's title from the scale$name field.

• transform() Updates the params$key based on the coordinates. This applies to position guides, as it rescales the aesthetic to the [0, 1] range.

• merge() Combines information from multiple guides with the same params$hash. This ensures that e.g. guide_legend() can display both shape and colour in the same guide.

• process_layers() Extract information from layers. This acts mostly as a filter for which layers to include and these are then (typically) forwarded to get_layer_key().

• get_layer_key() This can be used to gather information about how legend keys should be displayed.

• setup_params() Set up parameters at the beginning of drawing stages. It can be used to overrule user-supplied parameters or perform checks on the params property.

• override_elements() Take populated theme elements derived from the elements property and allows overriding these theme settings.

• build_title() Render the guide's title.

• build_labels() Render the guide's labels.

• build_decor() Render the params$decor, which is different for every guide.

• build_ticks() Render tick marks.

• measure_grobs() Measure dimensions of the graphical objects produced by the build_*() methods to be used in the layout or assembly.

• arrange_layout() Set up a layout for how graphical objects produced by the build_*() methods should be arranged.

• assemble_drawing() Take the graphical objects produced by the build_*() methods, the measurements from measure_grobs() and layout from arrange_layout() to finalise the guide.

• add_title Adds the title to a gtable, taking into account the size of the title as well as the gtable size.

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

• compute_panel(self, data, params, scales) 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 setup_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.

See also the new positions section of the online ggplot2 book.

Scales

All scale_* functions like scale_x_continuous() return a Scale* object like ScaleContinuous. Each of the Scale* objects is a ggproto() object, descended from the top-level Scale.

Properties not documented in continuous_scale() or discrete_scale():

• call The call to continuous_scale() or discrete_scale() that constructed the scale.

• range One of continuous_range() or discrete_range().

Methods:

• is_discrete() Returns TRUE if the scale is a discrete scale

• is_empty() Returns TRUE if the scale contains no information (i.e., it has no information with which to calculate its limits).

• clone() Returns a copy of the scale that can be trained independently without affecting the original scale.

• transform() Transforms a vector of values using self$trans. This occurs before the Stat is calculated.

• train() Update the self$range of observed (transformed) data values with a vector of (possibly) new values.

• reset() Reset the self$range of observed data values. For discrete position scales, only the continuous range is reset.

• map() Map transformed data values to some output value as determined by self$rescale() and self$palette (except for position scales, which do not use the default implementation of this method). The output corresponds to the transformed data value in aesthetic space (e.g., a color, line width, or size).

• rescale() Rescale transformed data to the range 0, 1. This is most useful for position scales. For continuous scales, rescale() uses the rescaler that was provided to the constructor. rescale() does not apply self$oob() to its input, which means that discrete values outside limits will be NA, and values that are outside range will have values less than 0 or greater than 1. This allows guides more control over how out-of-bounds values are displayed.

• transform_df(), train_df(), map_df() These _df variants accept a data frame, and apply the transform, train, and map methods (respectively) to the columns whose names are in self$aesthetics.

• get_limits() Calculates the final scale limits in transformed data space based on the combination of self$limits and/or the range of observed values (self$range).

• get_breaks() Calculates the final scale breaks in transformed data space based on on the combination of self$breaks, self$trans$breaks() (for continuous scales), and limits. Breaks outside of limits are assigned a value of NA (continuous scales) or dropped (discrete scales).

• get_labels() Calculates labels for a given set of (transformed) breaks based on the combination of self$labels and breaks.

• get_breaks_minor() For continuous scales, calculates the final scale minor breaks in transformed data space based on the rescaled breaks, the value of self$minor_breaks, and the value of self$trans$minor_breaks(). Discrete scales always return NULL.

• get_transformation() Returns the scale's transformation object.

• make_title() Hook to modify the title that is calculated during guide construction (for non-position scales) or when the Layout calculates the x and y labels (position scales).

These methods are only valid for position (x and y) scales:

• dimension() For continuous scales, the dimension is the same concept as the limits. For discrete scales, dimension() returns a continuous range, where the limits would be placed at integer positions. dimension() optionally expands this range given an expansion of length 4 (see expansion()).

• break_info() Returns a list() with calculated values needed for the Coord to transform values in transformed data space. Axis and grid guides also use these values to draw guides. This is called with a (usually expanded) continuous range, such as that returned by self$dimension() (even for discrete scales). The list has components major_source (self$get_breaks() for continuous scales, or seq_along(self$get_breaks()) for discrete scales), major (the rescaled value of major_source, ignoring self$rescaler), minor (the rescaled value of minor_source, ignoring self$rescaler), range (the range that was passed in to break_info()), labels (the label values, one for each element in breaks).

• axis_order() One of c("primary", "secondary") or c("secondary", "primary")

• make_sec_title() Hook to modify the title for the second axis that is calculated when the Layout calculates the x and y labels.

See also

ggproto