Plot a Raster Grid (GeoTIFF/NetCDF) as a Publication-Ready Map

sus_grid_plot() renders a raster surface – a SpatRaster, a single GeoTIFF/NetCDF file path, or the named vector of cached file paths returned by the sus_grid_*() family (e.g. sus_grid_chirps(), sus_grid_era5(), sus_grid_pdsi(), sus_grid_pollution_ghap(), sus_grid_pollution_merra2()) when called with municipalities = NULL or raster_area != FALSE – as a ggplot2 map, following the same publication style used across the other sus_*_plot_*() functions.

Large rasters are automatically downsampled for plotting (see max_cells); the returned object always reflects the full data range of the (possibly downsampled) layer shown.

Usage

sus_grid_plot(
  x,
  layer = 1,
  max_layers = 12,
  municipalities = NULL,
  state_borders = TRUE,
  diverging = FALSE,
  palette = "viridis",
  name = NULL,
  max_cells = 5e+05,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  base_size = 11,
  interactive = FALSE,
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/spatial",
  lang = "pt",
  verbose = TRUE
)

Arguments

x: A SpatRaster (terra), a single file path (.tif, .tif.gz, .nc), or a named character vector of file paths as returned by a sus_grid_*() function.
layer: Integer index, layer name, or "all". Selects which layer to plot when x has multiple layers/dates. "all" facets over every layer (capped at max_layers). Default 1 (first layer).
max_layers: Integer. Maximum number of layers plotted when layer = "all"; extra layers are dropped with a message. Default 12.
municipalities: An optional sf POLYGON object (e.g. one or more rows from geobr::read_municipality(), or a state/region polygon). When supplied, the raster is cropped and masked to this area (values outside the polygon(s) become NA and are dropped from the plot), and its boundary is drawn as a thin overlay. Default NULL (full raster extent, no cropping).
state_borders: Logical. Overlay Brazilian state boundaries (downloaded via geobr, cached). Default TRUE.
diverging: Logical. Use a diverging blue-white-red scale centered on 0 (for anomalies, indices, etc.) instead of the sequential palette. Default FALSE.
palette: Character. Sequential colour palette used when diverging = FALSE. One of "viridis", "plasma", "magma", "inferno", or any RColorBrewer::brewer.pal() sequential name (e.g. "YlOrRd", "Blues"). Default "viridis".
name: Character. Legend title. NULL (default) uses the layer name.
max_cells: Integer. Rasters with more cells than this are regularly resampled before plotting to keep rendering fast. Default 500000.
title: Character. Map title. NULL uses a built-in multilingual default.
subtitle: Character. Map subtitle. NULL auto-generates one from the layer name and resolution.
caption: Character. Figure caption. NULL uses a generic climasus4r source line.
base_size: Numeric. Base font size for theme_void(). Default 11.
interactive: Logical. If TRUE, wraps the ggplot2 object with plotly::ggplotly(). Requires plotly. Default FALSE.
use_cache: Logical. Cache state-boundary metadata to disk. Default TRUE.
cache_dir: Character. Directory for the disk cache. Default "~/.climasus4r_cache/spatial".
lang: Character. Language for messages and axis labels: "pt" (default), "en", "es".
verbose: Logical. Print progress messages. Default TRUE.

Value

A ggplot2 object (class "gg" / "ggplot"), or a plotly object when interactive = TRUE.

Examples

if (FALSE) { # \dontrun{
library(climasus4r)

# From a raster returned in memory
r <- sus_grid_chirps(resolution = "annual", years = 2022,
                      raster_area = TRUE)
sus_grid_plot(r, lang = "pt")

# From cached GeoTIFF paths, faceting every month
paths <- sus_grid_chirps(resolution = "monthly", years = 2022)
sus_grid_plot(paths, layer = "all", lang = "en")

# Anomaly-style raster with a diverging palette
sus_grid_plot(r, diverging = TRUE, name = "Anomaly (mm)")
} # }

Plot a Raster Grid (GeoTIFF/NetCDF) as a Publication-Ready Map

Usage

Arguments

Value

See also

Examples