moveVis

Movement Data Visualization

Tools to visualize movement data (e.g. from GPS tracking) and temporal changes of environmental data (e.g. from remote sensing) by creating video animations.

CRAN version CRAN downloads Build Status Coverage

Introduction

moveVis provides tools to visualize movement data (e.g. from GPS tracking) and temporal changes of environmental data (e.g. from remote sensing) by creating video animations. It works with move, sp and raster class inputs and turns them into ggplot2 frames that can be further customized. moveVis uses gifski (wraping the gifski cargo crate) and av (binding to FFmpeg) to render frames into animated GIF or video files.

Installation

With version 0.10.0, the package has been rewritten from the ground up with the goal to make it easier to customize the appearance of movement animations. Thus, the logic of the package, its functions and their syntax have changed.

moveVis 0.10.2 (stable) can be installed from CRAN:

install.packages("moveVis")

The development version can be installed from GitHub:

devtools::install_github("16EAGLE/moveVis")

Code written for moveVis version <=0.9.9 will not work with newer versions, but it is quite simple and thus highly recommended to switch to the new syntax due to a variety of advantages. moveVis version <=0.9.9 can still be downloaded here and installed manually:

setwd("your/download/directory")
install.packages("moveVis-0.9.9.tar.gz", repos = NULL)

Function overview

moveVis includes the following functions, sorted by the order they would be applied to create an animation from movement and environmental data:

Preparing movement tracks

  • df2move() converts a data.frame into a move or moveStack object. This is useful if you do not usually work with the move classes and your tracks are present as data.frames.
  • align_move() aligns single and multi-individual movement data to a uniform time scale with a uniform temporal resolution needed for creating an animation from it. Use this function to prepare your movement data for animation depending on the temporal resolution that suits your data.
  • subset_move() subsets a move or moveStack by a given time span. This is useful if you want to create a movement animation of only a temporal subset of your data, e.g. a particular day.

Creating frames

  • get_maptypes() returns a character vector of available map types that can be used with frames_spatial(). moveVis supports OpenStreetMaps and Mapbox basemap imergay. Alternatively, you can provide custom imagery to frames_spatial().
  • frames_spatial() creates a list of ggplot2 maps displaying movement. 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().
  • 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().

