ggplot2

https://ggplot2.tidyverse.org
Admin
ggplot2 is a system for declaratively creating graphics based on the Grammar of Graphics, allowing...
Tokens:459,513
Snippets:3,968
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Guide Setup Parameters Method

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Finalizes parameters for a guide, performing checks and making adjustments based on position or direction. Returns the adjusted parameters.

```r
Guide$setup_params(params)
```

--------------------------------

### Standard Binned Guide Example

Source: https://ggplot2.tidyverse.org/reference/guide_bins.html

Demonstrates the default appearance of a binned guide for a size aesthetic using guide_bins().

```R
p <- ggplot(mtcars) +
  geom_point(aes(disp, mpg, size = hp)) +
  scale_size_binned()

# Standard look
p
```

--------------------------------

### Coordinate System Panel Guides Setup

Source: https://ggplot2.tidyverse.org/reference/Coord.html

This method initiates position guides for each panel. For efficiency, it's called once per combination of x and y scales. It resolves guides from plot$guides and Scale$guide fields and sets appropriate Guide$params$position parameters.

```r
Coord$setup_panel_guides(panel_params, guides, params)
```

--------------------------------

### Layout Setup Panel Guides Method

Source: https://ggplot2.tidyverse.org/reference/Layout.html

Sets up and trains position guides (axes) per panel using appropriate scales. It calls Coord$setup_panel_guides() and Coord$train_panel_guides().

```r
Layout$setup_panel_guides(guides, layers)
```

--------------------------------

### Control order of multiple guides

Source: https://ggplot2.tidyverse.org/reference/guides.html

This example shows how to explicitly set the display order for multiple guides (colour, shape, size) using the `order` argument within guide functions.

```R
ggplot(mpg, aes(displ, cty)) +
  geom_point(aes(size = hwy, colour = cyl, shape = drv)) +
  guides(
   colour = guide_colourbar(order = 1),
   shape = guide_legend(order = 2),
   size = guide_legend(order = 3)
 )
```

--------------------------------

### Apply a single guide to multiple aesthetics

Source: https://ggplot2.tidyverse.org/reference/guides.html

This example shows how to apply the same guide configuration (e.g., a legend with a specific title) to multiple aesthetics at once.

```R
p +
  guides(
    colour = guide_legend("title"),
    size = guide_legend("title"),
    shape = guide_legend("title")
 )
```

--------------------------------

### Define a custom guide with a grob

Source: https://ggplot2.tidyverse.org/reference/guide_custom.html

Use guide_custom to display a graphical object as a guide. This example shows how to add a circle grob as a guide with a custom title.

```r
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point()

circle <- grid::circleGrob()

p + guides(custom = guide_custom(circle, title = "My circle"))
```

--------------------------------

### Stacked Axis Guide Example

Source: https://ggplot2.tidyverse.org/reference/guide_axis_stack.html

Demonstrates how to use guide_axis_stack to combine a standard axis with a capped axis. This is useful for visualizing data with different axis treatments simultaneously.

```r
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  theme(axis.line = element_line())

p + guides(x = guide_axis_stack("axis", guide_axis(cap = "both")))
```

--------------------------------

### guides() function

Source: https://ggplot2.tidyverse.org/reference/guides.html

The `guides()` function allows you to set guides for each scale individually or collectively. You can specify guides by scale name and either a string name (e.g., "colorbar") or a guide function call (e.g., `guide_colorbar()`).

```APIDOC
## guides(...)

### Description
Set guides for each scale scale-by-scale with the `guide` argument, or en masse with `guides()`.

### Arguments
* `...`: List of scale name-guide pairs. The guide can either be a string (i.e. "colorbar" or "legend"), or a call to a guide function (i.e. `guide_colourbar()` or `guide_legend()`) specifying additional arguments.

### Value
A list containing the mapping between scale and guide.

### See also
Other guides: `guide_bins()`, `guide_colourbar()`, `guide_coloursteps()`, `guide_legend()`

### Examples
```R
# ggplot object
dat <- data.frame(x = 1:5, y = 1:5, p = 1:5, q = factor(1:5), r = factor(1:5))
p <- ggplot(dat, aes(x, y, colour = p, size = q, shape = r)) + geom_point()

# Show colorbar guide for colour.
p + guides(colour = "colorbar", size = "legend", shape = "legend")
p + guides(colour = guide_colorbar(), size = guide_legend(), shape = guide_legend())
p + scale_colour_continuous(guide = "colorbar") + scale_size_discrete(guide = "legend") + scale_shape(guide = "legend")

# Remove some guides
p + guides(colour = "none")
p + guides(colour = "colorbar",size = "none")

# Guides are integrated where possible
p + guides(colour = guide_legend("title"), size = guide_legend("title"), shape = guide_legend("title") )
# same as
g <- guide_legend("title")
p + guides(colour = g, size = g, shape = g)

# position of guides
# Set order for multiple guides
ggplot(mpg, aes(displ, cty)) + geom_point(aes(size = hwy, colour = cyl, shape = drv)) + guides(colour = guide_colourbar(order = 1), shape = guide_legend(order = 2), size = guide_legend(order = 3))
```
```

