frames_graph creates a list of ggplot2 graphs displaying movement-environment interaction. Each object represents a single frame. Each frame can be viewed or modified individually. The returned list of frames can be animated using animate_frames.

  r_type = "gradient",
  fade_raster = FALSE,
  crop_raster = TRUE,
  return_data = FALSE,
  graph_type = "flow",
  path_size = 1,
  path_colours = NA,
  path_legend = TRUE,
  path_legend_title = "Names",
  val_min = NULL,
  val_max = NULL,
  val_by = 0.1,
  verbose = T



move or moveStack of uniform time scale and time lag, e.g. prepared with align_move (recommended). May contain a column named colour to control path colours (see details).


list of raster or rasterStack. Each list element refers to the times given in r_times. Use single-layer raster objects for gradient or discrete data (see r_type). Use a rasterStack containing three bands for RGB imagery (in the order red, green, blue).


list of POSIXct times. Each list element represents the time of the corresponding element in r_list. Must be of same length as r_list.


character, either "gradient" or "discrete". Ignored, if r_list contains rasterStacks of three bands, which are treated as RGB.


logical, if TRUE, r_list is interpolated over time based on r_times. If FALSE, r_list elements are assigned to those frames closest to the equivalent times in r_times.


logical, whether to crop rasters in r_list to plot extent before plotting or not.


logical, if TRUE, instead of a list of frames, a data.frame containing the values extracted from r_list per individual, location and time is returned. This data.frame can be used to create your own multi- or monotemporal ggplot2 movement-environemnt interaction graphs.


character, defines the type of multi-temporal graph that should be drawn as frames. Currently supported graphs are:

  • "flow", a time flow graph with frame time on the x axis and values of the visited cell at x on the y axis per individual track

  • "hist", a cumulative histogram with cell values on the x axis and time-cumulative counts of visits on the y axis per individual track.


numeric, size of each path.


character, a vector of colours. Must be of same length as number of individual tracks in m and refers to the order of tracks in m. If undefined (NA) and m contains a column named colour, colours provided within m are used (see details). Othwersie, colours are selected from a standard rainbow palette per individual track.


logical, wether to add a path legend from m or not. Legend tracks and colours will be ordered by the tracks' temporal apperances, not by their order in m.


character, path legend title. Default is "Names".


numeric, minimum value of the value axis. If undefined, the minimum is collected automatically.


numeric, maximum value of the value axis. If undefined, the maximum is collected automatically.


numeric, increment of the value axis sequence. Default is 0.1. If graph_type = "discrete", this value should be an integer of 1 or greater.


logical, if TRUE, messages and progress information are displayed on the console (default).


An object of class moveVis. If return_data is TRUE, a data.frame is returned (see return_data).


To later on side-by-side join spatial frames created using frames_spatial with frames created with frames_graph for animation, equal inputs must have been used for both function calls for each of the arguments m, r_list, r_times and fade_raster.

If argument path_colours is not defined (set to NA), path colours can be defined by adding a character column named colour to m, containing a colour code or name per row (e.g. "red". This way, for example, column colour for all rows belonging to individual A can be set to "green", while column colour for all rows belonging to individual B can be set to "red". Colours could also be arranged to change through time or by behavioral segments, geographic locations, age, environmental or health parameters etc. If a column name colour in m is missing, colours will be selected automatically. Call colours() to see all available colours in R.


Jakob Schwalb-Willmann



data("move_data", "basemap_data")
# align movement
m <- align_move(move_data, res = 4, unit = "mins")
#> Temporal resolution of 4 [mins] is used to align trajectories.

r_list <- basemap_data[[1]]
r_times <- basemap_data[[2]]

if (FALSE) {
# use the same inputs to create a non-spatial graph, e.g. a flow graph: <- frames_graph(m, r_list = r_list, r_times = r_times, r_type = "gradient",
                          fade_raster = TRUE, graph_type = "flow")
# take a look[[100]]

# make a histogram graph: <- frames_graph(m, r_list = r_list, r_times = r_times, r_type = "gradient",
                          fade_raster = TRUE, graph_type = "hist")
# change the value interval: <- frames_graph(m, r_list = r_list, r_times = r_times, r_type = "gradient",
                          fade_raster = TRUE, graph_type = "hist", val_by = 0.01)
# manipulate the labels, since now they are very dense:
# just replace the current scale <- add_gg(, expr(scale_x_continuous(breaks=seq(0,1,0.1),
                                    labels=seq(0,1,0.1), expand = c(0,0))))[[100]]

# the same can be done for discrete data, histogram will then be shown as bin plots

# to make your own graphs, use frames_graph to return data instead of frames <- frames_graph(m, r_list = r_list, r_times = r_times, r_type = "gradient",
                        fade_raster = TRUE, return_data = TRUE)

# then simply animate the frames using animate_frames 
# see all add_ functions on how to customize your frames created with frames_spatial
# or frames_graph

# see ?animate_frames on how to animate frames