Adapting frames

  • add_gg() adds ggplot2 functions (e.g. to add layers such as points, polygons, lines, or to change scales etc.) to the animation frames created with frames_spatial() or frames_graph(). Instead of creating your own ggplot2 functions, you can use one of the other moveVis `add_``functions:
  • add_labels() adds character labels such as title or axis labels to animation frames created with frames_spatial() or frames_graph().
  • add_scalebar() adds a scalebar to the animation frames created with frames_spatial() or frames_graph().
  • add_northarrow() adds a north arrow to the animation frames created with frames_spatial() or frames_graph().
  • add_progress() adds a progress bar to animation frames created with frames_spatial() or frames_graph().
  • add_timestamps() adds timestamps to animation frames created with frames_spatial() or frames_graph().
  • add_text() adds static or dynamically changing text to the animation frames created with frames_spatial() or frames_graph().
  • add_colourscale() adjusts the colour scales of the animation frames created with frames_spatial() and custom map imagery using the r_list argument.
  • join_frames() side-by-side joins the ggplot2 objects of two or more frames lists of equal lengths into a single list of ggplot2 objects per frame using cowplot::plot_grid. This is useful if you want to side-by-side combine spatial frames returned by frames_spatial() with graph frames returned by frames_graph().
  • get_frametimes() extracts the timestamps associated with each frame of a list of frames created using frames_spatial() or frames_graph() and returns them as a vector.

Animating frames (as GIF or video)

  • suggest_formats() returns a selection of suggested file formats that can be used with out_file of animate_frames() on your system.
  • animate_frames() creates an animation from a list of frames computed with frames_spatial(), frames_graph() or join_frames().

Viewing movement tracks

  • view_spatial() displays movement tracks on an interactive mapview or leaflet map.

Get started

The following example shows how to make a simple animation using a default base map by first aligning your movement data to a uniform time scale, creating a list of ggplot2 frames and turning these frames into an animated GIF:

library(moveVis)
library(move)
library(magrittr)
data("move_data", package = "moveVis") # move class object
# if your tracks are present as data.frames, see df2move() for conversion
 
# align move_data to a uniform time scale
m <- align_move(move_data, res = 240, digit = 0, unit = "secs")
 
# create spatial frames with a OpenStreetMap watercolour map
frames <- frames_spatial(m, path_colours = c("red", "green", "blue"),
                         map_service = "osm", map_type = "watercolor", alpha = 0.5) %>% 
  add_labels(x = "Longitude", y = "Latitude") %>% # add some customizations, such as axis labels
  add_northarrow() %>% 
  add_scalebar() %>% 
  add_timestamps(m, type = "label") %>% 
  add_progress()
 
frames[[100]] # preview one of the frames, e.g. the 100th frame
 
# animate frames
animate_frames(frames, out_file = "/full/path/to/moveVis.gif")

Examples

You can find code examples on how to use moveVis here:

Example 1: Creating a simple movement animation

Example 2: Customizing frames

Example 3: Using a mapbox satellite base map

Example 4: Custom base maps from raster data (to be added soon)

Example 5: Interaction graphs (to be added soon)

Example 6: Joining frames side by side (to be added soon)

Example 7: View movement tracks

Code snippets

These commented moveVis code snippets, addressing specific issues or questions, could also be helpful to you:

How to hold the last frame of an animation for a defined time and make it look good by using path_fade (requires moveVis >= 0.10.2)

How to display the full traces of each path using trace_show and trace_colour with frames_spatial() (requires moveVis >= 0.10.2)

How to assign multiple path colours per individual to indicate e.g. behavioral segments (requires moveVis >= 0.10.1)

How to adapt the path legend of frames created with frames_spatial()

How to create a data.frame containing each track coordinate per frame

How to overlay frames with additional transparent rasters changing over time (not yet a optimal solution)

Further resources

Detailed code examples explaining how to use specific functions are provided at the fucntion help pages. User contributions such as code examples or tutorials are very welcome and are linked below as soon as they have been spotted somewhere on the web:

Animating Animal Tracks From Multiple Years Over A Common Year With MoveVis: An Example With Blue Whale Argos Tracks On Movebank by Daniel M. Palacios, Marine Mammal Institute, Oregon State University

Features to be added

Things and features that should be added in future versions of moveVis (feel free to contribute to this list using a pull request):

Next version (0.10.2):

  • [DONE] option to show the trace of the complete track or not (see trace_show and trace_colour in frames_spatial())
  • [DONE] day-/night-time visualization (check out the available map types using get_maptypes() for bright and dark map types)
  • follow population mode
  • follow individual mode

Some day:

  • 3D animations, e.g. for including altitude data

Related packages

The Department of Remote Sensing of the University of Würzburg has developed other R packages that might interest you:

  • getSpatialData, a package to query, preview and download satellite data,
  • RStoolbox, a package providing a wide range of tools for every-day remote sensing processing needs,
  • rsMove, a package providing tools to query and analyze movement data using remote sensing.

For other news on the work at at the Department of Remote Sensing of the University of Würzburg, click here.

Acknowledgements

This initiative is part of the Opt4Environment project and was funded by the German Aerospace Center (DLR) on behalf of the Federal Ministry for Economic Affairs and Energy (BMWi) with the research grant 50 EE 1403.

News

moveVis 0.10.2

Adding some small but practical features. Released on CRAN: 2019-04-30.

New features:

  • Argument path_alpha of frames_spatial() for defining path transparency.
  • Argument tail_colour of frames_spatial() makes it now possible to define the colour of the last tail element, to which the path colour is faded. Default is "white".
  • Argument trace_show of frames_spatial() for displaying the trace of the complete path (instead that it vanishes after the tail).
  • Argument trace_colour of frames_spatial() for defining the colour of the trace.
  • Argument na.colour of add_colourscale() for defining the colouring of NA values.
  • Argument na.show of add_colourscale() to show or hide NA values in discrete background rasters.
  • Argument end_pause of animate_frames() to hold the last frame, adding a pause of a user-defined duration to the end of an animation.
  • Argument path_fade of frames_spatial() to define whether paths should be faded towards the last frame or not. Useful in combination with trace_show = T and when using end_pause of animate_frames().
  • moveVis now stores the timestamps represented by each frame as an attribute time for each ggplot frame. Frame times can now be accessed using get_frametimes().
  • add_timestamps() can now extract timestamps directly from frames, which makes defining m optional.

New functions:

  • get_frametimes() lets you extract the timestamps associated with each frame of a list of frames created using frames_spatial or frames_graph.

Other improvements:

  • add_colourscale() now calculates scale and legend with frame-wide fixed limits, when colours is defined as a named vector, e.g. c("-1" = "red", "0" = "blue", "1" = "green").
  • moveVis now displays the approximated duration of an animation on the console, when creating frames or rendering frames.

moveVis 0.10.1

Bug fixes. Released on CRAN: 2019-04-11.

Bug fixes:

  • Bug that prevented the use of equal colours for multiple individuals
  • Bug that prevented the use of multiple colours per individual, e.g. colouring by behavioral segments/change points
  • Bug that caused an error when using fade_raster = T in frames_spatial() due to unequal vector lengths returned by the internal interpolation function (issue #45)
  • Bug that caused false time assignments or an error, if fade_raster = F and/or r_times contained time elements outside the time range covered by the timestamps of m.

moveVis 0.10.0

moveVis rewrite introducing a new logic and new functions. Released on CRAN: 2019-03-20


**New features:**
  • movement data preparation, frames creation, layout/appearance editing and animation are now seperated, allowing you to customize each of these steps individually.
  • any ggplot2 syntax can now be added to every single frame, allowing you to customize almost everything that can be customized using ggplot2
  • to make customization easier, a variety of add_ functions wrapping pre-defined ggplot2 functions are included. For example, add_gg offers dynamic overplotting, e.g. for polygons or points that change over time
  • track colours can now be provided as a colour column in your movement data, allowing segmentation coulouring or colouring based on a logic, you defined beforhand
  • map elements can be positioned freely or individual map-elements can be created as ggplot2 functions
  • Your animation does not have to be a fixed-size squared standard extent: With the ext argument of frames_spatial() you can define user-defined area of interest (AOI), which scales the frame extent to a specific area
  • A new base map feature based on Miles McBains slippymath package. moveVis supports Mapbox (free, registration needed). OpenStreetMap and Carto (both free) as base map services. See the manual of frames_spatial() for details.
  • frames_spatial() now takes the argument equidistant to define whether the map should be stretched to an equidistant (squared) extent (x and y axis representing same distance) or not (projection-native ratio).
  • frames_spatial() now uses coord_sf to display projections (see details section of frames_spatial()).

**New functions:**

  • align_move(), get_maptypes(), frames_spatial(), frames_graph(), add_gg(), add_labels(), add_scalebar(), add_northarrow(), add_progress(), add_timestamps(), add_text(), add_colourscale(), join_frames(), suggest_formats(), animate_frames(): see the README and the description of the individual functions for further details.

  • subset_move(): subset movement data for a particular time span

  • df2move(): simple wrapper that converts data.frames into move or moveStack objects

  • view_spatial(): view movement data on an interactive map using mapview or leaflet


**Deprecated functions:**
  • animate_move(), animate_raster(), animate_stats(), get_formats(), get_libraries(): These functions have been replaced by a new logic and new functions.

moveVis 0.9.9

Reorganizing standard basemap usage by moveVis. Released on CRAN: 2018-11-23


**New features:**
  • Static basemaps defined through map_type are now retrieved from either OpenStreetMaps for thematic imagery or Microsoft Bing Maps for satellite/hybrid imagery. The usage of OpenStreetMaps is free. For intensive use of the Bing Maps basemap options, please provide your own Bing Maps API key through the api_key argument, after registering at Microsoft here: https://msdn.microsoft.com/en-us/library/ff428642.aspx. Google Maps services will be implemented in a future update for restricted usage using an API key.
  • New baemaps options via map_type: "satellite" (default), "hybrid", "roadmap", "roadmap_dark", "roadmap_bw", "roadmap_watercolor".
  • New argument map_zoom for animate_move: Increase or decrease the degree of detail of a static basemap.
  • New argument map_crop for animate_move: Define, if a static basemap should be cropped to the extent of m or if a wider extent of optimal resolution should be used.

**Bug fixes:**
  • Major bug causing moveVis to break with each available static basemap option due to changes of the Google Maps API policies.

moveVis 0.9.8

Updating unit tests for CRAN checks. Released on CRAN: 2018-09-14


**Bug fixes:**
  • Bug causing unit tests to fail on machines with different external tools available
  • added SystemRequirements field in DESCRIPTION

moveVis 0.9.7

Windows library detection bugs fixed. Released on CRAN: 2018-09-07


**New features:**
  • time_pos_x and time_pos_x allow to specify the location of the timestamp display
  • time_size allows to specify the font size of the timestamp display
  • added unit tests

**Bug fixes:**
  • Bug causing moveVis to not properly detect installed extern libraries that can be called from the command line
  • Bug causing moveVis to not use conv_dir if it contains a Windows path to a tool of an extern library

moveVis 0.9.6

video support, automatic time harmonization, bug fixes. Released on CRAN: 2017-11-01


**New functions:**
  • get_libraries() – handles all extern libraries that are needed for video formats. Just run it to get information on what you need to install. Replaces get_imconvert(), which can still be called for code compatibility reasons
  • get_formats() – outputs all file formats that can be used with moveVis depending on which libraries are installed on the system.

**New features:**
  • moveVis supports now multiple video formats in addition to GIF, if it is linked to a video library (either FFmpeg of libav)
  • animate_move() now detects temporal resolution and uniformity of timestamps automatically to determine, if interpolation needs to be applied to calculate uniform frame times per frame tick
  • animate_move() now calculates and displays the final animation duration derived from the total number of output frames and the fps prior to generating each frame, so that the user can already approximate which size the output animation will have.
  • added "frames_tres" to animate_move() to change temporal resolution through linear interpolation
  • added "frames_pixres" to animate_move() to adjust frame ppi
  • added "paths_na.hold" to animate_move() for defining how to deal with data gaps (hold or not hold last path location)
  • added "time_bar_col" to animate_move() for changing colouring of the time bar at the top border of the map
  • added "out_format" to animate_move() for defining output file format
  • added "indi_names" to animate_move() for defining individual names vector manually
  • added "scalebar_dist" to animate_move() for defining the scalebar length manually
  • added "overwrite" to animate_move() to regulate output file writing behaviour

**Improvements:**
  • it is now possible to use the 'layer' argument to specify one (static) raster object without specifying 'layer_dt', which is only needed, if several raster objects are handed over as a list.
  • in some situations, the movement data extent was bigger than the cropped layer extent: this works now
  • in some situations, stat animation lines were cut off, this should be resolved now
  • recoding of multiple processing steps to increase processing speed and stability
  • increased error handler by several errors likely to occure
  • several bug fixes

**Contributors:**
  • AniMove 2017 participants

moveVis 0.9.5

adding frames_layout, static_data etc., improvements to workflow. Released on CRAN: 2017-08-20


**New features:**
  • RGB stats support added for animate_stats() and animate_move()
  • added animate_move() argument "time_scale" to enable a time scale
  • added animate_move() argument "frame_layout" for user friendly, complex layouting of the output GIF by specifiying the plot locations
  • added animate_move() argument "layer_stretch"
  • added animate_move() expert arguments "conv_cmd" and "conv_frames"

**Improvements:**
  • several major bug fixes
  • major animate_raster() bug fixes, reenabling use of RGB rasterStack inputs
  • stats legend is now locatable using frame_layout
  • fixed a bug of get_imconvert() that caused it to have issues with finding convert.exe on Windows machines, if ImageMagick is preinstalled

**Contributors:**
  • Bart Kranstauber

moveVis 0.9.4

adding animate_stats() and stats arguments for animate_move(). Released on CRAN: 2017-06-28


**New features:**
  • animate_stats() – Enables creation of statistic plot animations visualizing possible relationships between movement paths and basemap. Define individual plot designs based on ggplot2 syntax.
  • stats arguments for animate_move(): Enables statistic plot animations side-by-side with the spatial plot animation of animate_move. Use the animate_stats() arguments with animate_move().
  • extent_factor argument for animate_move(): Increase the distance between the spatial extents of the movement paths and the basemap.

**Improvements:**
  • Several minor bug fixes

moveVis 0.9.3

fixing major bug. Released on CRAN: 2017-06-28


**Improvements:**
  • Fixed a major bug causing an unavoidable error when creating animations with animate_move() using user defined basemaps (Error message: 'Error in eval(expr, envir, enclos) : Object 'frame_l' not found')

moveVis 0.9.2

adding frame_width and frame_height arguments. Released on CRAN: 2017-06-28


**New features:**
  • Added two new arguments to animate_move() function for changing output frame resolution

**Bug report contributors:** * vestlink (at) github

moveVis 0.9.1

fixing important bug; adding animate_raster(). Released on CRAN: 2017-05-23


**New features:**
  • Added moveStack support: animate_move() now takes also moveStack objects in addition to list objects
  • animate_raster() – for animating just basemaps/for doing the same as with animate_move(), but without movement data

**Improvements:**
  • Bug fix: Function now takes movebank.org data --> there had been a static code line preventing the read-out of movement coordinates, which is now solved.
  • Several major and minor bug fixes

**Bug report contributors:**
  • bart1 (at) github
  • Patrick Scherler

moveVis 0.9.0

initial release. Released on CRAN: 2017-04-28


**Initial features:**
  • animate_move()
  • get_imconvert()

**Initial example data sets:**
  • data(move_data)

This document should provide a broad overview on changes that are applied to the moveVis R package. There is no warranty for completeness, since minor changes might not be included. All improvement and feature descriptions are bundled per release version. The document is currently maintained by Jakob Schwalb-Willmann.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.
install.packages("moveVis")

0.10.2 by Jakob Schwalb-Willmann, 3 months ago

http://movevis.org

Report a bug at http://www.github.com/16eagle/moveVis/issues

Browse source code at https://github.com/cran/moveVis

Authors: Jakob Schwalb-Willmann [aut, cre]

Documentation:   PDF Manual  

GPL-3 license

Imports raster, sp, sf, move, RStoolbox, geosphere, slippymath, lubridate, ggplot2, cowplot, gifski, magick, av, pbapply, curl, plyr, dplyr, zoo, magrittr, methods, grDevices

Suggests mapview, leaflet, testthat

System requirements: ImageMagick, FFmpeg, libav

See at CRAN

R links

R homepage

Download R

Mailing lists

R documentation

R manuals

R FAQs

The R Journal

CRAN links

CRAN homepage

CRAN repository policy

Submit a package

METACRAN stuff

About METACRAN

At github

Report a bug