DOCSEARCHbyAlgolia
Submit Docs

scales

repository·main·Indexed 19 days ago

https://github.com/r-lib/scales

Provides the scaling infrastructure used by ggplot2 to convert data values to perceptual properties and create guides such as legends and axes. It includes functions for controlling axis and legend breaks and labels, color palette generation via pal_viridis() and pal_brewer(), and tools for creating custom transformations using new_transform().

Tokens
1.1K
Snippets
4
Records
4
Agent score
16%

What's inside scales

  1. Install the scales package

    main

    The scales package is automatically installed as a dependency of ggplot2 or the tidyverse. You can install it standalone from CRAN, or install the development version from GitHub using pak.

    # Install from CRAN
install.packages("scales")

# Install development version from GitHub
install.packages("pak")
pak::pak("r-lib/scales")

  2. Control axis and legend breaks and labels

    main

    The most common use of scales is to customize the appearance of axes and legends in ggplot2.

    • Use break_ functions (e.g., breaks_width(), breaks_extended()) to control how breaks are generated from the data limits.
    • Use label_ functions (e.g., label_date(), label_number(), label_dollar()) to control how those breaks are formatted into human-readable labels.

    Note: It is often recommended to use the scales:: prefix rather than calling library(scales) to leverage autocomplete for the various label_ and break_ functions.

    library(ggplot2)
library(dplyr)
library(lubridate)

# Example: Customizing date breaks and number labels
txhousing %>%
  mutate(date = make_date(year, month, 1)) %>%
  group_by(city) %>%
  filter(min(sales) > 5e2) %>%
  ggplot(aes(date, sales, group = city)) +
  geom_line(na.rm = TRUE) +
  scale_x_date(
    NULL,
    breaks = scales::breaks_width("2 years"),
    labels = scales::label_date("'%y")
  ) +
  scale_y_log10(
    "Total sales",
    labels = scales::label_number(scale_cut = scales::cut_short_scale())
  )

  3. Use scales color palettes in other plotting systems

    main

    While scales powers ggplot2 color scales, you can use its palette functions in any plotting system (like base R).

    • Use pal_viridis() or pal_brewer() to generate a function that returns a list of colors.
    • Call the resulting function with a numeric argument to get the specific colors.
    • You can pass these colors to base R functions like palette() or directly to the col argument in plot().
    library(scales)

# Pull a list of colours from any palette
pal_viridis()(4)
#> [1] "#440154FF" "#31688EFF" "#35B779FF" "#FDE725FF"

# Use in combination with baseR `palette()` to set new defaults
palette(pal_brewer(palette = "Set2")(4))
par(mar = c(5, 5, 1, 1))
plot(Sepal.Length ~ Sepal.Width, data = iris, col = Species, pch = 20)

  4. Create custom transformations with new_transform()

    main

    You can define and apply custom transformation functions for repeated use by using new_transform(). This allows you to bundle a transformation function, its inverse, a name, and a break generation strategy into a single object that can be passed to ggplot2 scales (e.g., via the trans argument).

    # use new_transform to build a new transformation
transform_logp3 <- new_transform(
  name = "logp",
  transform = function(x) log(x + 3),
  inverse = function(x) exp(x) - 3,
  breaks = log_breaks()
)

set.seed(1234)
dsamp <- sample_n(diamonds, 100)

ggplot(dsamp, aes(carat, price, colour = color)) +
  geom_point() +
  scale_y_continuous(trans = transform_logp3)