--------------------------------

### Specify guides using guide functions

Source: https://ggplot2.tidyverse.org/reference/guides.html

Shows how to use explicit guide functions like `guide_colorbar()` and `guide_legend()` to assign guides, allowing for additional customization.

```R
p + guides(colour = guide_colorbar(), size = guide_legend(),
  shape = guide_legend())
```

--------------------------------

### guide_custom

Source: https://ggplot2.tidyverse.org/reference/guide_custom.html

A special guide that can be used to display any graphical object (grob) along with the regular guides. This guide has no associated scale.

```APIDOC
## guide_custom

### Description
Displays any graphical object (grob) along with regular guides. This guide has no associated scale.

### Usage
```R
guide_custom(
  grob,
  width = grobWidth(grob),
  height = grobHeight(grob),
  title = NULL,
  theme = NULL,
  position = NULL,
  order = 0
)
```

### Arguments

*   **grob** (grob) - A grob to display.
*   **width** (unit) - The allocated width to display the grob, given in `grid::unit()`s.
*   **height** (unit) - The allocated height to display the grob, given in `grid::unit()`s.
*   **title** (string or expression) - A character string or expression indicating the title of guide. If `NULL` (default), no title is shown.
*   **theme** (theme object) - A `theme` object to style the guide individually or differently from the plot's theme settings. Arguments that apply to a single legend are respected, most of which have the `legend`-prefix. Arguments that apply to combined legends (the legend box) are ignored, including `legend.position`, `legend.justification.*`, `legend.location` and `legend.box.*`.
*   **position** (string) - A character string indicating where the legend should be placed relative to the plot panels. One of "top", "right", "bottom", "left", or "inside".
*   **order** (integer) - Positive integer less than 99 that specifies the order of this guide among multiple guides. This controls the order in which multiple guides are displayed, not the contents of the guide itself. If 0 (default), the order is determined by a secret algorithm.

### Examples
```R
# A standard plot
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point()

# Define a graphical object
circle <- grid::circleGrob()

# Rendering a grob as a guide
p + guides(custom = guide_custom(circle, title = "My circle"))


# Controlling the size of the grob defined in relative units
p + guides(custom = guide_custom(
  circle, title = "My circle",
  width = unit(2, "cm"), height = unit(2, "cm"))
)


# Size of grobs in absolute units is taken directly without the need to
# set these manually
p + guides(custom = guide_custom(
  title = "My circle",
  grob = grid::circleGrob(r = unit(1, "cm"))
))
```
```

--------------------------------

### Example Usage of Hmisc Summary Functions

Source: https://ggplot2.tidyverse.org/reference/hmisc.html

Shows how to use mean_cl_boot, mean_cl_normal, mean_sdl, and median_hilow with a numeric vector. Requires the Hmisc package to be installed.

```r
if (requireNamespace("Hmisc", quietly = TRUE)) {
set.seed(1)
x <- rnorm(100)
mean_cl_boot(x)
mean_cl_normal(x)
mean_sdl(x)
median_hilow(x)
}
```

--------------------------------

### Guide$assemble_drawing

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Assembles grobs, layout, and sizes into a gtable structure. This method can be overridden if your extension directly descends from Guide, or if the parent class assembly does not work for your guide.

```APIDOC
## Guide$assemble_drawing

### Description
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

* `grobs` (list) - A list with grobs generated by the `build_*` methods.
* `layout` (data structure) - A data structure from the `arrange_layout()` method.
* `sizes` (list of `<unit>` vector) - A list of `<unit>` vector from the `measure_grobs()` method.
* `params` (list) - A list of parameters initiated by the `params` field.
* `elements` (list) - A list of elements or resolved theme settings from the `override_elements()` method.

### Value
A finished gtable containing the guide.
```

--------------------------------

### Assemble Guide Drawing

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Assembles grobs, placement information, and sizes into a gtable structure for the final guide. This method is central to constructing the visual representation of the guide.

```r
Guide$assemble_drawing(grobs, layout, sizes, params, elements)
```

--------------------------------

### guide_axis_stack

Source: https://ggplot2.tidyverse.org/reference/guide_axis_stack.html

Creates a stacked axis guide by combining multiple position guides. The 'first' guide is placed closest to the panel, followed by any additional guides provided.

