Package: scales 1.3.0.9000

Thomas Lin Pedersen

scales: Scale Functions for Visualization

Graphical scales map data to aesthetics, and provide methods for automatically determining breaks and labels for axes and legends.

Authors:Hadley Wickham [aut], Thomas Lin Pedersen [cre, aut], Dana Seidel [aut], Posit, PBC [cph, fnd]

scales_1.3.0.9000.tar.gz
scales_1.3.0.9000.zip(r-4.5)scales_1.3.0.9000.zip(r-4.4)scales_1.3.0.9000.zip(r-4.3)
scales_1.3.0.9000.tgz(r-4.5-any)scales_1.3.0.9000.tgz(r-4.4-any)scales_1.3.0.9000.tgz(r-4.3-any)
scales_1.3.0.9000.tar.gz(r-4.5-noble)scales_1.3.0.9000.tar.gz(r-4.4-noble)
scales_1.3.0.9000.tgz(r-4.4-emscripten)scales_1.3.0.9000.tgz(r-4.3-emscripten)
scales.pdf |scales.html
scales/json (API)
NEWS

# Install 'scales' in R:
install.packages('scales', repos = c('https://r-lib.r-universe.dev', 'https://cloud.r-project.org'))

Bug tracker:https://github.com/r-lib/scales/issues

Pkgdown site:https://scales.r-lib.org

On CRAN:scales-1.3.0(2023-11-28)

ggplot2

19.80 score 413 stars 7.9k packages 88k scripts 921k downloads 104 mentions 217 exports 9 dependencies

Last updated 4 months agofrom:ee03582857. Checks:8 OK. Indexed: yes.

TargetResultLatest binary
Doc / VignettesOKJan 29 2025
R-4.5-winOKFeb 19 2025
R-4.5-macOKJan 29 2025
R-4.5-linuxOKJan 29 2025
R-4.4-winOKJan 29 2025
R-4.4-macOKJan 29 2025
R-4.3-winOKJan 29 2025
R-4.3-macOKJan 29 2025

Exports:abs_areaalphaarea_palas_continuous_palas_discrete_palas.transas.transformasinh_transasn_transatanh_transboxcox_transbreaks_expbreaks_extendedbreaks_logbreaks_prettybreaks_timespanbreaks_widthbrewer_palcbreakscensorcol_bincol_darkercol_factorcol_lightercol_mixcol_numericcol_quantilecol_saturatecol_shiftcol2hclcolour_rampcommacomma_formatcompose_labelcompose_transContinuousRangecscalecut_long_scalecut_short_scalecut_sicut_time_scaledate_breaksdate_formatdate_transdemo_continuousdemo_datetimedemo_discretedemo_log10demo_timedemo_timespandichromat_paldiscardDiscreteRangediv_gradient_paldollardollar_formatdscaleexp_transexpand_rangeextended_breaksformat_formatformat_logfullseqget_palettegradient_n_palgrey_palhms_transhue_palidentity_palidentity_transis_colour_palis_continuous_palis_discrete_palis_numeric_palis_palis.transis.transformlabel_byteslabel_commalabel_currencylabel_datelabel_date_shortlabel_dictionarylabel_dollarlabel_gluelabel_loglabel_mathlabel_numberlabel_number_autolabel_number_silabel_ordinallabel_parselabel_percentlabel_pvaluelabel_scientificlabel_timelabel_timespanlabel_wraplinetype_pallog_breakslog_translog10_translog1p_translog2_translogit_transmanual_palmath_formatminor_breaks_logminor_breaks_nminor_breaks_widthmodulus_transmutednew_continuous_palettenew_discrete_palettenew_transformnumbernumber_bytesnumber_bytes_formatnumber_formatnumber_optionsoob_censoroob_censor_anyoob_discardoob_keepoob_squishoob_squish_anyoob_squish_infiniteordinalordinal_englishordinal_formatordinal_frenchordinal_spanishpal_areapal_brewerpal_dichromatpal_div_gradientpal_gradient_npal_greypal_huepal_identitypal_linetypepal_manualpal_rescalepal_seq_gradientpal_shapepal_viridispalette_na_safepalette_namespalette_nlevelspalette_typeparse_formatpercentpercent_formatpretty_breaksprobability_transprobit_transpseudo_log_transpvaluepvalue_formatRangereciprocal_transregular_minor_breaksrescalerescale_maxrescale_midrescale_nonerescale_palreset_palettesreverse_transscientificscientific_formatseq_gradient_palset_paletteshape_palshow_colsqrt_transsquishsquish_infinitetime_formattime_transtimespan_transtrain_continuoustrain_discretetrans_breakstrans_formattrans_newtrans_rangetransform_asinhtransform_asntransform_atanhtransform_boxcoxtransform_composetransform_datetransform_exptransform_hmstransform_identitytransform_logtransform_log10transform_log1ptransform_log2transform_logittransform_modulustransform_probabilitytransform_probittransform_pseudo_logtransform_reciprocaltransform_reversetransform_sqrttransform_timetransform_timespantransform_yjtrim_to_domainunit_formatviridis_palwrap_formatyj_transzero_range

