anipaths (version 0.9.3)

animate_paths: animate paths

Description

Animates telemetry data for the purposed of EDA using smoothing splines to interpolate the observed locations. The animations are particularly useful when examining multiple simultaneous trajectories. The output of the call to animate_paths() should bring up a browser window that shows the animation. Additionally, the images generated in images/ (or else the value set for imgdir) may be used with ffmpeg, latex, or other presentation software that can build animations directly from a sequence of images.

Usage

animate_paths(paths, times = NULL, delta.t = NULL, n.frames = 12 * 30,
  interval = 1/12, paths.proj = "+proj=longlat", coord = c("x", "y"),
  Time.name = "time", covariate.name = NULL, covariate.colors = c("black",
  "white"), covariate.thresh = NULL, covariate.legend.loc = "right",
  ID.name = NULL, background = NULL, bg.axes = TRUE, method = "html",
  pt.colors = NULL, dimmed = NULL, res = 1.5, plot.date = TRUE,
  legend.loc = "topright", network = NULL, network.times = NULL,
  network.thresh = 0.5, network.colors = NULL, tail.length = 5,
  xlim = NULL, ylim = NULL, main = NULL, bg.opts = NULL,
  bs = "'tp', fx=T", max.knots = 20, uncertainty.level = NA,
  override = FALSE, return.paths = FALSE, ...)

Arguments

paths

Either a data.frame with longitudes/eastings, latitudes/northings, IDs, and times (see coord, ID.name, and Time.name), a SpatialPointsDataFrame with IDs and times, or a list of data.frames containing the longitudes, latitudes, and times for each individual (with names provided).

times

If all paths are already synchornous, another option for passing the data is to define paths as a list of 2-column matrices, all with the same number of rows, and to specify the times separately via this argument. This is intended to reduce redundancy slightly, but is probably not the most common way to use this package.

delta.t

The gap in time between each frame in the animation. Specify one of delta.t or n.frames. If both are specified, delta.t is used.

n.frames

The number of frames used to animate the complete time domain of the data.

interval

Seconds per frame in animation. Default is 1/12 (or 12 frames per second).

paths.proj

PROJ.4 string corresponding to the projection of the data. Default is "+proj=longlat".

coord

A character vector of length 2 giving the names of the longitude/easting and latitude/northing columns in the paths data.frame (in that order). This is required if paths is not a SpatialPointsDataFrame.

Time.name

The name of the columns in paths gving the observation times. This column must be of class POSIXt, or numeric.

covariate.name

The name of the column in paths that identifies the covariate to be mapped to a ring of color around each point.

covariate.colors

vector of colors which will be used in their given order to make a color ramp (see colorRamp())

covariate.thresh

if changed from its default value of NULL, the interpolated value of the covariate will be binarized based on this numeric value.

covariate.legend.loc

either the location of the covariate legend, or NA if no legend is desired

ID.name

The name of the column in paths that identifies each individual. If left as NULL (default), a single individual is assumed.

background

Three possibilities: (1) A single background image over which animation will be overlayed, or a list of images corresponding to each frame. (2) A list with values location (long/lat), zoom, and maptype (see ggmap::get_map()) which will be used to generate a background for the animation based on Google maps tiles. (3) A logical value of TRUE, which will cue the function to get the best Google Map tile combination it can come up with. Note: ggmap must be installed for (2) and (3).

bg.axes

logical: should animation place axis labels when using a background image (default is TRUE). If RGoogleMaps is used to produce background, labels will be "northing" and "easting". Otherwise, the strings given to coord will be used.

method

either "html" (default) or "mp4". The latter requires the user has installed ffmpeg (see ?animation::saveVideo()).

pt.colors

A vector of colors to be used for each individual in the animation. Default values come from Color Brewer palettes. When a network is provided, this is ignored and individuals are all colored black. If NA, no plot colors are chosen to distinguish individuals. This can be useful when making animations involving a covariate. Consider also setting legend.loc to NA in this case.

dimmed

Numeric vector of individuals to "dim" in the animation. Order corresponds to the order of the ID.name variable, or order of paths list.

res

Resolution of images in animation. Increase this for higher quality (and larger) images.

plot.date

Logical variable toggling date text at the time center of the animation.

legend.loc

passed to first argument of legend() function. Default is "topright". NA removes legend.

network

Array of dimensions (# individuals) \(\times\) (# individuals) \(\times\) n.frames that gives a dyanmic network structure among the individuals.

network.times

Numeric vector. If network time grid doesn't match n.frames, supply the times at which the network has been evaluated so it can be interpolated using smoothing splines.

network.thresh

Network structure is summarized in the animation in a binary way, regardless of whether or not the network is continuously weighted or not. The value of network.thresh determines the level below which no connection is shown, and above which an active connection is shown via colored rings and connecting segments.

network.colors

A symmetric matrix of dimension length(paths) \(\times\) length(paths) giving the colors associated with each pairwise relationship.

tail.length

Length of the tail trailing each individual.

xlim

Boundaries for plotting. If left undefined, the range of the data will be used.

ylim

Boundaries for plotting. If left undefined, the range of the data will be used.

main

Title for each frame. SOON: support for changing titles to allow for, say, dates.

bg.opts

Options passed to plot() function call that makes background in each frame. For example, this could be used to specify blue ocean and gray landcover if background is a SpatialPolygonsDataFrame and bg.opts = list(bg = "dodgerblue4", col = "gray", border = "gray").

bs

default is "'tp'" (thin plate splines), but this can be any spline basis supported by s() in the mgcv package.

max.knots

maximum number of allowed knots. This actual number of knots used in the fitting will be min(max.knots, #observations_i).

uncertainty.level

value in \((0, 1)\) corresponding to level at which to draw uncertainty ellipses. NA (default) results in no ellipses.

override

Logical variable toggling where or not to override warnings about how long the animation procedure will take.

return.paths

logical. Default is FALSE, but if TRUE then the interpolated paths are returned and no animation is produced.

...

other arguments to be passed to ani.options to animation options such as the time interval between image frames.

Value

video file, possibly a directory containing the individual images, or interpolated paths.

Examples

# NOT RUN {
##
vultures$POSIX <- as.POSIXct(vultures$timestamp, tz = "UTC")
vultures_paths <- vultures[vultures$POSIX > as.POSIXct("2009-01-01", origin = "1970-01-01") & 
                             vultures$POSIX < as.POSIXct("2009-04-05", origin = "1970-01-01"), ]
animate_paths(paths = vultures_paths,
              delta.t = "month",
              coord = c("location.long", "location.lat"),
              Time.name = "POSIX",
              ID.name = "individual.local.identifier")
# }
# NOT RUN {
readline("Press [enter] to continue.")
background <- list(location = c(-90, 10),
                   zoom = 3,
                   maptype = "satellite")
COVARIATE <- cos(as.numeric(vultures_paths$timestamp) / 
                   diff(range(as.numeric(vultures_paths$timestamp))) * 4 * pi)
animate_paths(paths = cbind(vultures_paths, COVARIATE),
              delta.t = "week",
              coord = c("location.long", "location.lat"),
              Time.name = "POSIX", covariate.name = "COVARIATE", 
              covariate.colors = RColorBrewer::brewer.pal(n = 9, "RdYlGn"),
              ID.name = "individual.local.identifier", 
              background = background)
# }