Plot spatial predictions as a map

Create publication-ready maps from tulpaRatio spatial predictions. Supports plotting ratio estimates, uncertainty (credible interval width), and individual process predictions (numerator/denominator).

Usage

plot_map(
  x,
  coords = NULL,
  what = c("ratio", "numerator", "denominator", "uncertainty"),
  summary = c("median", "mean", "q2.5", "q97.5", "sd"),
  newdata = NULL,
  title = NULL,
  palette = "viridis",
  points = FALSE,
  point_color = "grey30",
  point_size = 0.5,
  na_color = "transparent",
  crs = NULL,
  legend_title = NULL,
  ...
)

Arguments

x: A ratiod_fit object with spatial structure, or a data frame containing predictions with coordinate columns.
coords: A data frame or matrix with spatial coordinates (columns named 'x'/'y', 'X'/'Y', 'lon'/'lat', 'longitude'/'latitude', or 'Easting'/'Northing'). Required if x is a data frame.
what: What to plot: "ratio" (default), "numerator", "denominator", or "uncertainty".
summary: Which summary statistic: "median" (default), "mean", "q2.5", "q97.5", or "sd".
newdata: Optional data frame with prediction locations and covariates. If NULL and x is a ratiod_fit, uses fitted values at observed locations.
title: Plot title. If NULL, auto-generated based on what.
palette: Color palette: "viridis" (default), "magma", "plasma", "inferno", "cividis", "mako", "rocket", or a custom vector of colors.
points: Logical; if TRUE, overlay observation points. Default FALSE.
point_color: Color for observation points. Default "grey30".
point_size: Size for observation points. Default 0.5.
na_color: Color for NA values. Default "transparent".
crs: Coordinate reference system (proj4 string or EPSG code). If NULL, uses planar coordinates.
legend_title: Title for the color legend. If NULL, auto-generated.
...: Additional arguments passed to ggplot2 theme functions.

Value

A ggplot2 object that can be further customized.

Details

This function provides a streamlined workflow for visualizing spatial predictions from ratio models. It handles:

Extracting predictions from ratiod_fit objects
Converting to appropriate spatial format (stars/sf)
Creating publication-quality maps with sensible defaults
Uncertainty visualization via credible interval width

For custom maps or more control, extract predictions using ratio() or predict() and use ggplot2 directly with geom_stars() or geom_sf().

Required packages

This function requires ggplot2. For raster-style maps, stars and sf are also needed. Install with:

install.packages(c("ggplot2", "stars", "sf"))

Examples

# plot_map requires a fitted spatial ratio model
# See spatial_car() examples for fitting spatial models

if (FALSE) { # \dontrun{
# Fit spatial model (slow, not run on CRAN)
set.seed(123)
n_sites <- 20
n <- 60
df <- data.frame(
  count = rpois(n, lambda = 8),
  effort = rgamma(n, shape = 4, rate = 1),
  elevation = rnorm(n),
  site = factor(rep(1:n_sites, length.out = n)),
  x = rep(runif(n_sites), length.out = n),
  y = rep(runif(n_sites), length.out = n)
)
# Create simple adjacency matrix
adj <- matrix(0, n_sites, n_sites)
for (i in 1:(n_sites-1)) adj[i, i+1] <- adj[i+1, i] <- 1
fit <- tratio(
  count | effort ~ elevation + (1 | site),
  data = df,
  family = ratiod_poisson_gamma(),
  spatial = spatial_car(adj, group_var = "site"),
  mode = "laplace"
)
# plot_map(fit)  # requires ggplot2
} # }