Layout: Layout
In hadley/ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics
Layout R Documentation
Layout
Description
The Layout class is a chaperone class discouraged for extension. The class
fulfils the following tasks. The class houses the Coord and Facet classes
and tracks their stateful parameters. In addition, it manages the position
scales for each panel. It is responsible for keeping track of panel
specifications and matching pieces of the data to scales and parameters in
panel-wise manners.
Details
The Layout class is only exported for extensions that re-implement a
ggplot_build() method for their specific class of plots. It is discouraged
to subclass the Layout class and for all purposes be considered an internal
structure. It has no user-facing constructor to put an small barrier in the
way.
The class is used throughout ggplot_build(), with the notable exception of
the render() method, which is used in ggplot_gtable() instead.
Fields
coord,coord_paramsA <Coord> ggproto object and a list
of the coordinate system's parameters. Parameters get populated by the
Coord$setup_params() method.
facet,facet_paramsA <Facet> ggproto object and a list
of the faceting specification's parameters. Parameters get populated by
the Facet$setup_params() method.
layoutA data frame with a row for each panel. The data frame
contains integer columns PANEL, SCALE_X, SCALE_Y, ROW and COL
representing a panel ID, scale indices and placement locations. In addition,
the layout may contain faceting variables or other additional information.
This field gets populated by the Facet$compute_layout() method.
panel_scales_x,panel_scales_yA list of x and y position scales
parallel to the layout field's SCALE_X and SCALE_Y levels respectively.
This fields gets populated by the Facet$init_scales() method.
panel_paramsA named list of parameters per panel populated by the
Coord$setup_panel_params() method. Contains <ViewScale> entries for
the x and y variables in addition to ranges and other information the
coordinate system might need to transform or render guides and grids.
setupDescription
A function method for setting up the relevant information for the layout
of the plot. It populates the facet_params, coord_params and layout
fields and appends a PANEL variable to the layer data.
Usage
Layout$setup(data, plot_data, plot_env)
Arguments
dataA list of data frames with layer data.
plot_dataThe data frame in the data field of the ggplot
object.
plot_envThe environment in the plot_env field of the
ggplot object.
Value
A list of data frames from the data argument with a PANEL variable
corresponding to rows in the layout field.
Also called for the side effects of populating fields.
train_positionDescription
A function method for training position scales and optionally initiating
them. Implementation is via the Facet$train_scales() and
Facet$init_scales() methods.
Usage
Layout$train_position(data, x_scale, y_scale)
Arguments
dataA list of data frames with layer data.
x_scale,y_scaleA single prototype position scale for the x
and y aesthetics respectively.
Value
Nothing, this method is called for the side effect of training scales and
optionally populating the panel_scales_x and panel_scales_y fields.
map_positionDescription
A function method for mapping position aesthetics. For discrete scales this
converts discrete levels to a numeric representation, usually integers. For
continuous scales, this applies out-of-bounds handling.
Usage
Layout$map_position(data)
Arguments
dataA list of data frames with layer data.
Value
A list of data frames per the data argument with mapped position
aesthetics.
reset_scalesDescription
A function method for resetting scale ranges. After computing stats and
position adjustments, scales need to be reset and re-trained to have an
accurate measure of the data limits. This goes through the
panel_scales_x and panel_scales_y fields and invokes the
Scale$reset() method.
Usage
Layout$reset_scales()
Value
Nothing, it is called for the side-effect of resetting scale ranges.
setup_panel_paramsDescription
A function method for executing Coord$setup_panel_params() once per panel
with the appropriate scales. For efficiency reasons, the setup is invoked
once per unique combination of x and y scale.
Usage
Layout$setup_panel_params()
Value
Nothing, it is called for the side effect of populating the panel_params
field.
setup_panel_guidesDescription
A function method for setting up and training the position guides (axes)
once per panel with the appropriate scales. For efficiency reasons,
the guides are setup once per unique combination of x and y scale.
It calls the Coord$setup_panel_guides() and Coord$train_panel_guides()
methods.
Usage
Layout$setup_panel_guides(guides, layers)
Arguments
guidesA <Guides> ggproto object from the guides field of
the ggplot object.
layersA list of layers from the layers field of the ggplot
object.
Value
Nothing, it is called for the side effect of augmenting each entry of the
panel_params field with position guides.
setup_panel_guidesDescription
A function method for setting up the Facet$finish_data() hook.
Usage
Layout$finish_data(data)
Arguments
dataA list of data frames with layer data.
Value
A list of data frames with layer data.
renderDescription
A function method for drawing and assembling the core plot. Mostly it
delegates tasks to the specific Facet methods for drawing components.
Usage
Layout$render(panels, data, theme, labels)
Arguments
panelsA list parallel to layers. Each element is another list
with grobs for each panel, generated by Layer$draw_geom().
dataA list of data frames with layer data.
themeA complete theme.
labelsA list of labels from the labels field of the ggplot
object.
Value
A gtable containing a plot with panels, axes, axis titles and strips.
resolve_labelDescription
A function method for prying the axis titles from guides, scales or plot
labels.
Usage
Layout$resolve_label(scale, labels)
Arguments
scaleA single scale from the panel_scales_x or
panel_scales_y fields.
labelsA list of labels from the labels field of the ggplot
object.
Value
A named list containing a two titles named "primary" and "secondary".
render_labelsDescription
A function method for drawing axis title grobs. The position guides
themselves do not typically render the axis title grobs as they are
orchestrated by the layout to draw one title even for multiple axes.
Usage
Layout$render_labels(labels, theme)
Arguments
labelsA named list containing an x list and a y list. The
x and y lists have primary and secondary labels. It originates
from the Coord$labels() method.
themeA complete theme.
Value
A list with the same structure and names as the labels argument, but with
grobs instead of text.
get_scalesDescription
A function method for retrieving panel specific scales. It is called in
the Stat$compute_layer() and Position$compute_layer() methods. The
Geom uses the panel_params field instead of the raw scales.
Usage
Layout$get_scales(i)
Arguments
iA scalar integer panel index giving the panel for which to
retrieve scales
Value
A named list of scales giving the x and y scale for the panel.
See Also
Other Layout components:
Coord,
Facet
Other chaperone classes:
Layer-class
Examples
# Some dummy layout components
facet <- facet_null()
coord <- coord_cartesian()
# Use in custom `ggplot_build()` methods
layout <- ggproto(NULL, Layout, facet = facet, coord = coord)
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.
| Layout | R Documentation |
Layout
Description
The Layout class is a chaperone class discouraged for extension. The class fulfils the following tasks. The class houses the Coord and Facet classes and tracks their stateful parameters. In addition, it manages the position scales for each panel. It is responsible for keeping track of panel specifications and matching pieces of the data to scales and parameters in panel-wise manners.
Details
The Layout class is only exported for extensions that re-implement a
ggplot_build() method for their specific class of plots. It is discouraged
to subclass the Layout class and for all purposes be considered an internal
structure. It has no user-facing constructor to put an small barrier in the
way.
The class is used throughout ggplot_build(), with the notable exception of
the render() method, which is used in ggplot_gtable() instead.
Fields
coord,coord_paramsA
<Coord>ggproto object and a list of the coordinate system's parameters. Parameters get populated by theCoord$setup_params()method.facet,facet_paramsA
<Facet>ggproto object and a list of the faceting specification's parameters. Parameters get populated by theFacet$setup_params()method.layoutA data frame with a row for each panel. The data frame contains integer columns
PANEL,SCALE_X,SCALE_Y,ROWandCOLrepresenting a panel ID, scale indices and placement locations. In addition, the layout may contain faceting variables or other additional information. This field gets populated by theFacet$compute_layout()method.panel_scales_x,panel_scales_yA list of
xandyposition scales parallel to the layout field'sSCALE_XandSCALE_Ylevels respectively. This fields gets populated by theFacet$init_scales()method.panel_paramsA named list of parameters per panel populated by the
Coord$setup_panel_params()method. Contains<ViewScale>entries for thexandyvariables in addition to ranges and other information the coordinate system might need to transform or render guides and grids.setupDescription
A function method for setting up the relevant information for the layout of the plot. It populates the
facet_params,coord_paramsandlayoutfields and appends aPANELvariable to the layer data.Usage
Layout$setup(data, plot_data, plot_env)
Arguments
dataA list of data frames with layer data.
plot_dataThe data frame in the
datafield of the ggplot object.plot_envThe environment in the
plot_envfield of the ggplot object.
Value
A list of data frames from the
dataargument with aPANELvariable corresponding to rows in thelayoutfield. Also called for the side effects of populating fields.train_positionDescription
A function method for training position scales and optionally initiating them. Implementation is via the
Facet$train_scales()andFacet$init_scales()methods.Usage
Layout$train_position(data, x_scale, y_scale)
Arguments
dataA list of data frames with layer data.
x_scale,y_scaleA single prototype position scale for the
xandyaesthetics respectively.
Value
Nothing, this method is called for the side effect of training scales and optionally populating the
panel_scales_xandpanel_scales_yfields.map_positionDescription
A function method for mapping position aesthetics. For discrete scales this converts discrete levels to a numeric representation, usually integers. For continuous scales, this applies out-of-bounds handling.
Usage
Layout$map_position(data)
Arguments
dataA list of data frames with layer data.
Value
A list of data frames per the
dataargument with mapped position aesthetics.reset_scalesDescription
A function method for resetting scale ranges. After computing stats and position adjustments, scales need to be reset and re-trained to have an accurate measure of the data limits. This goes through the
panel_scales_xandpanel_scales_yfields and invokes theScale$reset()method.Usage
Layout$reset_scales()
Value
Nothing, it is called for the side-effect of resetting scale ranges.
setup_panel_paramsDescription
A function method for executing
Coord$setup_panel_params()once per panel with the appropriate scales. For efficiency reasons, the setup is invoked once per unique combination ofxandyscale.Usage
Layout$setup_panel_params()
Value
Nothing, it is called for the side effect of populating the
panel_paramsfield.setup_panel_guidesDescription
A function method for setting up and training the position guides (axes) once per panel with the appropriate scales. For efficiency reasons, the guides are setup once per unique combination of
xandyscale. It calls theCoord$setup_panel_guides()andCoord$train_panel_guides()methods.Usage
Layout$setup_panel_guides(guides, layers)
Arguments
guidesA
<Guides>ggproto object from theguidesfield of the ggplot object.layersA list of layers from the
layersfield of the ggplot object.
Value
Nothing, it is called for the side effect of augmenting each entry of the
panel_paramsfield with position guides.setup_panel_guidesDescription
A function method for setting up the
Facet$finish_data()hook.Usage
Layout$finish_data(data)
Arguments
dataA list of data frames with layer data.
Value
A list of data frames with layer data.
renderDescription
A function method for drawing and assembling the core plot. Mostly it delegates tasks to the specific Facet methods for drawing components.
Usage
Layout$render(panels, data, theme, labels)
Arguments
panelsA list parallel to layers. Each element is another list with grobs for each panel, generated by
Layer$draw_geom().dataA list of data frames with layer data.
themeA complete theme.
labelsA list of labels from the
labelsfield of the ggplot object.
Value
A gtable containing a plot with panels, axes, axis titles and strips.
resolve_labelDescription
A function method for prying the axis titles from guides, scales or plot labels.
Usage
Layout$resolve_label(scale, labels)
Arguments
scaleA single scale from the
panel_scales_xorpanel_scales_yfields.labelsA list of labels from the
labelsfield of the ggplot object.
Value
A named list containing a two titles named
"primary"and"secondary".render_labelsDescription
A function method for drawing axis title grobs. The position guides themselves do not typically render the axis title grobs as they are orchestrated by the layout to draw one title even for multiple axes.
Usage
Layout$render_labels(labels, theme)
Arguments
labelsA named list containing an
xlist and aylist. Thexandylists haveprimaryandsecondarylabels. It originates from theCoord$labels()method.themeA complete theme.
Value
A list with the same structure and names as the
labelsargument, but with grobs instead of text.get_scalesDescription
A function method for retrieving panel specific scales. It is called in the
Stat$compute_layer()andPosition$compute_layer()methods. TheGeomuses thepanel_paramsfield instead of the raw scales.Usage
Layout$get_scales(i)
Arguments
iA scalar integer panel index giving the panel for which to retrieve scales
Value
A named list of scales giving the
xandyscale for the panel.
See Also
Other Layout components:
Coord,
Facet
Other chaperone classes:
Layer-class
Examples
# Some dummy layout components
facet <- facet_null()
coord <- coord_cartesian()
# Use in custom `ggplot_build()` methods
layout <- ggproto(NULL, Layout, facet = facet, coord = coord)
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.