animint2-gganimintproto: Base gganimintproto classes for ggplot2

animint2-gganimintprotoR Documentation

Base gganimintproto classes for ggplot2

Description

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

Usage

a_scales_list()

ScalesList

Format

An object of class ScalesList (inherits from gganimintproto) of length 9.

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 gganimintproto 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 gganimintproto 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 gganimintproto 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 gganimintproto 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 gganimintproto object, descended from the top-level Scale.

See Also

gganimintproto


animint2 documentation built on Nov. 22, 2023, 1:07 a.m.