```APIDOC
## guide_axis_stack

### Description
Creates a stacked axis guide by combining multiple position guides. The 'first' guide is placed closest to the panel, followed by any additional guides provided.

### Usage
```R
guide_axis_stack(
  first = "axis",
  ...,
  title = waiver(),
  theme = NULL,
  spacing = NULL,
  order = 0,
  position = waiver()
)
```

### Arguments

*   **first** (guide | string) - The first position guide to be stacked. Can be a string (e.g., "axis") or a guide function call (e.g., `guide_axis()`).
*   **...** (guides) - Additional guides to stack, provided in the same manner as `first`.
*   **title** (string | expression | NULL | waiver) - The title for the guide. Defaults to `waiver()`, which uses the scale name or `labs()` name.
*   **theme** (theme) - A `theme` object to style the guide individually.
*   **spacing** (unit) - A `unit()` object to control the spacing between separate guides.
*   **order** (integer) - An integer specifying the order of this guide among multiple guides for the same position. Defaults to 0.
*   **position** (string | waiver) - Where the guide should be drawn: one of top, bottom, left, or right. Defaults to `waiver()`.

### Details
The `first` guide will be placed closest to the panel and any subsequent guides provided through `...` will follow in the given order.

### Examples

```R
# A standard plot
p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  theme(axis.line = element_line())

# A normal axis first, then a capped axis
p + guides(x = guide_axis_stack("axis", guide_axis(cap = "both")))
```
```

--------------------------------

### Guide$setup_elements and Guide$override_elements

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Methods for resolving and overriding theme elements. `setup_elements` joins local and global themes, while `override_elements` allows for post-calculation edits.

```APIDOC
## Guide$setup_elements(params, elements, theme)

### Description
A function method for resolving required theme elements. Joins local guide theme with global theme and calculates the necessary theme elements.

### Arguments

* `params` (list) - A list of parameters initiated by the `params` field.
* `elements` (named list) - A named list of strings initiated by the `elements` field.
* `theme` (theme) - A complete theme.

### Value
A list of elements or resolved theme settings.

## Guide$override_elements(params, elements, theme)

### Description
A hook to edit elements after they've been calculated. Can be overridden for more complicated theme handling or to intervene in inheritance.

### Arguments

* `params` (list) - A list of parameters initiated by the `params` field.
* `elements` (named list) - A named list of strings initiated by the `elements` field.
* `theme` (theme) - A complete theme.

### Value
A list of elements or resolved theme settings.
```

--------------------------------

### Binned Guide with Limits Shown

Source: https://ggplot2.tidyverse.org/reference/guide_bins.html

Illustrates how to explicitly show the scale limits on a binned guide by setting show.limits = TRUE.

```R
p + guides(size = guide_bins(show.limits = TRUE))
```

--------------------------------

### Assign a single guide object to multiple aesthetics

Source: https://ggplot2.tidyverse.org/reference/guides.html

An alternative method to apply the same guide configuration to multiple aesthetics by creating a guide object first and then assigning it.

```R
g <- guide_legend("title")
p + guides(colour = g, size = g, shape = g)
```

--------------------------------

### Basic Colourbar Guide

Source: https://ggplot2.tidyverse.org/reference/guide_colourbar.html

Demonstrates the basic usage of `scale_fill_continuous` with `guide = "colourbar"` and `guide_colourbar()` to display a colourbar.

```R
df <- expand.grid(X1 = 1:10, X2 = 1:10)
df$value <- df$X1 * df$X2

p1 <- ggplot(df, aes(X1, X2)) + geom_tile(aes(fill = value))
p2 <- p1 + geom_point(aes(size = value))

# Basic form
p1 + scale_fill_continuous(guide = "colourbar")

p1 + scale_fill_continuous(guide = guide_colourbar())

p1 + guides(fill = guide_colourbar())
```

--------------------------------

### Specify guides using scale functions

Source: https://ggplot2.tidyverse.org/reference/guides.html

Illustrates setting guides directly within the scale functions (e.g., `scale_colour_continuous()`, `scale_size_discrete()`) for each aesthetic.

```R
p +
 scale_colour_continuous(guide = "colorbar") +
 scale_size_discrete(guide = "legend") +
 scale_shape(guide = "legend")
```

--------------------------------

### Guide Constructor Usage

Source: https://ggplot2.tidyverse.org/reference/new_guide.html

Use this function to construct a new guide in ggplot2. Ensure that any named arguments provided match the parameters of the superclass or theme elements. The available_aes argument specifies the aesthetics the guide can handle.

```r
new_guide(..., available_aes = "any", super)
```

--------------------------------

### Guide Draw Method

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Orchestrates the drawing of a guide, setting up context and rendering components like titles, ticks, and labels. Override for non-standard components or simplification.

```r
Geom$setup_params(theme, position, direction, params)
```

--------------------------------

### Old Guide System Generics

Source: https://ggplot2.tidyverse.org/reference/old_guide.html

These functions are generics from the previous S3 guide system, now encapsulated within the GuideOld ggproto class as a fallback.

```r
guide_train(guide, scale, aesthetic = NULL)

guide_merge(guide, new_guide)

guide_geom(guide, layers, default_mapping = NULL)

guide_transform(guide, coord, panel_params)

guide_gengrob(guide, theme)

old_guide(guide)
```

--------------------------------

### Basic Faceting Example

Source: https://ggplot2.tidyverse.org/reference/as_labeller.html

This is a basic example demonstrating how to create a ggplot and apply faceting. It serves as a base for subsequent label modification examples.

```r
p <- ggplot(mtcars, aes(disp, drat)) + geom_point()
p + facet_wrap(~am)
```

