Skip to contents

Plot modern POPMAPS raster outputs

Source: R/popmaps-viz.R
plot_popmaps.Rd

plot_popmaps() draws cleaner, terra-based maps from the list returned by popmaps(). It is intended as the modern plotting layer for popmaps2, while popmap_viz() remains available for POPMAPS 1.03 compatibility.

Usage

plot_popmaps(
  pop_raster_list,
  input_raster,
  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,
  add = 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.

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".

add

Logical. If TRUE, add the raster layer to the existing plot.

...

Additional arguments passed to terra::plot().

Value

Invisibly returns the terra::SpatRaster created by popmaps_rast().

Examples

ex_raster <- raster::aggregate(hija_raster, fact = 240)
aps <- popmaps(
  input_raster = ex_raster,
  input_locs = hija_struc,
  surface = "G",
  empirical_pt_dist = 0,
  num_sites = 5,
  num_tested = 2,
  popmod = -0.05,
  threshold = 0,
  ncore = 1
)
plot_popmaps(aps, ex_raster, hija_struc)