scale_grass: GRASS scales
In dieghernan/tidyterra: 'tidyverse' Methods and 'ggplot2' Helpers for 'terra' Objects

scale_grass

R Documentation

GRASS scales

Description

Implementation of GRASS color tables. The following fill scales and palettes are provided:

⁠scale_*_grass_d()⁠: For discrete values.
⁠scale_*_grass_c()⁠: For continuous values.
⁠scale_*_grass_b()⁠: For binning continuous values.
grass.colors(): Gradient color palette. See also grDevices::terrain.colors() for details.

Additional parameters ... would be passed on to:

Discrete values: ggplot2::discrete_scale().
Continuous values: ggplot2::continuous_scale().
Binned continuous values: ggplot2::binned_scale().

Note that tidyterra just documents a selection of these additional parameters, check the ggplot2 functions listed above to see the full range of parameters accepted by these scales.

These palettes are an implementation of terra::map.pal(), that is the default color palettes provided by terra::plot() (terra ⁠> 1.7.78⁠).

Usage

scale_fill_grass_d(
  palette = "viridis",
  ...,
  alpha = 1,
  direction = 1,
  na.translate = FALSE,
  drop = TRUE
)

scale_colour_grass_d(
  palette = "viridis",
  ...,
  alpha = 1,
  direction = 1,
  na.translate = FALSE,
  drop = TRUE
)

scale_fill_grass_c(
  palette = "viridis",
  ...,
  alpha = 1,
  direction = 1,
  values = NULL,
  limits = NULL,
  use_grass_range = TRUE,
  na.value = "transparent",
  guide = "colourbar"
)

scale_colour_grass_c(
  palette = "viridis",
  ...,
  alpha = 1,
  direction = 1,
  values = NULL,
  limits = NULL,
  use_grass_range = TRUE,
  na.value = "transparent",
  guide = "colourbar"
)

scale_fill_grass_b(
  palette = "viridis",
  ...,
  alpha = 1,
  direction = 1,
  values = NULL,
  limits = NULL,
  use_grass_range = TRUE,
  na.value = "transparent",
  guide = "coloursteps"
)

scale_colour_grass_b(
  palette = "viridis",
  ...,
  alpha = 1,
  direction = 1,
  values = NULL,
  limits = NULL,
  use_grass_range = TRUE,
  na.value = "transparent",
  guide = "coloursteps"
)

grass.colors(n, palette = "viridis", alpha = 1, rev = FALSE)

Arguments

`palette`	A valid palette name. The name is matched to the list of available palettes, ignoring upper vs. lower case. See grass_db for more info.
`...`	Arguments passed on to `ggplot2::discrete_scale`, `ggplot2::continuous_scale`, `ggplot2::binned_scale` `breaks` One of: `NULL` for no breaks `waiver()` for the default breaks (the scale limits) A character vector of breaks A function that takes the limits as input and returns breaks as output. Also accepts rlang lambda function notation. `labels` One of: `NULL` for no labels `waiver()` for the default labels computed by the transformation object A character vector giving labels (must be same length as `breaks`) An expression vector (must be the same length as breaks). See ?plotmath for details. A function that takes the breaks as input and returns labels as output. Also accepts rlang lambda function notation. `expand` For position scales, a vector of range expansion constants used to add some padding around the data to ensure that they are placed some distance away from the axes. Use the convenience function `expansion()` to generate the values for the `expand` argument. The defaults are to expand the scale by 5% on each side for continuous variables, and by 0.6 units on each side for discrete variables. `minor_breaks` One of: `NULL` for no minor breaks `waiver()` for the default breaks (one minor break between each major break) A numeric vector of positions A function that given the limits returns a vector of minor breaks. Also accepts rlang lambda function notation. When the function has two arguments, it will be given the limits and major breaks. `n.breaks` An integer guiding the number of major breaks. The algorithm may choose a slightly different number to ensure nice break labels. Will only have an effect if `breaks = waiver()`. Use `NULL` to use the default number of breaks given by the transformation. `nice.breaks` Logical. Should breaks be attempted placed at nice values instead of exactly evenly spaced between the limits. If `TRUE` (default) the scale will ask the transformation object to create breaks, and this may result in a different number of breaks than requested. Ignored if breaks are given explicitly.
`alpha`	The alpha transparency, a number in [0,1], see argument alpha in `hsv`.
`direction`	Sets the order of colors in the scale. If 1, the default, colors are ordered from darkest to lightest. If -1, the order of colors is reversed.
`na.translate`	Should `NA` values be removed from the legend? Default is `TRUE`.
`drop`	Should unused factor levels be omitted from the scale? The default (`TRUE`) removes unused factors.
`values`	if colours should not be evenly positioned along the gradient this vector gives the position (between 0 and 1) for each colour in the `colours` vector. See `rescale()` for a convenience function to map an arbitrary range to between 0 and 1.
`limits`	One of: `NULL` to use the default scale range A numeric vector of length two providing limits of the scale. Use `NA` to refer to the existing minimum or maximum A function that accepts the existing (automatic) limits and returns new limits. Also accepts rlang lambda function notation. Note that setting limits on positional scales will remove data outside of the limits. If the purpose is to zoom, use the limit argument in the coordinate system (see `coord_cartesian()`).
`use_grass_range`	Logical. Should the scale use the suggested range when plotting? See Details.
`na.value`	Missing values will be replaced with this value. By default, tidyterra uses `na.value = "transparent"` so cells with `NA` are not filled. See also #120.
`guide`	A function used to create a guide or its name. See `guides()` for more information.
`n`	the number of colors (`\ge 1`) to be in the palette.
`rev`	logical indicating whether the ordering of the colors should be reversed.