--------------------------------

### Extending the Guide Class

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Defines a new guide class 'GuideDescribe' by extending the base 'Guide' class. This includes custom methods for building titles, labels, measuring grobs, and assembling the drawing. Use this when you need a specialized guide appearance or behavior.

```R
__```
# 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"))


```
```

--------------------------------

### guide_none

Source: https://ggplot2.tidyverse.org/reference/guide_none.html

This function creates a guide that draws nothing. It's useful for explicitly suppressing guides.

```APIDOC
## guide_none

### Description

This guide draws nothing. It is used to explicitly suppress the display of guides for a specific aesthetic.

### Usage

```
guide_none(title = waiver(), position = waiver())
```

### Arguments

*   **title** (character string or expression) - A title for the guide. If `NULL`, the title is not shown. By default (`waiver()`), the name of the scale object or the name specified in `labs()` is used.
*   **position** (character string) - Where this guide should be drawn. Accepts one of "top", "bottom", "left", or "right".
```

--------------------------------

### Define a guide that draws nothing

Source: https://ggplot2.tidyverse.org/reference/guide_none.html

Use guide_none() to create a guide object that renders no visual elements. This is useful for suppressing default guides when you don't want any axis or legend.

```r
guide_none(title = waiver(), position = waiver())
```

--------------------------------

### Guide$build_title

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Method for rendering the title of a guide. Can be overridden to customize title rendering or margin settings.

```APIDOC
## Guide$build_title(label, elements, params)

### Description
A function method for rendering the title. Note that titles for position guides are rendered by the Facet class and not this method. Can be overridden if you need to render more than one title (or none) or adjust margin settings.

### Arguments

* `label` (string or expression) - A single string or expression with the title text.
* `elements` (list) - A 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.
* `params` (list) - A list of parameters initiated by the `params` field.

### Value
A grob representing the title.
```

--------------------------------

### Remove multiple guides

Source: https://ggplot2.tidyverse.org/reference/guides.html

Shows how to remove guides for multiple aesthetics simultaneously, in this case, colour and size.

```R
p + guides(colour = "colorbar",size = "none")
```

--------------------------------

### Guide Constructor for Custom Key

Source: https://ggplot2.tidyverse.org/articles/extending-ggplot2.html

Create a constructor function for the custom GuideKey class. This function prepares the key data frame and instantiates the guide, ensuring all necessary parameters are declared.

```r
guide_key <- function(
  aesthetic, value = aesthetic, label = as.character(aesthetic),
  ...,
  # Standard guide arguments
  theme = NULL, title = waiver(), order = 0, position = waiver()
) {
  
  key <- data.frame(aesthetic, .value = value, .label = label, ...)
  
  new_guide(
    # Arguments passed on to the GuideKey$params field
    key = key, theme = theme, title = title, order = order, position = position,
    # Declare which aesthetics are supported
    available_aes = c("x", "y"),
    # Set the guide class
    super = GuideKey
  )
}
```

--------------------------------

### Binned Guide with Custom Axis Arrow

Source: https://ggplot2.tidyverse.org/reference/guide_bins.html

Demonstrates styling the axis line of a binned guide with custom arrows using theme overrides.

```R
my_arrow <- arrow(length = unit(1.5, "mm"), ends = "both")
p + guides(size = guide_bins(
  theme = theme(legend.axis.line = element_line(arrow = my_arrow))
))
```

--------------------------------

### Coord$setup_panel_guides

Source: https://ggplot2.tidyverse.org/reference/Coord.html

Method to initiate position guides for each panel.

```APIDOC
## Coord$setup_panel_guides

### Description
This function method is used to initiate position guides for each panel. For efficiency reasons, this method is called once per combination of `x` and `y` scales. For the primary and secondary positions, it should resolve guides coming from the `plot$guides` field and `Scale$guide` fields and set appropriate `Guide$params$position` parameters.

### Usage
__```
Coord$setup_panel_guides(panel_params, guides, params)
```

### Arguments

`panel_params`
    
A list of ViewScale class objects and additional parameters from the `setup_panel_params()` method.

`guides`
    
A `<Guides>` ggproto class.

`params`
    
A list of parameters coming from the `setup_params()` method.

### Value
The `panel_params` object but with a Guides class object appended with the name 'guides'.
```

--------------------------------

### get_guide_data()

Source: https://ggplot2.tidyverse.org/reference/get_guide_data.html

Builds a plot and extracts information from guide keys. This information typically contains positions, values and/or labels, depending on which aesthetic is queried or guide is used.