Dependencies:clifarvergluelabelinglifecycleR6RColorBrewerrlangviridisLite

Citation

To cite package ‘scales’ in publications use:

Wickham H, Pedersen T, Seidel D (2025). scales: Scale Functions for Visualization. R package version 1.3.0.9000, , https://github.com/r-lib/scales.

Corresponding BibTeX entry:

  @Manual{,
    title = {scales: Scale Functions for Visualization},
    author = {Hadley Wickham and Thomas Lin Pedersen and Dana Seidel},
    year = {2025},
    note = {R package version 1.3.0.9000, },
    url = {https://github.com/r-lib/scales},
  }

Readme and manuals

scales scales website

One of the most difficult parts of any graphics package is scaling, converting from data values to perceptual properties. The inverse of scaling, making guides (legends and axes) that can be used to read the graph, is often even harder! The scales packages provides the internal scaling infrastructure used by ggplot2, and gives you tools to override the default breaks, labels, transformations and palettes.

Installation

# Scales is installed when you install ggplot2 or the tidyverse.
# But you can install just scales from CRAN:
install.packages("scales")

# Or the development version from Github:
# install.packages("pak")
# pak::pak("r-lib/scales")
install.packages("scales", repos = c('https://r-lib.r-universe.dev', 'https://cloud.r-project.org'))

Usage

Breaks and labels

The most common use of the scales package is to control the appearance of axis and legend labels. Use a break_ function to control how breaks are generated from the limits, and a label_ function to control how breaks are turned in to labels.

library(ggplot2)
library(dplyr, warn.conflicts = FALSE)
library(lubridate, warn.conflicts = FALSE)

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())
  )
A line plot created with ggplot2, showing property sales in Texas. The x scale uses `scales::break_width()` to place breaks every second year, and `scales::label_date()` to create a custom format for the labels. The y-scale uses `scales::label_number()` to reformat the labels with `scales::cut_short_scale()`.
economics %>%
  filter(date < ymd("1970-01-01")) %>%
  ggplot(aes(date, pce)) +
  geom_line() +
  scale_x_date(NULL,
    breaks = scales::breaks_width("3 months"),
    labels = scales::label_date_short()
  ) +
  scale_y_continuous("Personal consumption expenditures",
    breaks = scales::breaks_extended(8),
    labels = scales::label_dollar()
  )
A line plot created with ggplot2, showing personal expenses between 1967 and 1970. The x axis uses `scales::break_width()` to put a break every 3 months and `scales::label_date_short()` to only show the year on the first occuring break of that year. The y axis uses `scales::breaks_extended()` to request 8 breaks, though only 6 are ultimately provided, and `scales::label_dollar()` to format the label as a dollar value.

Generally, I don’t recommend running library(scales) because when you type (e.g.) scales::label_ autocomplete will provide you with a list of labelling functions to jog your memory.

Advanced features

Scales colour palettes are used to power the scales in ggplot2, but you can use them in any plotting system. The following example shows how you might apply them to a base plot.

#|   sepal length and sepal width in the Iris dataset. The points are coloured
#|   according to species and the `scales::pal_brewer()` are used to provide the
#|   colours.
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)
A scatterplot created with base plot showing the relationship between

scales also gives users the ability to define and apply their own custom transformation functions for repeated use.

# 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()
)

dsamp <- sample_n(diamonds, 100)
ggplot(dsamp, aes(carat, price, colour = color)) +
  geom_point() +
  scale_y_continuous(trans = transform_logp3)
A scatterplot created with ggplot2 showing the relationship between diamond price and its carat for a subset of the data in the diamonds dataset. The y scale uses a custom log transform created with `scales::new_transform()`.

Help Manual

