Skip to contents

Plot a histogram of raster cell values

Source: R/plot_hist.R
plot_hist.Rd

Draws the distribution of valid (non-NA) cell values in x with ggplot2, bars filled along the same value ramp used by plot_raster(). Multi-layer rasters are facetted, each panel scaled to its own layer.

Usage

plot_hist(
  x,
  bins = 50,
  col = NULL,
  border = NA,
  main = NULL,
  xlab = "Pixel value",
  ylab = "Count",
  legend = FALSE,
  maxcell = 1e+06,
  ...
)

Arguments

x

A SpatRaster, or the path to a single raster file.

bins

Number of bins. Default 50.

col

Character vector of colours the bar fill ramps through, low value to high. Defaults to a reversed "Hiroshige" ramp. Bars are filled by where their bin sits in the layer's own range, so each facet ramps through the whole palette.

border

Colour of the bar outlines. Default NA, no outline.

main

Plot title. Defaults to the layer name for a single-layer raster, and to none for a facetted one, where the strips carry the names.

xlab, ylab

Axis labels. Default "Pixel value" and "Count".

legend

Logical; draw the fill legend. Default FALSE, since the fill repeats what the x axis already shows. When drawn it is labelled on 0 to 1, the bin's relative position in its layer's range.

maxcell

Numeric; the raster is downsampled to this many cells before the histogram is computed. Default 1e6.

...

Additional arguments passed to ggplot2::geom_histogram(), e.g. boundary or alpha.

Value

A ggplot object.

Details

The raster is downsampled to at most maxcell cells before the histogram is computed, so it approximates the distribution of a large layer.

The default colours are the "Hiroshige" palette from MetBrewer, reversed so low values are dark blue and high values red, and the default theme is theme_science_map(). Both are ordinary ggplot2 components, so either can be replaced by adding a new scale_fill_*() or theme to the returned plot.

See also

plot_raster() for the spatial view of the same values; raster_stats() for them as a table; theme_science_map() for the theme applied.

Examples

if (FALSE) { # \dontrun{
library(terra)
r <- get_layer("fab_dem")

plot_hist(r)
plot_hist(r, bins = 100)

# A ggplot object, so it composes and saves as one
p <- plot_hist(r) + ggplot2::scale_x_log10()
ggplot2::ggsave("2_pipeline/fab_dem_hist.png", p,
                width = 8, height = 5, dpi = 200)
} # }