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

# \donttest{
# Twenty sites on a chain, each visited three times
set.seed(123)
n_sites <- 20
sites <- data.frame(site = factor(seq_len(n_sites)),
                    x = sort(runif(n_sites)), y = runif(n_sites))
df <- sites[rep(seq_len(n_sites), 3), ]
df$count <- rpois(nrow(df), lambda = 8)
df$effort <- rgamma(nrow(df), shape = 4, rate = 1)
df$elevation <- rnorm(nrow(df))
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,
  data = df,
  family = ratiod_poisson_gamma(),
  spatial = spatial_car(adj, group_var = "site"),
  mode = "laplace"
)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot_map(fit, coords = df[, c("x", "y")])
}

# }