Help pageTopics
Modify colour transparencyalpha
Breaks for exponentially transformed databreaks_exp
Automatic breaks for numeric axesbreaks_extended extended_breaks
Breaks for log axesbreaks_log log_breaks
Pretty breaks for date/timesbreaks_pretty
Breaks for timespan databreaks_timespan
Equally spaced breaksbreaks_width
Mix colourscol_mix
Colour mappingcol_bin col_factor col_numeric col_quantile
Modify standard R colour in hcl colour space.col2hcl
Colour manipulationcolour_manip col_darker col_lighter col_saturate col_shift
Fast colour interpolationcolour_ramp
Compose two or more label formatters togethercompose_label
Continuous scalecscale
Discrete scaledscale
Expand a range with a multiplicative or additive constantexpand_range
Known palettesget_palette palette_names reset_palettes set_palette
Label bytes (1 kB, 2 MB, etc)label_bytes
Label currencies ($100, €2.50, etc)label_currency
Label date/timeslabel_date label_date_short label_time label_timespan
Labels from lookup tableslabel_dictionary
Interpolated labelslabel_glue
Label numbers in log format (10^3, 10^6, etc)format_log label_log
Label numbers in decimal format (e.g. 0.12, 1,234)label_comma label_number
Label numbers, avoiding scientific notation where possiblelabel_number_auto
Label ordinal numbers (1st, 2nd, 3rd, etc)label_ordinal ordinal_english ordinal_french ordinal_spanish
Label with mathematical annotationslabel_math label_parse
Label percentages (2.5%, 50%, etc)label_percent
Label p-values (e.g. <0.001, 0.25, p >= 0.99)label_pvalue
Label numbers with scientific notation (e.g. 1e05, 1.5e-02)label_scientific
Label strings by wrapping across multiple lineslabel_wrap
Minor breaks for log-10 axesminor_breaks_log
Minor breaksminor_breaks_n minor_breaks_width
Mute standard colourmuted
Constructors for palettesas_continuous_pal as_discrete_pal is_colour_pal is_continuous_pal is_discrete_pal is_numeric_pal is_pal new_continuous_palette new_discrete_palette palette_na_safe palette_nlevels palette_type
Number optionsnumber_options
Out of bounds handlingcensor discard oob oob_censor oob_censor_any oob_discard oob_keep oob_squish oob_squish_any oob_squish_infinite squish squish_infinite
Area palettes (continuous)abs_area area_pal pal_area
Colour Brewer palette (discrete)brewer_pal pal_brewer
Dichromat (colour-blind) palette (discrete)dichromat_pal pal_dichromat
Diverging colour gradient (continuous).div_gradient_pal pal_div_gradient
Arbitrary colour gradient palette (continuous)gradient_n_pal pal_gradient_n
Grey scale palette (discrete)grey_pal pal_grey
Hue palette (discrete)hue_pal pal_hue
Identity paletteidentity_pal pal_identity
Line type palette (discrete)linetype_pal pal_linetype
Manual palette (discrete)manual_pal pal_manual
Rescale palette (continuous)pal_rescale rescale_pal
Sequential colour gradient palette (continuous)pal_seq_gradient seq_gradient_pal
Shape palette (discrete)pal_shape shape_pal
Viridis palettepal_viridis viridis_pal
Mutable rangesContinuousRange DiscreteRange Range
Rescale continuous vector to have specified minimum and maximumrescale rescale.AsIs rescale.Date rescale.difftime rescale.dist rescale.integer64 rescale.logical rescale.numeric rescale.POSIXt
Rescale numeric vector to have specified maximumrescale_max
Rescale vector to have specified minimum, midpoint, and maximumrescale_mid rescale_mid.AsIs rescale_mid.Date rescale_mid.dist rescale_mid.integer64 rescale_mid.logical rescale_mid.numeric rescale_mid.POSIXt
Don't perform rescalingrescale_none
Train (update) a continuous scaletrain_continuous
Train (update) a discrete scaletrain_discrete
Inverse Hyperbolic Sine transformationasinh_trans transform_asinh
Arc-sin square root transformationasn_trans transform_asn
Arc-tangent transformationatanh_trans transform_atanh
Box-Cox & modulus transformationsboxcox_trans modulus_trans transform_boxcox transform_modulus
Compose two or more transformations togethercompose_trans transform_compose
Transformation for dates (class Date)date_trans transform_date
Exponential transformation (inverse of log transformation)exp_trans transform_exp
Identity transformation (do nothing)identity_trans transform_identity
Log transformationslog10_trans log1p_trans log2_trans log_trans pseudo_log_trans transform_log transform_log10 transform_log1p transform_log2 transform_pseudo_log
Probability transformationlogit_trans probability_trans probit_trans transform_logit transform_probability transform_probit
Reciprocal transformationreciprocal_trans transform_reciprocal
Reverse transformationreverse_trans transform_reverse
Square-root transformationsqrt_trans transform_sqrt
Transformation for date-times (class POSIXt)time_trans transform_time
Transformation for times (class hms)hms_trans timespan_trans transform_hms transform_timespan
Yeo-Johnson transformationtransform_yj yj_trans
Determine if range of vector is close to zero, with a specified tolerancezero_range