```APIDOC
## get_guide_data()

### Description
Builds a plot and extracts information from guide keys. This information typically contains positions, values and/or labels, depending on which aesthetic is queried or guide is used.

### Usage
```R
get_guide_data(plot = get_last_plot(), aesthetic, panel = 1L)
```

### Arguments

*   **plot** (ggplot or ggplot_build object) - A ggplot or ggplot_build object.
*   **aesthetic** (string) - A string that describes a single aesthetic for which to extract guide information. For example: "colour", "size", "x" or "y.sec".
*   **panel** (integer) - An integer giving a panel number for which to return position guide information.

### Value
One of the following:
  * A `data.frame` representing the guide key, when the guide is unique for the aesthetic.
  * A `list` when the coord does not support position axes or multiple guides match the aesthetic.
  * `NULL` when no guide key could be found.

### Examples
```R
# A standard plot
p <- ggplot(mtcars) + 
  aes(mpg, disp, colour = drat, size = drat) + 
  geom_point() + 
  facet_wrap(vars(cyl), scales = "free_x")

# Guide information for legends
get_guide_data(p, "size")

# Note that legend guides can be merged
merged <- p + guides(colour = "legend")
get_guide_data(merged, "size")

# Guide information for positions
get_guide_data(p, "x", panel = 2)

# Coord polar doesn't support proper guides, so we get a list
polar <- p + coord_polar()
get_guide_data(polar, "theta", panel = 2)
```
```

--------------------------------

### Get Guide Data

Source: https://ggplot2.tidyverse.org/articles/extending-ggplot2.html

Retrieves the key data used by a guide for a specific aesthetic. This is useful for understanding how scales translate aesthetic information into visual elements and labels for guides.

```r
p <- ggplot(mpg, aes(displ, hwy, colour = drv)) +
  geom_point() +
  scale_colour_discrete(
    labels = c("4-wheel drive", "front wheel drive", "rear wheel drive")
  )

get_guide_data(p, "colour")

```

--------------------------------

### Layout$setup_panel_guides

Source: https://ggplot2.tidyverse.org/reference/Layout.html

Sets up and trains position guides (axes) per panel, calling Coord$setup_panel_guides() and Coord$train_panel_guides().

```APIDOC
## Layout$setup_panel_guides

### Description
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

`guides`
    
A `<Guides>` ggproto object from the `guides` field of the ggplot object. 

`layers`
    
A 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.
```

--------------------------------

### Specify guides using string shortcuts

Source: https://ggplot2.tidyverse.org/reference/guides.html

Demonstrates how to assign guides to specific aesthetics (colour, size, shape) using simple string shortcuts like "colorbar" and "legend".

```R
p + guides(colour = "colorbar", size = "legend", shape = "legend")
```

--------------------------------

### Merged Binned Guides Example

Source: https://ggplot2.tidyverse.org/reference/guide_bins.html

Shows how ggplot2 automatically merges binned guides when multiple aesthetics (size and colour) are mapped to binned scales in the same way.

```R
ggplot(mtcars) +
  geom_point(aes(disp, mpg, size = hp, colour = hp)) +
  scale_size_binned() +
  scale_colour_binned(guide = "bins")
```

--------------------------------

### Layout$setup

Source: https://ggplot2.tidyverse.org/reference/Layout.html

Sets up layout information by populating facet and coordinate parameters, and adding a PANEL variable to layer data.

```APIDOC
## Layout$setup

### Description
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

`data`
    
A list of data frames with layer data. 

`plot_data`
    
The data frame in the `data` field of the ggplot object. 

`plot_env`
    
The 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.
```

--------------------------------

### Create a ggplot with multiple aesthetics and facets

Source: https://ggplot2.tidyverse.org/reference/get_guide_data.html

This code sets up a base ggplot object with mapped aesthetics for size and color, and applies faceting. It serves as a starting point for extracting guide data.

```r
p <- ggplot(mtcars) +
  aes(mpg, disp, colour = drat, size = drat) +
  geom_point() +
  facet_wrap(vars(cyl), scales = "free_x")
```

--------------------------------

### Create and Plot US State Map Data

Source: https://ggplot2.tidyverse.org/reference/map_data.html

This example demonstrates how to load US state map data using `map_data()`, merge it with arrest data, and create a choropleth map. Ensure the 'maps' package is installed and loaded.

```r
if (require("maps")) {
states <- map_data("state")
arrests <- USArrests
names(arrests) <- tolower(names(arrests))
arrests$region <- tolower(rownames(USArrests))

choro <- merge(states, arrests, sort = FALSE, by = "region")
choro <- choro[order(choro$order), ]
ggplot(choro, aes(long, lat)) +
  geom_polygon(aes(group = group, fill = assault)) +
  coord_map("albers",  lat0 = 45.5, lat1 = 29.5)
}
```

--------------------------------

### Guide$build_decor

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Method for rendering decor components. Serves as a wildcard for drawing guide-specific components not covered by other build methods.

```APIDOC
## Guide$build_decor(decor, grobs, elements, params)

### Description
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.

### Arguments

* `decor` (data frame or other structure) - A data frame (or other structure) with information derived from the `extract_decor()` method.
* `grobs` (list) - A list with grobs generated by the other `build_*` methods.
* `elements` (list) - A 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>`.
* `params` (list) - A list of parameters initiated by the `params` field.

