Write a modern POPMAPS map to PNG — write_popmaps

write_popmaps_plot() is a small export wrapper around plot_popmaps(). It writes a publication- or website-ready PNG while returning the written path.

Usage

write_popmaps_plot(
  pop_raster_list,
  input_raster,
  path,
  input_locs = NULL,
  type = c("ancestry", "boundary", "axis"),
  style = c("modern", "manuscript"),
  axis = 1,
  sites = c("pies", "points", "none"),
  site_legend = TRUE,
  boundaries = TRUE,
  palette = "Viridis",
  boundary_palette = "Dark 3",
  background_raster = NULL,
  background_threshold = NULL,
  background_palette = "manuscript_background",
  state_lines = FALSE,
  state_col = "grey15",
  state_lwd = 0.8,
  n = 100,
  legend = TRUE,
  axes = TRUE,
  frame.plot = FALSE,
  main = NULL,
  col_na = "transparent",
  boundary_alpha = 0.2,
  boundary_lwd = 1.4,
  pie_radius = NULL,
  point_cex = 1,
  width = 1800,
  height = 1400,
  res = 220,
  bg = "white",
  overwrite = FALSE,
  ...
)

Arguments

pop_raster_list: A list returned by popmaps().
input_raster: The raster used to create pop_raster_list. It may be a terra::SpatRaster, a legacy raster::RasterLayer, or a raster file path.
path: Output PNG path.
input_locs: Optional POPMAPS location table. When supplied, empirical sampling locations are drawn as ancestry pies or dominant-ancestry points.
type: Map type to draw. "ancestry" plots the maximum ancestry probability layer, "boundary" plots hard population assignments, and "axis" plots one ancestry-axis probability layer.
style: Plot style. "modern" uses the default popmaps2 map style. "manuscript" uses a Massatti and Winkler (2022)-inspired style with grayscale probabilities, colored hard-boundary outlines, muted suitability background, and state outlines when available.
axis: Ancestry axis used when type = "axis". Supply either an integer axis number or a layer name such as "axis_1".
sites: How to draw empirical locations when input_locs is supplied. "pies" draws ancestry-proportion pies, "points" draws points colored by dominant ancestry, and "none" suppresses site symbols.
site_legend: Logical. If TRUE, draw an ancestry-axis legend for site symbols.
boundaries: Logical. If TRUE, hard-boundary outlines are overlaid on ancestry and axis maps.
palette: Continuous color palette for ancestry and axis maps. Named palettes are matched to base R HCL palettes; common choices include "Viridis", "Mako", "Inferno", "YlGnBu", and "Purple-Yellow". A custom color vector may also be supplied.
boundary_palette: Categorical color palette for ancestry axes and hard boundaries. Named palettes are matched to base R HCL palettes, or a custom color vector may be supplied.
background_raster: Optional suitability, habitat, or prediction raster drawn beneath the POPMAPS probability layer. In style = "manuscript", this defaults to input_raster.
background_threshold: Optional numeric cutoff. When supplied, ancestry probability or axis values are shown only where background_raster is greater than or equal to the cutoff; lower cells show only the background.
background_palette: Color palette for background_raster.
state_lines: Logical. If TRUE, overlay state boundaries from the maps package. This is intended for US longitude/latitude outputs.
state_col: Color for state boundaries.
state_lwd: Line width for state boundaries.
n: Number of colors used for continuous raster maps.
legend: Logical. If TRUE, draw raster and site legends.
axes: Logical. If TRUE, draw map axes.
frame.plot: Logical. If TRUE, draw a frame around the map panel.
main: Optional plot title. If NULL, a title is chosen from type.
col_na: Color used for NA raster cells.
boundary_alpha: Fill transparency for hard-boundary maps.
boundary_lwd: Line width for hard-boundary outlines.
pie_radius: Radius for empirical-site pies in map units. When NULL, a conservative radius is chosen from the map extent.
point_cex: Point size for sites = "points".
width, height: Plot dimensions in pixels.
res: Output resolution in pixels per inch.
bg: PNG background color.
overwrite: Logical. If FALSE, the function stops before replacing an existing file.
...: Additional arguments passed to terra::plot().

Value

Normalized output path, invisibly.

Examples

if (FALSE) { # \dontrun{
write_popmaps_plot(aps, ex_raster, "hija-ancestry.png", input_locs = hija_struc)
} # }