Layer-class: Layers
In hadley/ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics
Layer-class R Documentation
Layers
Description
The Layer class is a chaperone class not available for extension. The class
fulfils the following tasks. The class houses the Geom, Stat and Position
trinity and tracks their stateful parameters. Furthermore, its methods are
responsible for managing the layer data and exposing it to other components
of the plot at the right time.
Details
The Layer class is an internal class that is not exported because the class
is not intended for extension. The layer() function instantiates the
LayerInstance class, which inherits from Layer, but has relevant fields
populated.
The class is mostly used in ggplot_build(), with the notable exception
of the draw_geom() method, which is used in ggplot_gtable() instead.
Fields
constructorA call object with the user-facing
constructor function, for use in error messaging. This field is populated
by layer().
geom,stat,positionThese fields house the Geom, Stat and Position
trifecta in ggproto form and is populated by layer().
stat_params,computed_stat_paramsThese fields hold parameters
assigned to the Stat. The stat_params field is directly derived from
user input and is populated by layer(). The computed_stat_params
carries state and is constructed by the Stat$setup_params() method.
geom_params,computed_geom_paramsThese fields hold parameters
assigned to the Geom. The geom_params field is directly derived from
user input and is populated by layer(). The computed_geom_params
carries state and is constructed by the Geom$setup_params() method.
mapping,computed_mappingThese fields hold mappings.
The mapping field holds the layer(mapping) argument. The
computed_mapping field carries state and is constructed in the
setup_layer() method.
dataThe fortified layer(data) argument.
aes_paramsHolds the fixed, unmapped aesthetics passed to
layer(params) as determined by Geom$aesthetics().
inherit.aesA scalar boolean used in the setup_layer() method to
indicate whether the computed_mapping should include the global mapping
(TRUE) or only the layer mapping (FALSE). This is populated by the
layer(inherit.aes) parameter.
layer_dataDescription
A function method for initially resolving layer data. If layer data is
missing or is a function, it will derive layer data from the global plot
data.
Usage
Layer$layer_data(plot_data)
Arguments
plot_dataThe data field of the ggplot object.
Value
A data frame with layer data or NULL
setup_layerDescription
A function method is a hook to allow a final access to layer data in
input form. In addition, it allows a layer access to global plot
information. The latter is used to enforce the inherit.aes parameter by
supplementing the layer mapping with the global mapping when requested.
Usage
Layer$setup_data(data, plot)
Arguments
dataA data frame with the layer's data.
plotA ggplot object
Value
A data frame with layer data. As a side effect, the computed_mapping
field is populated.
compute_aestheticsDescription
A function method that evaluates aesthetics and warns about any problems.
It also infers a group aesthetic if not provided. This method is also
the step where layer data becomes standardised to base data frames without
row names or additional attributes.
Usage
Layer$compute_aesthetics(data, plot)
Arguments
dataA data frame with the layer's data.
plotA ggplot object
Value
A data frame with layer data
compute_aestheticsDescription
A function method that orchestrates computing statistics. It executes
methods from the Stat class to form new computed variables.
Usage
Layer$compute_statistic(data, layout)
Arguments
dataA data frame with the layer's data.
layoutA <Layout> ggproto object.
Value
A data frame with layer data. As a side effect the computed_stat_params
field is populated.
map_statisticDescription
A function method that finishes the result of computed statistics. It has
several tasks:
It evaluates the after_stat() stage of the mapping from both the
computed_mapping but also the Stat$default_aes fields.
It ensures relevant scales are instantiated for computed aesthetics.
It takes care that scale transformation is applied to computed aesthetics.
Usage
Layer$map_statistic(data, plot)
Arguments
dataA data frame with the layer's data.
plotA ggplot object.
Value
A data frame with layer data
compute_geom_1Description
A function method that prepares data for drawing. It checks that all
required aesthetics are present and sets up parameters and data using the
Geom class.
Usage
Layer$compute_geom_1(data)
Arguments
dataA data frame with the layer's data.
Value
A data frame with layer data. As a side effect the computed_geom_params
field is populated.
compute_positionDescription
A function method that orchestrates the position adjustment. It executes
methods from the Position class.
Usage
Layer$compute_position(data, layout)
Arguments
dataA data frame with the layer's data.
layoutA <Layout> ggproto object.
Value
A data frame with layer data.
compute_geom_2Description
A function method that add defaults and fixed parameters. It wraps the
Geom$use_defaults() method.
Usage
Layer$compute_geom_2(data, params, theme, ...)
Arguments
dataA data frame with the layer's data.
paramsA list with fixed aesthetic parameters, typically the
aes_params field.
themeA theme object
...Passed on to Geom$use_defaults(), not in use.
Value
A data frame with layer data.
finish_statisticsDescription
A function method that wraps Stat$finish_layer().
Usage
Layer$finish_statistics(data)
Arguments
dataA data frame with the layer's data.
Value
A data frame with layer data.
draw_geomDescription
A function method that produces graphics for every panel. It uses Geom
class methods to handle missing data and produce grobs. In contrast to
other methods, this is called during the ggplot_gtable() stage, not the
ggplot_build() stage.
Usage
Layer$draw_geom(data, layout)
Arguments
dataA data frame with the layer's data.
layoutA <Layout> ggproto object.
Value
A list of grobs, one per panel.
printDescription
A function method that prints information about the layer.
Usage
Layer$print()
Value
Nothing (NULL), invisibly
Layer data diagram
As the Layer class is a chaparone for the data, it makes sense to give a
small overview of how layer data flows through a plot. In the diagram below
we following the layer(data) argument over the course of plot building
through Layer class methods. When an outside class acts on the data without
the Layer class, this is indicated with the left arrow <-. Subcomponents
of a method that touch data are indicated with the right arrow ->.
# Inside `ggplot_build()`
|
layer(data)
|
|
| # Inherit plot data
|
Layer$layer_data()
|
|
| # Finalise mapping
|
Layer$setup_layer()
|
|
| # Append PANEL variable for facets
|
|<- Layout$setup()
| |
| +-> Facet$setup_data()
| |
| +-> Coord$setup_data()
|
|
| # Evaluate mappings to new data and infer group
|
Layer$compute_aesthetics()
|
|
| # Scale-transform all aesthetics
|
|<- ScalesList$transform_df()
| |
| +-> Scale$transform_df()
|
|
| # Map x/y aesthetics with initial scale
|
|<- Layout$map_position()
| |
| +-> Scale$map()
|
|
| # Compute stat part of layer
|
Layer$compute_statistic()
| |
| +-> Stat$setup_data()
| |
| +-> Stat$compute_layer()
|
|
| # Add `after_stat()` stage
| # Scale transform computed variables
|
Layer$map_statistic()
|
|
| # Setup geom part of layer
|
Layer$compute_geom_1()
| |
| +-> Geom$setup_data()
|
|
| # Apply position adjustments
|
Layer$compute_position()
| |
| +-> Position$use_defaults()
| |
| +-> Position$setup_data()
| |
| +-> Position$compute_layer()
|
|
| # Map x/y aesthetics with final scales
|
|<- Layout$map_position()
| |
| +-> Scale$map()
|
| # Map non-position aesthetics
|
|<- ScalesList$map_df()
| |
| +-> Scale$map()
|
|
| # Fill in defaults and fixed aesthetics
|
Layer$compute_geom_2()
| |
| +-> Geom$use_defaults()
|
|
| # Apply final Stat hook
|
Layer$finish_statistics()
| |
| +-> Stat$finish_layer()
|
|
| # Apply final Facet hook
|
|<- Layout$finish_data()
| |
| +-> Facet$finish_data()
|
V
# `ggplot_build()` is finished
# Hand off to `ggplot_gtable()`
|
|
| # Draw the geom part
|
Layer$draw_geom()
|
+-> Geom$handle_na()
|
+-> Geom$draw_layer()
See Also
Other Layer components:
Geom,
Position,
Stat
Other chaperone classes:
Layout
Examples
# None: Layer is not intended to be extended
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.
| Layer-class | R Documentation |
Layers
Description
The Layer class is a chaperone class not available for extension. The class fulfils the following tasks. The class houses the Geom, Stat and Position trinity and tracks their stateful parameters. Furthermore, its methods are responsible for managing the layer data and exposing it to other components of the plot at the right time.
Details
The Layer class is an internal class that is not exported because the class
is not intended for extension. The layer() function instantiates the
LayerInstance class, which inherits from Layer, but has relevant fields
populated.
The class is mostly used in ggplot_build(), with the notable exception
of the draw_geom() method, which is used in ggplot_gtable() instead.
Fields
constructorA call object with the user-facing constructor function, for use in error messaging. This field is populated by
layer().geom,stat,positionThese fields house the Geom, Stat and Position trifecta in ggproto form and is populated by
layer().stat_params,computed_stat_paramsThese fields hold parameters assigned to the Stat. The
stat_paramsfield is directly derived from user input and is populated bylayer(). Thecomputed_stat_paramscarries state and is constructed by theStat$setup_params()method.geom_params,computed_geom_paramsThese fields hold parameters assigned to the Geom. The
geom_paramsfield is directly derived from user input and is populated bylayer(). Thecomputed_geom_paramscarries state and is constructed by theGeom$setup_params()method.mapping,computed_mappingThese fields hold mappings. The
mappingfield holds thelayer(mapping)argument. Thecomputed_mappingfield carries state and is constructed in thesetup_layer()method.dataThe fortified
layer(data)argument.aes_paramsHolds the fixed, unmapped aesthetics passed to
layer(params)as determined byGeom$aesthetics().inherit.aesA scalar boolean used in the
setup_layer()method to indicate whether thecomputed_mappingshould include the global mapping (TRUE) or only the layer mapping (FALSE). This is populated by thelayer(inherit.aes)parameter.layer_dataDescription
A function method for initially resolving layer data. If layer data is missing or is a function, it will derive layer data from the global plot data.
Usage
Layer$layer_data(plot_data)
Arguments
plot_dataThe
datafield of the ggplot object.
Value
A data frame with layer data or
NULLsetup_layerDescription
A function method is a hook to allow a final access to layer data in input form. In addition, it allows a layer access to global plot information. The latter is used to enforce the
inherit.aesparameter by supplementing the layer mapping with the global mapping when requested.Usage
Layer$setup_data(data, plot)
Arguments
dataA data frame with the layer's data.
plotA ggplot object
Value
A data frame with layer data. As a side effect, the
computed_mappingfield is populated.compute_aestheticsDescription
A function method that evaluates aesthetics and warns about any problems. It also infers a
groupaesthetic if not provided. This method is also the step where layer data becomes standardised to base data frames without row names or additional attributes.Usage
Layer$compute_aesthetics(data, plot)
Arguments
dataA data frame with the layer's data.
plotA ggplot object
Value
A data frame with layer data
compute_aestheticsDescription
A function method that orchestrates computing statistics. It executes methods from the Stat class to form new computed variables.
Usage
Layer$compute_statistic(data, layout)
Arguments
dataA data frame with the layer's data.
layoutA
<Layout>ggproto object.
Value
A data frame with layer data. As a side effect the
computed_stat_paramsfield is populated.map_statisticDescription
A function method that finishes the result of computed statistics. It has several tasks:
It evaluates the
after_stat()stage of the mapping from both thecomputed_mappingbut also theStat$default_aesfields.It ensures relevant scales are instantiated for computed aesthetics.
It takes care that scale transformation is applied to computed aesthetics.
Usage
Layer$map_statistic(data, plot)
Arguments
dataA data frame with the layer's data.
plotA ggplot object.
Value
A data frame with layer data
compute_geom_1Description
A function method that prepares data for drawing. It checks that all required aesthetics are present and sets up parameters and data using the Geom class.
Usage
Layer$compute_geom_1(data)
Arguments
dataA data frame with the layer's data.
Value
A data frame with layer data. As a side effect the
computed_geom_paramsfield is populated.compute_positionDescription
A function method that orchestrates the position adjustment. It executes methods from the Position class.
Usage
Layer$compute_position(data, layout)
Arguments
dataA data frame with the layer's data.
layoutA
<Layout>ggproto object.
Value
A data frame with layer data.
compute_geom_2Description
A function method that add defaults and fixed parameters. It wraps the
Geom$use_defaults()method.Usage
Layer$compute_geom_2(data, params, theme, ...)
Arguments
dataA data frame with the layer's data.
paramsA list with fixed aesthetic parameters, typically the
aes_paramsfield.themeA theme object
...Passed on to
Geom$use_defaults(), not in use.
Value
A data frame with layer data.
finish_statisticsDescription
A function method that wraps
Stat$finish_layer().Usage
Layer$finish_statistics(data)
Arguments
dataA data frame with the layer's data.
Value
A data frame with layer data.
draw_geomDescription
A function method that produces graphics for every panel. It uses Geom class methods to handle missing data and produce grobs. In contrast to other methods, this is called during the
ggplot_gtable()stage, not theggplot_build()stage.Usage
Layer$draw_geom(data, layout)
Arguments
dataA data frame with the layer's data.
layoutA
<Layout>ggproto object.
Value
A list of grobs, one per panel.
printDescription
A function method that prints information about the layer.
Usage
Layer$print()
Value
Nothing (
NULL), invisibly
Layer data diagram
As the Layer class is a chaparone for the data, it makes sense to give a
small overview of how layer data flows through a plot. In the diagram below
we following the layer(data) argument over the course of plot building
through Layer class methods. When an outside class acts on the data without
the Layer class, this is indicated with the left arrow <-. Subcomponents
of a method that touch data are indicated with the right arrow ->.
# Inside `ggplot_build()` | layer(data) | | | # Inherit plot data | Layer$layer_data() | | | # Finalise mapping | Layer$setup_layer() | | | # Append PANEL variable for facets | |<- Layout$setup() | | | +-> Facet$setup_data() | | | +-> Coord$setup_data() | | | # Evaluate mappings to new data and infer group | Layer$compute_aesthetics() | | | # Scale-transform all aesthetics | |<- ScalesList$transform_df() | | | +-> Scale$transform_df() | | | # Map x/y aesthetics with initial scale | |<- Layout$map_position() | | | +-> Scale$map() | | | # Compute stat part of layer | Layer$compute_statistic() | | | +-> Stat$setup_data() | | | +-> Stat$compute_layer() | | | # Add `after_stat()` stage | # Scale transform computed variables | Layer$map_statistic() | | | # Setup geom part of layer | Layer$compute_geom_1() | | | +-> Geom$setup_data() | | | # Apply position adjustments | Layer$compute_position() | | | +-> Position$use_defaults() | | | +-> Position$setup_data() | | | +-> Position$compute_layer() | | | # Map x/y aesthetics with final scales | |<- Layout$map_position() | | | +-> Scale$map() | | # Map non-position aesthetics | |<- ScalesList$map_df() | | | +-> Scale$map() | | | # Fill in defaults and fixed aesthetics | Layer$compute_geom_2() | | | +-> Geom$use_defaults() | | | # Apply final Stat hook | Layer$finish_statistics() | | | +-> Stat$finish_layer() | | | # Apply final Facet hook | |<- Layout$finish_data() | | | +-> Facet$finish_data() | V # `ggplot_build()` is finished # Hand off to `ggplot_gtable()` | | | # Draw the geom part | Layer$draw_geom() | +-> Geom$handle_na() | +-> Geom$draw_layer()
See Also
Other Layer components:
Geom,
Position,
Stat
Other chaperone classes:
Layout
Examples
# None: Layer is not intended to be extended
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.