### Value
A grob.
```

--------------------------------

### Remove a guide

Source: https://ggplot2.tidyverse.org/reference/guides.html

Demonstrates how to completely remove a guide for a specific aesthetic by setting its guide to "none".

```R
p + guides(colour = "none")
```

--------------------------------

### Layout Setup Panel Params Method

Source: https://ggplot2.tidyverse.org/reference/Layout.html

Executes Coord$setup_panel_params() once per panel with appropriate scales for efficiency.

```r
Layout$setup_panel_params()
```

--------------------------------

### Placeholder for Scale Example

Source: https://ggplot2.tidyverse.org/reference/Scale.html

This is a placeholder for a code example demonstrating ggplot2 scale functionality. The actual example is yet to be determined.

```r
# TODO: find easy to digest example
NULL
#> NULL
```

--------------------------------

### Facet Setup Panel Parameters

Source: https://ggplot2.tidyverse.org/reference/Facet.html

Use `setup_panel_params` as a hook to provide facets with input over panel parameters. The default implementation returns panel parameters without modification.

```r
Facet$setup_panel_params(panel_params, coord, ...)
```

--------------------------------

### Install ggplot2 Package

Source: https://ggplot2.tidyverse.org/index.html

Installs the ggplot2 package. It is recommended to install the entire tidyverse for a comprehensive set of data science tools.

```r
install.packages("tidyverse")
```

```r
install.packages("ggplot2")
```

```r
# Or the development version from GitHub:
# install.packages("pak")
pak::pak("tidyverse/ggplot2")
```

--------------------------------

### Guide Merge Method

Source: https://ggplot2.tidyverse.org/reference/Guide.html

Merges information from two guides when they share the same computed hash. This is useful for combining guides trained on different scales.

```r
Guide$merge(params, new_guide, new_params)
```

--------------------------------

### Facet Setup Data

Source: https://ggplot2.tidyverse.org/reference/Facet.html

Use `setup_data` to modify or check data before defaults are added. The default method returns the data unchanged.

```r
Facet$setup_data(data, params)
```

--------------------------------

### Facet Setup Parameters

Source: https://ggplot2.tidyverse.org/reference/Facet.html

Use `setup_params` to modify or check parameters based on the data. The default method provides a `.possible_columns` variable with column names.

```r
Facet$setup_params(data, params)
```

--------------------------------

### GeomLine setup_params method

Source: https://ggplot2.tidyverse.org/articles/extending-ggplot2.html

Shows the setup_params method for GeomLine, which handles ambiguous layers by using has_flipped_aes with ambiguous = TRUE. This is for geoms where orientation is not data-driven.

```R
GeomLine$setup_params
```

```R
function (data, params) {
    params$flipped_aes <- has_flipped_aes(data, params, ambiguous = TRUE)
    params
}
```

--------------------------------

### Identity Scale with Legend Guide

Source: https://ggplot2.tidyverse.org/reference/scale_identity.html

Shows how to configure scale_fill_identity() to display a legend guide. This requires specifying 'guide = "legend"' and typically also providing 'breaks' and 'labels' for the legend.

```R
ggplot(df, aes(x, y)) +
  geom_tile(aes(fill = colour)) +
  scale_fill_identity(guide = "legend")

# But you'll typically also need to supply breaks and labels:
ggplot(df, aes(x, y)) +
  geom_tile(aes(fill = colour)) +
  scale_fill_identity("trt", labels = letters[1:4], breaks = df$colour,
  guide = "legend")
```

--------------------------------

### Check if an object is guides

Source: https://ggplot2.tidyverse.org/reference/is_tests.html

Use `is_guides()` to check if an object represents a collection of guides.

```R
is_guides(x)
```

--------------------------------

### stat_unique Examples

Source: https://ggplot2.tidyverse.org/reference/stat_unique.html

Provides examples of how to use stat_unique in ggplot2, demonstrating its application with geom_point.

```APIDOC
## Examples
__```
ggplot(mtcars, aes(vs, am)) +
  geom_point(alpha = 0.1)

ggplot(mtcars, aes(vs, am)) +
  geom_point(alpha = 0.1, stat = "unique")


```
```

--------------------------------

### Guide transform method signature

Source: https://ggplot2.tidyverse.org/reference/Guide.html

The `transform` method applies coordinate transformations and munching to the 'key' and 'decor' parameters. This method is primarily for position guides and may need overriding for custom guide structures.

```r
Guide$transform(params, coord, ...)
```

--------------------------------

### Layout Setup Method

Source: https://ggplot2.tidyverse.org/reference/Layout.html

Sets up layout information for the plot, populating parameters and adding a PANEL variable to layer data.

```r
Layout$setup(data, plot_data, plot_env)
```

--------------------------------

### ggproto Basic Example

Source: https://ggplot2.tidyverse.org/articles/extending-ggplot2.html

Demonstrates the basic usage of ggproto by defining a simple object 'A' with a mutable state 'x' and an incrementing method 'inc'. Shows how to access and modify the state.

```R
A <- ggproto("A", NULL,
  x = 1,
  inc = function(self) {
    self$x <- self$x + 1
  }
)
A$x
```

```R
A$inc()
A$x
```

```R
A$inc()
A$inc()
A$x
```

--------------------------------

### Check if an object is a guide

Source: https://ggplot2.tidyverse.org/reference/is_tests.html

Use `is_guide()` to determine if an object is a guide (e.g., legend or color bar).

```R
is_guide(x)
```

--------------------------------

### Creating Dummy Layout Components

Source: https://ggplot2.tidyverse.org/reference/Layout.html

Demonstrates the creation of dummy facet and coord components, which can then be used to construct a custom Layout object.

```r
# Some dummy layout components
facet <- facet_null()
coord <- coord_cartesian()

