Autoplot continuous phylogeography with optional animation

Creates a ggplot2 visualization of continuous phylogeographic data from BEAST analyses. For simple quick plots, this function provides sensible defaults. For custom visualizations, use build_phylogeo() with the individual geom functions (geom_phylo_branches(), geom_phylo_hpd(), geom_phylo_nodes()).

autoplot.treedata(
  object,
  most_recent_sample = NULL,
  lat = "location1",
  lon = "location2",
  show_map = TRUE,
  show_dispersion_legend = TRUE,
  smooth = TRUE,
  stream = FALSE,
  curvature = -0.25,
  highlight_tips = NULL,
  highlight_color = "red",
  tip_size = 3.5,
  node_size = 3,
  tip_stroke = 1,
  date_format = "%Y",
  animate = FALSE,
  nframes = 100,
  fps = 10,
  end_pause = 20,
  renderer = NULL,
  debug = getOption("ggphylogeo.debug", FALSE),
  height_branches = "height_mean",
  height_hpd = "height_median",
  level = "0.80",
  digits = 2,
  map_pad = 1,
  map_name = "world",
  map_fill = "white",
  map_colour = "gray50",
  arrow = NULL,
  ...
)

Arguments

object: A treedata object with phylogeographic annotations from treeio::read.beast()
most_recent_sample: Date, numeric year (e.g. 2019), or "YYYY-MM-DD" string for calibrating ages to real dates. If NULL, ages remain as numeric heights.
lat: Name of latitude coordinate column (default: "location1")
lon: Name of longitude coordinate column (default: "location2")
show_map: Logical; overlay world map background (default TRUE)
show_dispersion_legend: Logical; show legend explaining branch curvature direction (default TRUE)
smooth: Logical; smooth HPD polygons for visual appeal (default TRUE)
stream: Logical; use stream-style branch plotting with fade effect (default FALSE)
curvature: Curvature of branch curves (default -0.25). Positive values curve left, negative curve right.
highlight_tips: Character vector of tip labels to highlight with special styling
highlight_color: Color for highlighted tips (default "red")
tip_size: Size of tip nodes (default 3.5)
node_size: Size of internal nodes (default 3)
tip_stroke: Stroke width for tip nodes (default: 1)
date_format: Format string for date axis labels (default "%Y")
animate: Logical; create animated plot showing temporal progression (default FALSE). Requires gganimate and gifski packages.
nframes: Number of frames for animation (default 100)
fps: Frames per second for animation (default 10)
end_pause: Frames to pause at end of animation (default 20)
renderer: gganimate renderer function. Default uses gifski if available.
debug: Logical; emit debug messages (default FALSE)
height_branches: Column name for branch ages (default: "height_mean")
height_hpd: Column name for HPD ages (default: "height_median")
level: HPD level to display (default: "0.80" for 80% HPD)
digits: Decimal places for coordinate rounding (default: 2)
map_pad: Padding in degrees around data extent (default: 1)
map_name: Map database name from maps package (default: "world")
map_fill: Fill color for map polygons (default: "white")
map_colour: Outline color for map polygons (default: "gray50")
arrow: Arrow specification for branches (default: NULL)
...: Additional arguments passed to geoms

Value

A ggplot2 object (if animate=FALSE) or gganim object (if animate=TRUE)

Examples

if (FALSE) { # \dontrun{
data(wnv_tree)

# Basic plot
autoplot(wnv_tree, most_recent_sample = "2007-07-01")

# With highlighting
autoplot(wnv_tree,
         most_recent_sample = "2007-07-01",
         highlight_tips = c("WN99-flamingo383"))

# Animation (requires gganimate)
anim <- autoplot(wnv_tree,
                 most_recent_sample = "2007-07-01",
                 animate = TRUE, nframes = 50)
} # }