Details

Some palettes are mapped by default to a specific range of values (see grass_db). However, it is possible to modify this behaviour with the use_grass_range argument, When FALSE the color scales would be mapped to the range of values of the color/fill aesthethics, See Examples.

When passing limits parameter the colors would be restricted of those specified by this parameter, keeping the distribution of the palette. You can combine this with oob (i.e. oob = scales::oob_squish) to avoid blank pixels in the plot.

Value

The corresponding ggplot2 layer with the values applied to the fill/colour aes().

terra equivalent

terra::map.pal()

Source

Derived from https://github.com/OSGeo/grass/tree/main/lib/gis/colors. See also r.color - GRASS GIS Manual.

References

GRASS Development Team (2024). Geographic Resources Analysis Support System (GRASS) Software, Version 8.3.2. Open Source Geospatial Foundation, USA. https://grass.osgeo.org.

Examples


filepath <- system.file("extdata/volcano2.tif", package = "tidyterra")

library(terra)
volcano2_rast <- rast(filepath)

# Palette
plot(volcano2_rast, col = grass.colors(100, palette = "haxby"))

library(ggplot2)
ggplot() +
  geom_spatraster(data = volcano2_rast) +
  scale_fill_grass_c(palette = "terrain")

# Use with no default limits
ggplot() +
  geom_spatraster(data = volcano2_rast) +
  scale_fill_grass_c(palette = "terrain", use_grass_range = FALSE)

# Full map with true tints

f_asia <- system.file("extdata/asia.tif", package = "tidyterra")
asia <- rast(f_asia)

ggplot() +
  geom_spatraster(data = asia) +
  scale_fill_grass_c(
    palette = "srtm_plus",
    labels = scales::label_number(),
    breaks = c(-10000, 0, 5000, 8000),
    guide = guide_colorbar(reverse = FALSE)
  ) +
  labs(fill = "elevation (m)") +
  theme(
    legend.position = "bottom",
    legend.title.position = "top",
    legend.key.width = rel(3),
    legend.ticks = element_line(colour = "black", linewidth = 0.3),
    legend.direction = "horizontal"
  )

# Binned
ggplot() +
  geom_spatraster(data = volcano2_rast) +
  scale_fill_grass_b(breaks = seq(70, 200, 25), palette = "sepia")


# With discrete values
factor <- volcano2_rast %>%
  mutate(cats = cut(elevation,
    breaks = c(100, 120, 130, 150, 170, 200),
    labels = c(
      "Very Low", "Low", "Average", "High",
      "Very High"
    )
  ))

ggplot() +
  geom_spatraster(data = factor, aes(fill = cats)) +
  scale_fill_grass_d(palette = "soilmoisture")


# Display all the GRASS palettes
data("grass_db")

pals_all <- unique(grass_db$pal)

# In batches
pals <- pals_all[c(1:25)]
# Helper fun for plotting

ncols <- 128
rowcol <- grDevices::n2mfrow(length(pals))

opar <- par(no.readonly = TRUE)
par(mfrow = rowcol, mar = rep(1, 4))

for (i in pals) {
  image(
    x = seq(1, ncols), y = 1, z = as.matrix(seq(1, ncols)),
    col = grass.colors(ncols, i), main = i,
    ylab = "", xaxt = "n", yaxt = "n", bty = "n"
  )
}
par(opar)

# Second batch
pals <- pals_all[-c(1:25)]

ncols <- 128
rowcol <- grDevices::n2mfrow(length(pals))

opar <- par(no.readonly = TRUE)
par(mfrow = rowcol, mar = rep(1, 4))

for (i in pals) {
  image(
    x = seq(1, ncols), y = 1, z = as.matrix(seq(1, ncols)),
    col = grass.colors(ncols, i), main = i,
    ylab = "", xaxt = "n", yaxt = "n", bty = "n"
  )
}
par(opar)

dieghernan/tidyterra documentation built on Feb. 20, 2025, 4:18 p.m.