# Use in custom `ggplot_build()` methods
layout <- ggproto(NULL, Layout, facet = facet, coord = coord)

```

--------------------------------

### Layout$setup_panel_params

Source: https://ggplot2.tidyverse.org/reference/Layout.html

Executes Coord$setup_panel_params() for each panel with appropriate scales to populate the panel_params field.

```APIDOC
## Layout$setup_panel_params

### Description
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.
```

--------------------------------

### Independent Guide Control

Source: https://ggplot2.tidyverse.org/reference/guide_colourbar.html

Shows how to control different aesthetic guides (colourbar and legend) independently for a plot.

```R
p2 +
  scale_fill_continuous(guide = "colourbar") +
  scale_size(guide = "legend")

p2 + guides(fill = "colourbar", size = "legend")
```

--------------------------------

### Coordinate System Panel Parameters Setup

Source: https://ggplot2.tidyverse.org/reference/Coord.html

This method sets up panel parameters per panel for efficiency. It is called once per combination of x and y scales to instantiate ViewScale objects and ranges, and optionally append parameters for the transform method and rendering axes.

```r
Coord$setup_panel_params(scale_x, scale_y, params)
```

--------------------------------

### Basic Geom Point Example

Source: https://ggplot2.tidyverse.org/reference/geom_point.html

A basic example of using geom_point() to create a scatterplot with default settings.

```APIDOC
## Examples
__```
p <- ggplot(mtcars, aes(wt, mpg))
p + geom_point()
```__
```

--------------------------------

### Binned Guide with Axis Removed

Source: https://ggplot2.tidyverse.org/reference/guide_bins.html

Shows how to remove the axis line from a binned guide by applying a theme override.

```R
p + guides(size = guide_bins(
  theme = theme(legend.axis.line = element_blank())
))
```

--------------------------------

### Stat setup_data Method

Source: https://ggplot2.tidyverse.org/reference/Stat.html

This method is used for modifying or checking the data. The default method returns data unaltered.

```R
Stat$setup_data(data, params)
```

--------------------------------

### Get Zero-Column Frame Prototype

Source: https://ggplot2.tidyverse.org/articles/profiling.html

Experimental generic to get a zero-column data frame prototype, used by vec_cbind().

```R
vec_cbind_frame_ptype <- function(x, ...) {
  UseMethod("vec_cbind_frame_ptype")
}
```

--------------------------------

### scale_colour_manual() Example

Source: https://ggplot2.tidyverse.org/reference/scale_manual.html

Demonstrates how to use scale_colour_manual() to manually set colors for a plot. It shows basic usage with a vector of colors and a named vector for specific mappings.

```APIDOC
## scale_colour_manual()

### Description
Manually specify the colors used for a color aesthetic.

### Method
Not applicable (this is an R function call).

### Parameters
#### Aesthetics
- **colour**: The aesthetic to map to.
- **fill**: The aesthetic to map to.

#### Values
- **values** (character vector or named character vector) - A vector of colors to use. If named, the names should match the levels of the factor being mapped.

#### Optional Parameters
- **aesthetics** (character vector) - Specifies which aesthetics this scale should affect. Defaults to 'colour'. Can be used to set both 'colour' and 'fill' simultaneously.
- **breaks** (character vector) - Specifies the breaks to appear in the legend.
- **labels** (character vector) - Specifies the labels for the breaks in the legend.
- **limits** (character vector) - Specifies the limits of the scale.

### Request Example
```R
p <- ggplot(mtcars, aes(mpg, wt)) + geom_point(aes(colour = factor(cyl)))
p + scale_colour_manual(values = c("red", "blue", "green"))

# Using a named vector for specific mappings
cols <- c("8" = "red", "4" = "blue", "6" = "darkgreen", "10" = "orange")
p + scale_colour_manual(values = cols)

# Setting color and fill aesthetics at the same time
ggplot(
  mtcars,
  aes(mpg, wt, colour = factor(cyl), fill = factor(cyl))
) + 
  geom_point(shape = 21, alpha = 0.5, size = 2) + 
  scale_colour_manual(
    values = cols,
    aesthetics = c("colour", "fill")
  )

# Controlling legend appearance with breaks and labels
p + scale_colour_manual(
  values = cols,
  breaks = c("4", "6", "8"),
  labels = c("four", "six", "eight")
)

# Controlling the possible values of the scale with limits
p + scale_colour_manual(values = cols, limits = c("4", "8"))
```

