Guide: Guides
In hadley/ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics
Guide R Documentation
Guides
Description
The guide_* functions (like guide_legend()) return Guide* objects
(like GuideLegend). The Guide* object is responsible for rendering the
guide for at least one aesthetic.
Details
Each of the Guide* objects is a ggproto() object, descended from the
top-level Guide, and each implements various methods and fields.
Building a guide has three stages:
The guide extracts the relevant information from scales.
The guide interacts with other parts of the plot, like coords or layers to
supplement information.
The guide is rendered.
When creating a new Guide class, you may want to consider overriding one or
more of the following:
The params, elements, hashables and available_aes fields.
The extract_key(), extract_decor() and extract_params() methods.
The transform() or get_layer_key() methods.
The setup_params() and override_elements() methods.
Any of the build_* methods.
As a last resort the measure_grobs(), arrange_layout(), and
assemble_drawing() methods.
Fields
paramsA list of initial parameters that the guide needs to
function. The base Guide$params contains mandatory parameters,
but extensions can add new parameters. It has the following roles:
It provides the default values for parameters.
-
names(params) determines what are valid arguments for new_guide().
During build stages, a mutable copy of params holds information
about the guide.
available_aesA character vector of aesthetic names for which the
guide is appropriate. Can use keyword "any" to indicate all non-position
aesthetics.
elementsA named list of strings stating which theme elements this
guide uses. By default, strings will be translated in
Guide$setup_elements() using calc_element(). Strings are expected to
occur in names(get_element_tree()), like "legend.text" for example.
Position guides typically append the {aes}.{position} suffix in the
setup_elements() method when the position is known.
hashablesA list of calls or names constructed by rlang::exprs()
indicating objects in the params field. These will be evaluated in the
context of the params field and the resulting list will be hashed. The
hash uniquely identify guides that can merge. Guides that have different
hashes will not merge. For extensions, you should include objects that
clearly mark two guides from one another that cannot be merged.
trainDescription
A function method for orchestrating the training of a guide, which extracts
necessary information from a Scale object. As orchestrator, this method is
not intended for extension.
Usage
Guide$train(params, scale, aesthetic, ...)
Arguments
paramsA list of parameters initiated by the params field.
scaleA <Scale> ggproto object. In the case of position
guides, can be a <ViewScale> ggproto object.
aestheticA scalar string specifying the aesthetic.
If missing (default), it will use the first aesthetic specified in the
scale.
...Additional parameters passed on to the extract_params()
method.
Value
A modified list of parameters
extract_keyDescription
A function method for extracting break information from the scale called
the 'key'. It retrieves breaks, maps these breaks and derives labels. These
form the basis for tick marks and labels in some guides. It is appropriate
to override in extensions.
Usage
Guide$extract_key(scale, aesthetic, ...)
Arguments
scaleA <Scale> ggproto object. In the case of position
guides, can be a <ViewScale> ggproto object.
aestheticA scalar string specifying the aesthetic.
...Optional arguments from the params field.
Value
A 'key' data frame containing annotated scale breaks, including at least a
column for the aesthetic, .label and .value. If there are no breaks,
returns NULL.
extract_decorDescription
A function method for extracting 'decor' from the scale. The 'decor' acts
as a wildcard for anything the guide may need to render that is not based
on the key. For this reason, it has guide specific meaning that indicates
different things for different guides. In guide_colourbar() it is the
colour gradient, but in guide_axis() it is the axis line information.
It is appropriate to override in extensions.
Usage
Guide$extract_decor(scale, aesthetic, ...)
Arguments
scaleA <Scale> ggproto object. In the case of position
guides, can be a <ViewScale> ggproto object.
aestheticA scalar string specifying the aesthetic.
...Optional arguments from the params field.
Value
Undefined. NULL by default.
extract_paramsDescription
A function method for extracting any other information from the scale that
the guide may need. A typical example is to derive the title from the scale,
or apply any edits to the key or decor variables.
Usage
Geom$extract_params(scale, params, ...)
Arguments
scaleA <Scale> ggproto object. In the case of position
guides, can be a <ViewScale> ggproto object.
paramsA list of parameters initiated by the params field,
which at this point includes the key and decor from previous
extractors.
...Additional arguments passed from the train() method. For
non-position guides, often includes title as derived from the
plot$labels field.
Value
A modified list of parameters
transformDescription
A function method to apply coord transformation and munching to the
'key' and 'decor' parameters. This method only applies to position guides
like guide_axis() and is not called for non-position guides. It is
recommended to override this method if you have a position guide that
does not inherit from GuideAxis or has custom key' or 'decor' structures
that GuideAxis$transform() does not handle well.
Usage
Guide$transform(params, coord, ...)
Arguments
paramsA list of parameters initiated by the params field.
coordA <Coord> ggproto object.
...Optional arguments, typically panel_params for most
position guides.
Value
A list of parameters. The default throws an error.
mergeDescription
A function method for combining information from two guides. When two
guides have the same computed hash parameter derived from the hashables
field, this function will be called to merge them. If more than two guides
need to be merged, they are merged successively in a Reduce()-like
fashion.
Merging guides is the mechanism by which guide_legend() can take one
guide trained on the shape scale, another trained on the colour scale
and display them together in the same guide, for example.
Overriding this method is recommended if the extension descends directly
from Guide and not its children. Otherwise, it should be overridden if
presented with no superior options.
Usage
Guide$merge(params, new_guide, new_params)
Arguments
paramsA list of parameters derived from the params field of
this guide.
new_guideA <Guide> ggproto object representing the other guide class
new_paramsA list of parameters derived from the params field
of the other guide
Value
A named list containing guide and params, where guide is a <Guide>
ggproto object and params is a list with parameters. By default, returns
the new guide and its parameters.
process_layers,get_layer_keyDescription
These function methods extract information from layers that the guide may
need. The process_layers() method is tasked with selecting layers that
are represented by the guide and are to be included. The selected layers
should be passed on to the get_layer_key() method.
Typical use of these methods is for guide_legend() to extract the
Geom$draw_key function to render glyphs in addition to any default or
fixed aesthetics. While these methods are called in position guides,
the layers and data arguments are empty as these are unavailable at
that point.
You can override get_layer_key(), but process_layers() should
probably only be overridden if the extension does not inherit from
GuideLegend.
Usage
Guide$process_layers(params, layers, data, theme)
Guide$get_layer_key(params, layers, data, theme)
Arguments
paramsA list of parameters initiated by the params field.
layersA list of layers from plot$layers.
dataA list of layer data frames.
themeA completed theme object.
Value
A list of parameters
drawDescription
A function method is the main orchestrator for drawing the guide. It sets
up the final pieces in context of the position, direction and theme
and. Subsequenty, it renders the individual components like titles, ticks,
labels and decor. Finally, it arranges these components into a guide.
This method should only be overridden if the extension has non standard
components that do not fit into 'decor' or when this method can be greatly
simplified for humble guides. All subsidiaries are fine to override.
Usage
Geom$setup_params(theme, position, direction, params)
Arguments
themeA complete theme object.
positionA scalar string indicating the position where
the guide should be drawn. Typically "top", "right", "bottom"
or "left", unless it is a position guide for an exotic coord. Can be
NULL, in which case params$position should be used.
directionA scalar string indicating the legend direction.
Can be NULL, in which case params$direction should be used.
paramsA list of parameters initiated by the params field.
Value
A grob with the guide.
draw_early_exitDescription
A function method that determines what should be drawn when the guide 'key'
is empty. The default method returns zeroGrob(). You can override
this method if an empty key should draw anything. Used in guide_axis()
to render the axis.line part even if no ticks or labels should be drawn.
Usage
Guide$draw_early_exit(params, elements)
Arguments
paramsA list of parameters initiated by the params field.
elementsA list of elements or resolved theme settings from
the override_elements() method.
Value
A grob.
setup_paramsDescription
A function method for finalising parameters. Typically used to make checks
on the params object or to make any position or direction based
adjustments.
Usage
Guide$setup_params(params)
Arguments
paramsA list of parameters initiated by the params field.
Value
A list of parameters
setup_elements,override_elementsDescription
A function method for resolving required theme elements. The
setup_elements() method joins local guide theme with global theme and
calculates the necessary theme elements. The override_elements() method
is a hook to edit elements after they've been calculated.
You can override the setup_elements() method if you need more complicated
theme handling before calculating elements or want to intervene in inheritance.
For example, guide_legend() has special handling of text margins and
guide_axis() suffixes {aes}.{position} to get the theme elements for
the correct position.
For other purposes, you can override the override_elements() method.
Usage
Guide$setup_elements(params, elements, theme)
Guide$override_elements(params, elements, theme)
Arguments
paramsA list of parameters initiated by the params field.
elementsA named list of strings initiated by the elements field.
themeA complete theme
Value
A list of elements or resolved theme settings.
build_titleDescription
A function method for rendering the title. Note that titles for position
guides are rendered by the Facet class and not this method.
You can override this method if you need to render more than one title
(or none) or adjust margin settings.
Usage
Guide$build_title(label, elements, params)
Arguments
labelA single string or expression with the title text.
elementsA list of elements or resolved theme settings from
the override_elements() method. The default method expects
elements$title to inherit from the <element_text> class.
paramsA list of parameters initiated by the params field.
Value
A grob representing the title.
build_ticksDescription
A function method for rendering tick marks.
You can override this function if you don't need ticks or have completely
different logic on how these should be drawn.
Usage
Guide$build_ticks(key, elements, params, position, length)
Arguments
keyA data frame with the key information derived from the
extract_key() method.
elementsA list of elements or resolved theme settings from
the override_elements() method. The default method expects
elements$ticks to inherit from the <element_line> class and
elements$ticks_length to be a scalar <unit> object.
paramsA list of parameters initiated by the params field.
positionA scalar string indicating the position. Due to
historic error this works in the opposite way to intuition: if you want
ticks for an axis at the bottom of a plot, you should use "top" here.
lengthA scalar <unit> object giving the tick length.
Value
A grob representing tick marks.
build_labelsDescription
A function method for rendering labels. The default method returns an
empty grob. It is recommended to override this method when your extension
directly descends from Guide.
Usage
Guide$build_labels(key, elements, params)
Arguments
keyA data frame with the key information derived from the
extract_key() method.
elementsA list of elements or resolved theme settings from
the override_elements() method. Most non-default methods expects
elements$text to inherit from the <element_text>.
paramsA list of parameters initiated by the params field.
Value
A grob representing labels.
build_decorDescription
A function method for rendering decor. As the 'wildcard' component, this
can draw whatever component the guide needs that isn't already captured by
the key. The default method returns an empty grob. It is recommended to
override this method.
For some examples: guide_legend() renders the keys with the glyphs,
guide_colourbar() renders the colour gradient rectangle and
guide_axis() renders the axis line.
Usage
Guide$build_decor(decor, grobs, elements, params)
Arguments
decorA data frame (or other structure) with information derived
from the extract_decor() method.
grobsA list with grobs generated by the other build_*
methods.
elementsA list of elements or resolved theme settings from
the override_elements() method. Most non-default methods expects
elements$text to inherit from the <element_text>.
paramsA list of parameters initiated by the params field.
Value
A grob.
measure_grobsDescription
A function method for measuring grobs. In preparation for arranging grobs,
they often need to be measured to determine their widths and heights.
It is convention that every measurement is converted to centimetres.
You can override this method if your extension directly descends from
Guide, or the parent class measurement is defective.
Usage
Guide$measure_grobs(grobs, params, elements)
Arguments
grobsA list with grobs generated by the build_* methods.
paramsA list of parameters initiated by the params field.
elementsA list of elements or resolved theme settings from
the override_elements() method.
Value
A named list or <unit> vector giving sizes of components, coordinated
with arrange_layout() and assemble_drawing() methods. The default
method returns NULL.
arrange_layoutDescription
A function method for determining the location or order of grobs in a
gtable. Typically determines rows and columns where decor and labels are
placed. Titles are added seperately.You can override this method if your
extension directly descends from Guide.
Usage
Guide$arrange_layout(key, sizes, params, elements)
Arguments
keyA data frame with the key information derived from the
extract_key() method.
sizesA list of <unit> vector from the measure_grobs() method.
paramsA list of parameters initiated by the params field.
elementsA list of elements or resolved theme settings from
the override_elements() method.
Value
Any structure holding placement information coordinated with the
assemble_drawing() method.
assemble_drawingDescription
A function method that takes measurements, placement information and grobs
and assembles these together in a gtable structure. You can override this
method if your extension directly descends from Guide, or the parent class
assembly does not work for your guide.
Usage
Guide$assemble_drawing(grobs, layout, sizes, params, elements)
Arguments
grobsA list with grobs generated by the build_* methods.
layoutA data structure from the arrange_layout() method.
sizesA list of <unit> vector from the measure_grobs() method.
paramsA list of parameters initiated by the params field.
elementsA list of elements or resolved theme settings from
the override_elements() method.
Value
A finished gtable containing the guide.
arrange_layoutDescription
A function method for placing the title. It is a subsidiary method used
in the assemble_drawing() method for non-position guides. Titles are
typically added before legend.margin is applied. It is not
recommended to override this method.
Usage
Guide$add_title(gtable, title, position, just)
Arguments
gtableAn unfinished gtable under construction in the
assemble_drawing() method.
titleThe grob resulting from the build_title() method.
positionA scaler string, either "top", "right", "bottom"
or "left" corresponding to the legend.title.position.
justA named list having hjust and vjust components with
scalar numeric values between 0 and 1.
Value
The gtable argument with added title.
Conventions
The object name that a new class is assigned to is typically the same as the
class name. Guide class names are in UpperCamelCase and start with the
Guide* prefix, like GuideNew.
A constructor function is usually paired with a Guide class. The constructor
wraps a call to new_guide(), where e.g. new_guide(super = GuideNew). The
constructor name is formatted by taking the Guide class name and formatting
it with snake_case, so that GuideNew becomes guide_new().
See Also
Run vignette("extending-ggplot2"), in particular the "Creating
new guides" section.
Examples
# Extending the class
GuideDescribe <- ggproto(
"GuideDescribe", Guide,
# Fields
elements = list(text = "legend.text", margin = "legend.margin"),
hashables = rlang::exprs(key$.label),
# Methods
build_title = function(...) zeroGrob(), # Turn off title
build_labels = function(key, elements, params) {
labels <- key$.label
n <- length(labels)
labels <- paste0(paste0(labels[-n], collapse = ", "), ", and ", labels[n])
labels <- paste0("A guide showing ", labels, " categories")
element_grob(elements$text, label = labels, margin_x = TRUE, margin_y = TRUE)
},
measure_grobs = function(grobs, params, elements) {
# Measuring in centimetres is the convention
width <- grid::convertWidth(grid::grobWidth(grobs$labels), "cm", valueOnly = TRUE)
height <- grid::convertHeight(grid::grobHeight(grobs$labels), "cm", valueOnly = TRUE)
list(width = unit(width, "cm"), height = unit(height, "cm"))
},
assemble_drawing = function(self, grobs, layout, sizes, params, elements) {
gt <- gtable::as.gtable(grobs$labels, width = sizes$width, height = sizes$height)
gt <- gtable::gtable_add_padding(gt, elements$margin)
gt
}
)
# Building a constructor
guide_describe <- function(position = NULL) {
new_guide(position = position, super = GuideDescribe)
}
# Use new guide plot
ggplot(mpg, aes(displ, hwy, colour = class)) +
geom_point() +
guides(colour = guide_describe("bottom"))
hadley/ggplot2 documentation built on June 13, 2025, 12:51 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Guide | R Documentation |
Guides
Description
The guide_* functions (like guide_legend()) return Guide* objects
(like GuideLegend). The Guide* object is responsible for rendering the
guide for at least one aesthetic.
Details
Each of the Guide* objects is a ggproto() object, descended from the
top-level Guide, and each implements various methods and fields.
Building a guide has three stages:
The guide extracts the relevant information from scales.
The guide interacts with other parts of the plot, like coords or layers to supplement information.
The guide is rendered.
When creating a new Guide class, you may want to consider overriding one or more of the following:
The
params,elements,hashablesandavailable_aesfields.The
extract_key(),extract_decor()andextract_params()methods.The
transform()orget_layer_key()methods.The
setup_params()andoverride_elements()methods.Any of the
build_*methods.As a last resort the
measure_grobs(),arrange_layout(), andassemble_drawing()methods.
Fields
paramsA list of initial parameters that the guide needs to function. The base
Guide$paramscontains mandatory parameters, but extensions can add new parameters. It has the following roles:It provides the default values for parameters.
-
names(params)determines what are valid arguments fornew_guide(). During build stages, a mutable copy of
paramsholds information about the guide.
available_aesA character vector of aesthetic names for which the guide is appropriate. Can use keyword
"any"to indicate all non-position aesthetics.elementsA named list of strings stating which theme elements this guide uses. By default, strings will be translated in
Guide$setup_elements()usingcalc_element(). Strings are expected to occur innames(get_element_tree()), like"legend.text"for example. Position guides typically append the{aes}.{position}suffix in thesetup_elements()method when the position is known.hashablesA list of calls or names constructed by
rlang::exprs()indicating objects in theparamsfield. These will be evaluated in the context of theparamsfield and the resulting list will be hashed. The hash uniquely identify guides that can merge. Guides that have different hashes will not merge. For extensions, you should include objects that clearly mark two guides from one another that cannot be merged.trainDescription
A function method for orchestrating the training of a guide, which extracts necessary information from a Scale object. As orchestrator, this method is not intended for extension.
Usage
Guide$train(params, scale, aesthetic, ...)
Arguments
paramsA list of parameters initiated by the
paramsfield.scaleA
<Scale>ggproto object. In the case of position guides, can be a<ViewScale>ggproto object.aestheticA scalar string specifying the aesthetic. If missing (default), it will use the first aesthetic specified in the scale.
...Additional parameters passed on to the
extract_params()method.
Value
A modified list of parameters
extract_keyDescription
A function method for extracting break information from the scale called the 'key'. It retrieves breaks, maps these breaks and derives labels. These form the basis for tick marks and labels in some guides. It is appropriate to override in extensions.
Usage
Guide$extract_key(scale, aesthetic, ...)
Arguments
scaleA
<Scale>ggproto object. In the case of position guides, can be a<ViewScale>ggproto object.aestheticA scalar string specifying the aesthetic.
...Optional arguments from the
paramsfield.
Value
A 'key' data frame containing annotated scale breaks, including at least a column for the aesthetic,
.labeland.value. If there are no breaks, returnsNULL.extract_decorDescription
A function method for extracting 'decor' from the scale. The 'decor' acts as a wildcard for anything the guide may need to render that is not based on the key. For this reason, it has guide specific meaning that indicates different things for different guides. In
guide_colourbar()it is the colour gradient, but inguide_axis()it is the axis line information. It is appropriate to override in extensions.Usage
Guide$extract_decor(scale, aesthetic, ...)
Arguments
scaleA
<Scale>ggproto object. In the case of position guides, can be a<ViewScale>ggproto object.aestheticA scalar string specifying the aesthetic.
...Optional arguments from the
paramsfield.
Value
Undefined.
NULLby default.extract_paramsDescription
A function method for extracting any other information from the scale that the guide may need. A typical example is to derive the title from the scale, or apply any edits to the
keyordecorvariables.Usage
Geom$extract_params(scale, params, ...)
Arguments
scaleA
<Scale>ggproto object. In the case of position guides, can be a<ViewScale>ggproto object.paramsA list of parameters initiated by the
paramsfield, which at this point includes thekeyanddecorfrom previous extractors....Additional arguments passed from the
train()method. For non-position guides, often includestitleas derived from theplot$labelsfield.
Value
A modified list of parameters
transformDescription
A function method to apply coord transformation and munching to the 'key' and 'decor' parameters. This method only applies to position guides like
guide_axis()and is not called for non-position guides. It is recommended to override this method if you have a position guide that does not inherit fromGuideAxisor has custom key' or 'decor' structures thatGuideAxis$transform()does not handle well.Usage
Guide$transform(params, coord, ...)
Arguments
paramsA list of parameters initiated by the
paramsfield.coordA
<Coord>ggproto object....Optional arguments, typically
panel_paramsfor most position guides.
Value
A list of parameters. The default throws an error.
mergeDescription
A function method for combining information from two guides. When two guides have the same computed
hashparameter derived from thehashablesfield, this function will be called to merge them. If more than two guides need to be merged, they are merged successively in aReduce()-like fashion.Merging guides is the mechanism by which
guide_legend()can take one guide trained on theshapescale, another trained on thecolourscale and display them together in the same guide, for example.Overriding this method is recommended if the extension descends directly from
Guideand not its children. Otherwise, it should be overridden if presented with no superior options.Usage
Guide$merge(params, new_guide, new_params)
Arguments
paramsA list of parameters derived from the
paramsfield of this guide.new_guideA
<Guide>ggproto object representing the other guide classnew_paramsA list of parameters derived from the
paramsfield of the other guide
Value
A named list containing
guideandparams, whereguideis a<Guide>ggproto object andparamsis a list with parameters. By default, returns the new guide and its parameters.process_layers,get_layer_keyDescription
These function methods extract information from layers that the guide may need. The
process_layers()method is tasked with selecting layers that are represented by the guide and are to be included. The selected layers should be passed on to theget_layer_key()method.Typical use of these methods is for
guide_legend()to extract theGeom$draw_keyfunction to render glyphs in addition to any default or fixed aesthetics. While these methods are called in position guides, thelayersanddataarguments are empty as these are unavailable at that point.You can override
get_layer_key(), butprocess_layers()should probably only be overridden if the extension does not inherit fromGuideLegend.Usage
Guide$process_layers(params, layers, data, theme) Guide$get_layer_key(params, layers, data, theme)
Arguments
paramsA list of parameters initiated by the
paramsfield.layersA list of layers from
plot$layers.dataA list of layer data frames.
themeA completed theme object.
Value
A list of parameters
drawDescription
A function method is the main orchestrator for drawing the guide. It sets up the final pieces in context of the position, direction and theme and. Subsequenty, it renders the individual components like titles, ticks, labels and decor. Finally, it arranges these components into a guide.
This method should only be overridden if the extension has non standard components that do not fit into 'decor' or when this method can be greatly simplified for humble guides. All subsidiaries are fine to override.
Usage
Geom$setup_params(theme, position, direction, params)
Arguments
themeA complete theme object.
positionA scalar string indicating the position where the guide should be drawn. Typically
"top","right","bottom"or"left", unless it is a position guide for an exotic coord. Can beNULL, in which caseparams$positionshould be used.directionA scalar string indicating the legend direction. Can be
NULL, in which caseparams$directionshould be used.paramsA list of parameters initiated by the
paramsfield.
Value
A grob with the guide.
draw_early_exitDescription
A function method that determines what should be drawn when the guide 'key' is empty. The default method returns
zeroGrob(). You can override this method if an empty key should draw anything. Used inguide_axis()to render theaxis.linepart even if no ticks or labels should be drawn.Usage
Guide$draw_early_exit(params, elements)
Arguments
paramsA list of parameters initiated by the
paramsfield.elementsA list of elements or resolved theme settings from the
override_elements()method.
Value
A grob.
setup_paramsDescription
A function method for finalising parameters. Typically used to make checks on the
paramsobject or to make any position or direction based adjustments.Usage
Guide$setup_params(params)
Arguments
paramsA list of parameters initiated by the
paramsfield.
Value
A list of parameters
setup_elements,override_elementsDescription
A function method for resolving required theme elements. The
setup_elements()method joins local guide theme with global theme and calculates the necessary theme elements. Theoverride_elements()method is a hook to edit elements after they've been calculated.You can override the
setup_elements()method if you need more complicated theme handling before calculating elements or want to intervene in inheritance. For example,guide_legend()has special handling of text margins andguide_axis()suffixes{aes}.{position}to get the theme elements for the correct position.For other purposes, you can override the
override_elements()method.Usage
Guide$setup_elements(params, elements, theme) Guide$override_elements(params, elements, theme)
Arguments
paramsA list of parameters initiated by the
paramsfield.elementsA named list of strings initiated by the
elementsfield.themeA complete theme
Value
A list of elements or resolved theme settings.
build_titleDescription
A function method for rendering the title. Note that titles for position guides are rendered by the Facet class and not this method.
You can override this method if you need to render more than one title (or none) or adjust margin settings.
Usage
Guide$build_title(label, elements, params)
Arguments
labelA single string or expression with the title text.
elementsA list of elements or resolved theme settings from the
override_elements()method. The default method expectselements$titleto inherit from the<element_text>class.paramsA list of parameters initiated by the
paramsfield.
Value
A grob representing the title.
build_ticksDescription
A function method for rendering tick marks.
You can override this function if you don't need ticks or have completely different logic on how these should be drawn.
Usage
Guide$build_ticks(key, elements, params, position, length)
Arguments
keyA data frame with the key information derived from the
extract_key()method.elementsA list of elements or resolved theme settings from the
override_elements()method. The default method expectselements$ticksto inherit from the<element_line>class andelements$ticks_lengthto be a scalar<unit>object.paramsA list of parameters initiated by the
paramsfield.positionA scalar string indicating the position. Due to historic error this works in the opposite way to intuition: if you want ticks for an axis at the bottom of a plot, you should use
"top"here.lengthA scalar
<unit>object giving the tick length.
Value
A grob representing tick marks.
build_labelsDescription
A function method for rendering labels. The default method returns an empty grob. It is recommended to override this method when your extension directly descends from Guide.
Usage
Guide$build_labels(key, elements, params)
Arguments
keyA data frame with the key information derived from the
extract_key()method.elementsA list of elements or resolved theme settings from the
override_elements()method. Most non-default methods expectselements$textto inherit from the<element_text>.paramsA list of parameters initiated by the
paramsfield.
Value
A grob representing labels.
build_decorDescription
A function method for rendering decor. As the 'wildcard' component, this can draw whatever component the guide needs that isn't already captured by the key. The default method returns an empty grob. It is recommended to override this method.
For some examples:
guide_legend()renders the keys with the glyphs,guide_colourbar()renders the colour gradient rectangle andguide_axis()renders the axis line.Usage
Guide$build_decor(decor, grobs, elements, params)
Arguments
decorA data frame (or other structure) with information derived from the
extract_decor()method.grobsA list with grobs generated by the other
build_*methods.elementsA list of elements or resolved theme settings from the
override_elements()method. Most non-default methods expectselements$textto inherit from the<element_text>.paramsA list of parameters initiated by the
paramsfield.
Value
A grob.
measure_grobsDescription
A function method for measuring grobs. In preparation for arranging grobs, they often need to be measured to determine their widths and heights. It is convention that every measurement is converted to centimetres. You can override this method if your extension directly descends from Guide, or the parent class measurement is defective.
Usage
Guide$measure_grobs(grobs, params, elements)
Arguments
grobsA list with grobs generated by the
build_*methods.paramsA list of parameters initiated by the
paramsfield.elementsA list of elements or resolved theme settings from the
override_elements()method.
Value
A named list or
<unit>vector giving sizes of components, coordinated witharrange_layout()andassemble_drawing()methods. The default method returnsNULL.arrange_layoutDescription
A function method for determining the location or order of grobs in a gtable. Typically determines rows and columns where decor and labels are placed. Titles are added seperately.You can override this method if your extension directly descends from Guide.
Usage
Guide$arrange_layout(key, sizes, params, elements)
Arguments
keyA data frame with the key information derived from the
extract_key()method.sizesA list of
<unit>vector from themeasure_grobs()method.paramsA list of parameters initiated by the
paramsfield.elementsA list of elements or resolved theme settings from the
override_elements()method.
Value
Any structure holding placement information coordinated with the
assemble_drawing()method.assemble_drawingDescription
A function method that takes measurements, placement information and grobs and assembles these together in a gtable structure. You can override this method if your extension directly descends from Guide, or the parent class assembly does not work for your guide.
Usage
Guide$assemble_drawing(grobs, layout, sizes, params, elements)
Arguments
grobsA list with grobs generated by the
build_*methods.layoutA data structure from the
arrange_layout()method.sizesA list of
<unit>vector from themeasure_grobs()method.paramsA list of parameters initiated by the
paramsfield.elementsA list of elements or resolved theme settings from the
override_elements()method.
Value
A finished gtable containing the guide.
arrange_layoutDescription
A function method for placing the title. It is a subsidiary method used in the
assemble_drawing()method for non-position guides. Titles are typically added beforelegend.marginis applied. It is not recommended to override this method.Usage
Guide$add_title(gtable, title, position, just)
Arguments
gtableAn unfinished gtable under construction in the
assemble_drawing()method.titleThe grob resulting from the
build_title()method.positionA scaler string, either
"top","right","bottom"or"left"corresponding to thelegend.title.position.justA named list having
hjustandvjustcomponents with scalar numeric values between 0 and 1.
Value
The
gtableargument with added title.
Conventions
The object name that a new class is assigned to is typically the same as the
class name. Guide class names are in UpperCamelCase and start with the
Guide* prefix, like GuideNew.
A constructor function is usually paired with a Guide class. The constructor
wraps a call to new_guide(), where e.g. new_guide(super = GuideNew). The
constructor name is formatted by taking the Guide class name and formatting
it with snake_case, so that GuideNew becomes guide_new().
See Also
Run vignette("extending-ggplot2"), in particular the "Creating
new guides" section.
Examples
# Extending the class
GuideDescribe <- ggproto(
"GuideDescribe", Guide,
# Fields
elements = list(text = "legend.text", margin = "legend.margin"),
hashables = rlang::exprs(key$.label),
# Methods
build_title = function(...) zeroGrob(), # Turn off title
build_labels = function(key, elements, params) {
labels <- key$.label
n <- length(labels)
labels <- paste0(paste0(labels[-n], collapse = ", "), ", and ", labels[n])
labels <- paste0("A guide showing ", labels, " categories")
element_grob(elements$text, label = labels, margin_x = TRUE, margin_y = TRUE)
},
measure_grobs = function(grobs, params, elements) {
# Measuring in centimetres is the convention
width <- grid::convertWidth(grid::grobWidth(grobs$labels), "cm", valueOnly = TRUE)
height <- grid::convertHeight(grid::grobHeight(grobs$labels), "cm", valueOnly = TRUE)
list(width = unit(width, "cm"), height = unit(height, "cm"))
},
assemble_drawing = function(self, grobs, layout, sizes, params, elements) {
gt <- gtable::as.gtable(grobs$labels, width = sizes$width, height = sizes$height)
gt <- gtable::gtable_add_padding(gt, elements$margin)
gt
}
)
# Building a constructor
guide_describe <- function(position = NULL) {
new_guide(position = position, super = GuideDescribe)
}
# Use new guide plot
ggplot(mpg, aes(displ, hwy, colour = class)) +
geom_point() +
guides(colour = guide_describe("bottom"))
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.