Animate routes

Animate synthetic routes produced by route() and route_migration(), producing a dynamic version of plot_routes().

Usage

animate_routes(routes, bf, ...)

Arguments

routes

The output of route() or a similarly structured data frame.

bf

A BirdFlow object

...

Arguments passed on to plot_routes

facet

If TRUE then use ggplot2::facet_wrap() to show each route out into a separate subplot.

max_stay_len

Used to scale the stay length dots. If NULL (the default) it will be set to the maximum "stay_len" value in routes. Set it manually to keep the dot scaling consistent across multiple plots.

use_seasonal_colors

If TRUE a color scale that uses blues, greens, yellows, reds, for winter, spring, summer, and fall will be used with a consistent mapping of dates to colors regardless of the range of dates plotted. If FALSE then the data will be plotted using the full color scale.

pal

The color palette to use for plotting when use_seasonal_cols is FALSE. Defaults to viridisLite::viridis(n = 5).

barheight

The height of the color gradient legend bar. Passed to ggplot2::guide_colorbar() as barheight argument. Depending on the output resolution and plot size this may need to be adjusted. Can take a number or the output from ggplot2::unit().

route_linewidth

Line width used for routes.

coast_linewidth

Line width used for coastlines.

dot_sizes

Two numbers indicating the smallest and largest dot sizes used to represent stay length.

Value

A gganim object. print() will plot it with default options, or use animate() to set the options. See the example for recommended settings.

Details

Note when rendering early frames (at a minimum the first) there will only one point per route, resulting in a message: "geom_path(): Each group consists of only one observation. ℹ Do you need to adjust the group aesthetic?" This will possibly be repeated while individuals remain in one location. It can be safely ignored. The error is thrown while rendering and not from within animate_routes() where it could not be suppressed."

Examples

bf <- BirdFlowModels::amewoo
rts <- route(bf, 10,  season = "prebreeding")
anim <- animate_routes(rts, bf)

if (FALSE) { # \dontrun{
  # example render
  timesteps <- unique(rts$timestep)
  gif <- gganimate::animate(anim,
                            device = "ragg_png", # is fast and pretty
                            width = 7, height = 6,
                            res = 150, units = "in",
                            nframes = length(timesteps) * 4, fps = 8)

  # Display
  print(gif)

  # Save
  gif_file <- tempfile("animation", fileext = ".gif")
  gganimate::save_animation(gif, gif_file)
  file.remove(gif_file) # cleanup
} # }