### Response
#### Success Response (200)
Not applicable (this is an R function call).

#### Response Example
Not applicable (this is an R function call).
```

--------------------------------

### Example Usage with geom_tile

Source: https://ggplot2.tidyverse.org/reference/guide_coloursteps.html

Demonstrates how to use guide_coloursteps with a ggplot object that uses geom_tile and a fill aesthetic mapped to a continuous variable.

```R
df <- expand.grid(X1 = 1:10, X2 = 1:10)
df$value <- df$X1 * df$X2

p <- ggplot(df, aes(X1, X2)) + geom_tile(aes(fill = value))
```

--------------------------------

### GeomBoxplot setup_data method

Source: https://ggplot2.tidyverse.org/articles/extending-ggplot2.html

Illustrates the setup_data method for GeomBoxplot, including data flipping and width computation. This is useful when a geom is used with a stat that doesn't handle orientation.

```R
GeomBoxplot$setup_data
```

```R
function (self, data, params) {
    data$flipped_aes <- params$flipped_aes
    data <- flip_data(data, params$flipped_aes)
    data <- compute_data_size(data, params$width, default = self$default_aes$width,
        zero = FALSE, discrete = TRUE)
    if (isFALSE(params$outliers)) {
        data$outliers <- NULL
    }
    if (!is.null(data$outliers)) {
        suppressWarnings({
            out_min <- vapply(data$outliers, min, numeric(1))
            out_max <- vapply(data$outliers, max, numeric(1))
        })
        data$ymin_final <- pmin(out_min, data$ymin)
        data$ymax_final <- pmax(out_max, data$ymax)
    }
    if (is.null(params) || is.null(params$varwidth) || !params$varwidth ||
        is.null(data$relvarwidth)) {
        data$xmin <- data$x - data$width/2
        data$xmax <- data$x + data$width/2
    }
    else {
        data$relvarwidth <- data$relvarwidth/max(data$relvarwidth)
        data$xmin <- data$x - data$relvarwidth * data$width/2
        data$xmax <- data$x + data$relvarwidth * data$width/2
    }
    data$width <- NULL
    if (!is.null(data$relvarwidth))
        data$relvarwidth <- NULL
    flip_data(data, params$flipped_aes)
}
```

--------------------------------

### Generate Scale Title

Source: https://ggplot2.tidyverse.org/reference/Scale.html

Determines the appropriate title for a guide or axis, prioritizing guide titles over scale names and labels.

```r
Scale$make_title(guide_title, scale_title, label_title)
```

--------------------------------

### Basic Faceting with facet_grid()

Source: https://ggplot2.tidyverse.org/reference/facet_grid.html

Demonstrates basic faceting by rows, columns, or both using variables supplied via vars().

```r
p <- ggplot(mpg, aes(displ, cty)) + geom_point()

# Use vars() to supply variables from the dataset:
p + facet_grid(rows = vars(drv))

p + facet_grid(cols = vars(cyl))

p + facet_grid(vars(drv), vars(cyl))
```

--------------------------------

### Get default aesthetics for a geom by class object

Source: https://ggplot2.tidyverse.org/reference/get_geom_defaults.html

Demonstrates how to get default aesthetics for a geom by passing its class object.

```r
get_geom_defaults(GeomPoint)
```

--------------------------------

### Displaying Limits in Binned Colour Scale Guide

Source: https://ggplot2.tidyverse.org/reference/guide_coloursteps.html

Configures the binned colour scale guide to explicitly show the limits of the scale.

```r
p + scale_fill_binned(guide = guide_coloursteps(show.limits = TRUE))
```

--------------------------------

### guide_bins() Function Signature

Source: https://ggplot2.tidyverse.org/reference/guide_bins.html

This is the function signature for guide_bins(). It outlines the available arguments for customizing binned guides.

```R
guide_bins(
  title = waiver(),
  theme = NULL,
  angle = NULL,
  position = NULL,
  direction = NULL,
  override.aes = list(),
  reverse = FALSE,
  order = 0,
  show.limits = NULL,
  ...
)
```

--------------------------------

### new_guide Constructor

Source: https://ggplot2.tidyverse.org/reference/new_guide.html

Constructs a new guide object in ggplot2, ensuring compatibility between the guide and provided arguments. It accepts named arguments for parameters and theme elements, a list of available aesthetics, and a super class object.

```APIDOC
## Function: new_guide

### Description
A constructor function for guides, which performs some standard compatibility checks between the guide and provided arguments.

### Usage
```R
new_guide(..., available_aes = "any", super)
```

### Arguments

* `...`: Named arguments that match the parameters of `super$params` or the theme elements in `super$elements`.
* `available_aes` (character vector): A vector of character strings listing the aesthetics for which the guide can be drawn. Defaults to "any".
* `super` (Guide class object): The super class to use for the constructed guide. Should be a Guide class object.

### Value
A `Guide` ggproto object.
```
Tokens:
Raw