dynamic_proj_GIF function

Create GIF of dynamic species distribution and abundance projections

Plots dynamic species distribution and abundance projections through time and combines images into a GIF.

dynamic_proj_GIF(
  dates,
  projection.type,
  drive.folder,
  user.email,
  local.directory,
  save.drive.folder,
  save.directory,
  width = 10,
  height = 10,
  legend.max,
  legend.min,
  legend.name,
  file.name,
  borders = FALSE,
  border.regions,
  border.colour = "black",
  colour.palette.custom,
  colour.palette
)

Arguments

• dates: a character vector , projection dates in format "YYYY-MM-DD".
• projection.type: a character string, the type of distribution or abundance projection to plot. One of proportional, binary, abundance and stacked.
• drive.folder: optional; a character string, the Google Drive folder to read projection rasters from. Folder must be uniquely named within Google Drive. Do not provide path.
• user.email: optional; a character string, user email for initialising Google Drive. Required if drive.folder or save.drive.folder used.
• local.directory: optional; a character string, the path to local directory to read projection rasters from.
• save.drive.folder: optional; a character string, Google Drive folder to save GIF to. Folder must be uniquely named within Google Drive. Do not provide path.
• save.directory: optional; a character string, path to local directory to save GIF to.
• width: optional; a numeric value, the GIF width in inches Default = 480.
• height: optional; a numeric value, the GIF height in inches Default = 480.
• legend.max: optional; a numeric value, the maximum limit of legend values to standardise across projections.
• legend.min: optional; a numeric value, the minimum limit of legend values to standardise across projections.
• legend.name: optional; a character string, the name for the legend title. Default = projection.type.
• file.name: optional, a character string, the name for the output GIF file. Default = projection.type.
• borders: a logical indicating whether to add country borders to map. Default = FALSE.
• border.regions: optional; a character string or vector, the region or regionss for which to add map borders. Required if borders = TRUE.
• border.colour: optional; a character vector, the colour for plotted map borders. Default = black.
• colour.palette.custom: optional; a character string or vector, the colours to use as plot colour palette.
• colour.palette: optional; a character string, the colormap option to use from viridis. See details for colour palette options.

Returns

Exports GIF to Google Drive folder or local directory.

Details

Function reads in projection rasters for each date. These are plotted using ggplot2 and combined into a Graphics Interchange Format (GIF).

Import projection rasters

Projection rasters for each date must be “tif” files that are uniquely named with the date in format "YYYY-MM-DD" and projection.type. If more than one file name matches the date and projection.type, the function will error.

Google Drive compatibility

If drive.folder or save.drive.folder is given, please ensure the folder name is unique within your Google Drive. Do not provide the path if the folder is nested within others.

If one of drive.folder or save.drive.folder are used then user.email is required to access the appropriate Google Drive user account. This requires users to have installed R package googledrive and initialised Google Drive with valid log-in credentials. Please follow instructions on https://googledrive.tidyverse.org/.

Options for colour palettes using viridis are illustrated at: https://ggplot2.tidyverse.org/reference/scale_viridis.html. Available options include: "magma" (or "A"), "inferno" (or "B"), "plasma" (or "C"), "viridis" (or "D", the default option), "cividis" (or "E"), "rocket" (or "F"), "mako"(or "G") and "turbo" (or "H").

Examples

proj_dates <- dynamic_proj_dates(startdate = "2018-01-01",
                                     enddate = "2018-12-01",
                                     interval = 3,
                                     interval.level = "month")

# Generate fake proportional projection SpatRasters
proj1 <- terra::rast(ncols=22, nrows=25)
proj1 <- terra::setValues(proj1, sample(0:100, terra::ncell(proj1), replace = TRUE)/100)

proj2 <- terra::rast(ncols=22, nrows=25)
proj2 <- terra::setValues(proj2, sample(0:100, terra::ncell(proj2), replace = TRUE)/100)

proj3 <- terra::rast(ncols=22, nrows=25)
proj3 <- terra::setValues(proj3, sample(0:100, terra::ncell(proj3), replace = TRUE)/100)

proj4 <- terra::rast(ncols=22, nrows=25)
proj4 <- terra::setValues(proj4, sample(0:100, terra::ncell(proj4), replace = TRUE)/100)

# Save sample projection rasters to replicate output from `dynamic_proj()`
terra::writeRaster(proj1,
                  filename = paste0(tempdir(),
                  "/",
                  paste0(proj_dates[1], "_proportional.tif")),
                  overwrite = TRUE)
terra::writeRaster(proj2,
                  filename = paste0(tempdir(),
                  "/",
                  paste0(proj_dates[2], "_proportional.tif")),
                  overwrite = TRUE)
terra::writeRaster(proj3,
                  filename = paste0(tempdir(),
                  "/",
                  paste0(proj_dates[3], "_proportional.tif")),
                  overwrite = TRUE)
terra::writeRaster(proj4,
                  filename = paste0(tempdir(),
                  "/",
                  paste0(proj_dates[4], "_proportional.tif")),
                  overwrite = TRUE)

dynamic_proj_GIF(dates = proj_dates,
                projection.type = "proportional",
                local.directory = tempdir(),
                save.directory = tempdir())

References

Wickham, H., and Chang, W, 2016. Package ‘ggplot2’. Create elegant data visualisations using the grammar of graphics. Version, 2(1), pp.1-189.