dynamic_proj_GIF {dynamicSDM}

Create GIF of dynamic species distribution and abundance projections

Description

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

Usage

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.

Details

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

Value

Exports GIF to Google Drive folder or local directory.

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

References

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

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())