tidyterra (version 0.7.2)

scale_grass: 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)

Value

The corresponding ggplot2 layer with the values applied to the fill/colour

aes().

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.

<a href="https://CRAN.R-project.org/package=terra"><span class="pkg">terra</span></a> equivalent

terra::map.pal()

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.

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.

See Also

grass_db, terra::plot(), terra::minmax(), ggplot2::scale_fill_viridis_c().

See also ggplot2 docs on additional ... parameters:

Other gradient scales and palettes for hypsometry: scale_color_coltab(), scale_cross_blended, scale_hypso, scale_princess, scale_terrain, scale_whitebox

Examples

# \donttest{
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)