0.9.4 public release

16EAGLE · Jun 27, 2017 · 116b9fb · 116b9fb
1 parent ce5ce50
commit 116b9fb
Show file tree

Hide file tree

Showing 11 changed files with 717 additions and 134 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,28 +1,30 @@
-Package: moveVis
-Type: Package
-Title: Movement Data Visualization
-Version: 0.9.1
-Depends: R (>= 2.10)
-Date: 2017-05-23
-Authors@R: person("Jakob", "Schwalb-Willmann", email = "movevis@schwalb-willmann.de",
-  role = c("aut", "cre"))
-Description: Tools to visualize movement data of any kind, e. g by creating path animations from GPS point data.
-License: GPL-3
-RoxygenNote: 6.0.1
-Imports:
-  animation,
-  xts,
-  maptools,
-  ggplot2,
-  grid,
-  rasterVis,
-  raster,
-  sp,
-  geosphere,
-  dismo,
-  utils,
-  grDevices,
-  methods,
-  stats,
-  move,
-  RCurl
+Package: moveVis
+Type: Package
+Title: Movement Data Visualization
+Version: 0.9.4
+Depends: R (>= 2.10)
+Date: 2017-05-23
+Authors@R: person("Jakob", "Schwalb-Willmann", email = "movevis@schwalb-willmann.de",
+  role = c("aut", "cre"))
+Description: Tools to visualize movement data of any kind, e. g by creating path animations from GPS point data.
+License: GPL-3
+RoxygenNote: 6.0.1
+Imports:
+  animation,
+  xts,
+  maptools,
+  ggplot2,
+  grid,
+  rasterVis,
+  raster,
+  sp,
+  geosphere,
+  dismo,
+  utils,
+  grDevices,
+  methods,
+  stats,
+  move,
+  RCurl,
+  gridExtra,
+  reshape
diff --git a/NAMESPACE b/NAMESPACE
@@ -2,6 +2,7 @@
 
 export(animate_move)
 export(animate_raster)
+export(animate_stats)
 export(get_imconvert)
 import(ggplot2)
 importFrom(RCurl,getURL)
@@ -13,22 +14,27 @@ importFrom(grDevices,dev.off)
 importFrom(grDevices,rgb)
 importFrom(grid,arrow)
 importFrom(grid,unit)
+importFrom(gridExtra,grid.arrange)
 importFrom(maptools,gcDestination)
 importFrom(methods,is)
 importFrom(move,move)
 importFrom(raster,crop)
 importFrom(raster,crs)
 importFrom(raster,extent)
+importFrom(raster,extract)
 importFrom(raster,getValues)
 importFrom(raster,projectRaster)
 importFrom(raster,raster)
 importFrom(raster,rasterToPoints)
 importFrom(raster,res)
 importFrom(raster,setValues)
 importFrom(rasterVis,gplot)
+importFrom(reshape,melt)
 importFrom(sp,SpatialPointsDataFrame)
 importFrom(sp,spTransform)
 importFrom(stats,approxfun)
+importFrom(stats,na.omit)
+importFrom(stats,setNames)
 importFrom(utils,download.file)
 importFrom(utils,head)
 importFrom(utils,unzip)

diff --git a/NEWS b/NEWS
@@ -1,13 +1,26 @@
 -----------------------------------------------------------
-moveVis 0.9.3 BETA (only on GitHub)
+moveVis 0.9.4 (on GitHub, submitted to CRAN including prior versions)
+adding animate_stats() and stats arguments for animate_move()
+-----------------------------------------------------------
+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 (on GitHub)
 Fixing major bug
 -----------------------------------------------------------
 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 BETA (only on GitHub)
+moveVis 0.9.2 (on GitHub)
 adding frame_width and frame_height arguments
 -----------------------------------------------------------
 New features:

diff --git a/R/animate_move.R b/R/animate_move.R
diff --git a/R/animate_raster.R b/R/animate_raster.R
@@ -394,7 +394,7 @@ animate_raster <- function(layer, out_dir, conv_dir = "convert", layer_type = ""
   if(map_elements == TRUE){
     if(layer_type == "gradient"){
       plt_fin <- paste0('quiet(plot(gplot(rbl[[i]]) + geom_tile(aes_(fill = ~value)) +
-                          scale_fill_gradientn(colours = layer_col, ',plt_limits,', guide=guide_colourbar(title = legend_title, label.vjust = 0.9, title.hjust = 0, title.vjust = 0)) +
+                          scale_fill_gradientn(colours = layer_col, ',plt_limits,', na.value = layer_nacol, guide=guide_colourbar(title = legend_title, label.vjust = 0.9, title.hjust = 0, title.vjust = 0)) +
                           scale_y_continuous(expand = c(0,0)) + scale_x_continuous(expand = c(0,0)) + theme(aspect.ratio=1) +',
                         plt_scale_north,"+",plt_progress)
     }

diff --git a/R/animate_stats.R b/R/animate_stats.R
@@ -0,0 +1,134 @@
+#' Animate movement data statistics
+#'
+#' \code{animate_stats} animates statistic plot from movement data provided as \code{move} class objects or a list of them and basemap data provided as \code{raster}. It extracts basemap values of pixels that are part of the movement paths and visualizes frequencies per value. The function creates an animated GIF file and saves it into the output directory. See also \code{\link{animate_move}}. 
+#'
+#' @param data_ani list or \code{moveStack} class object. Needs to contain one or several \code{move} class objects (one for each individual path to be displayed) containing point coordinates, timestamps and projection.
+#' @param out_dir character. Output directory for the GIF file creation.
+#' @param conv_dir character. Command or directory to call the ImageMagick convert tool (default to be \code{convert}). You can use \code{conv_dir = get_imconvert()} to search for the right command/tool directory and/or get the required software.
+#' @param layer raster, list or character. Single raster object or list of raster objects to be used as (dynamically changing) basemap layer. Default is \code{"basemap"} to download a static basemap layer. Use a rasterBrick class object and set layer_type to "\code{RGB}" to compute a RGB basemap.
+#' @param layer_dt POSIXct or list. Single POSIXct date/time stamp or list of POSIXct date/time stamps corresponding to the acquisition dates of the \code{layer} raster objects.
+#' @param layer_int logical. Whether to interpolate the basemap layer objects over time, if several are provided (\code{TRUE}), or to display them one after another depending on the animation time frame that is displayed (\code{FALSE}). Default is \code{FALSE}.
+#' @param layer_type charachter. Layer type. Can be either "\code{RGB}" (if layer is a rasterBrick class onejct), "\code{gradient}" or "\code{discrete}". Default is "\code{RGB}". Ignored, if \code{layer = "basemap"}.
+#' @param val_limits numeric vector. Fixed minimum and maximum limit values of the basemap value range (gradient layer type). Default is NA for data-depending minimum and maximum values. Ignored, if \code{layer_type} is "discrete" or "RGB".
+#' @param paths_col character vector. Colours of the individual animation paths. If set to "auto", a predfined colour set will be used. If single colour, all paths will be displayed by the same colour. If more individuals then colours, the colours are repeated.
+#' @param paths_mode character vector. Mode to be used for dealing with time information when displaying multiple individual paths. See \code{\link{animate_move}} for details. Default is "true_data".
+#' @param stats_type character. Defines which standard plot design should be used. Select either "line" or "bar". Ignored, if \code{stats_gg} is used.
+#' @param stats_gg character. Enables usage of \code{ggplot2} syntax for plot design. If set, \code{stats_type} is ignored. See \code{details} for information on the statistic data structure to be used by the user defined plot function.
+#' @param stats_digits numeric. Defines how detailed the statistic plot should be as number of decimals. Values with more decimals are rounded. Default is 1 for one decimal.
+#' @param stats_tframe numeric. Defines the temporal range of the periodic stats plot. Default is 5 meaning that five time frames back from the displayed frame are evaluated.
+#' @param stats_lay matrix. Optional layout. Based on the \code{\link{grid.arrange}} syntax.
+#' @param stats_title character vector. Optional plot titles. Two character strings within a vector.
+#' @param frames_nmax numeric. Number of maximum frames. If set, the animation will be stopped, after the specified number of frames is reached. Default is 0 (displaying all frames).
+#' @param frames_interval numeric. Duration, each frame is displayed (in seconds). Default is .04.
+#' @param frames_nres numeric. Interval of which frames of all frames should be used (nth elements). Default is 1 (every frame is used). If set to 2, only every second frame is used.
+#' @param frames_width numeric. Number of pixels of frame width. Default is 600.
+#' @param frames_height numeric. Number of pixels of frame height. Defualt is 600.
+#' @param out_name character. Name of the output file. Default is "final_gif".
+#' @param log_level numeric. Level of console output given by the function. There are three log levels. If set to 3, no messages will be displayed except erros that caused an abortion of the process. If set to 2, warnings and errors will be displayed. If set to 1, a log showing the process activity, wanrnings ans errors will be displayed.
+#' @param log_logical logical. For large processing schemes. If TRUE, the function returns TRUE when finished processing succesfully.
+#' @param ... optional arguments.
+#' 
+#' @return None or logical (see \code{log_logical}. The output GIF file is written to the ouput directory.
+#' 
+#' @details \code{animate_stats} is a wrapper function of \code{\link{animate_move}} to create single statistic plots without spatial plotting. For statistic plot animations sidy-by-side with spatial plot animations, use \code{\link{animate_move}} (see \code{stats_create} argument). The function can handle all arguments taken by \code{animate_stats} as well.
+#' Use \code{stats_gg} to provide an own ggplot2 plot design as shown in the examples. The statistics are stored for both plots (periodic and accumulated) withn the variable \code{pdat} (list of two, indexed by k ranging from 1 to 2 for each plot). Both \code{pdat} lists contain the stats elements framewise for each time step. For this, see the \code{stats_gg} example. The variable \code{cols} (list of two, one per plot) contains the defined colour values and namings. 
+#' 
+#' @examples
+#' #Load move and moveVis packages
+#' library(move)
+#' library(moveVis)
+#' 
+#' #Get the sample data from the moveVis package
+#' data("move_data")
+#' move_data$dt <- as.POSIXct(strptime(move_data$dt, "%Y-%m-%d %H:%M:%S", tz = "UTC"))
+#'
+#' #Differentiate data per individual
+#' indi_levels <- levels(move_data$individual)
+#' indi_levels_n <- length(indi_levels)
+#' for(i in 1:indi_levels_n){
+#'   if(i == 1){
+#'     indi_subset <- list(subset(move_data, individual == indi_levels[i]))
+#'   }else{
+#'     indi_subset <- c(indi_subset,list(subset(move_data,
+#'                                individual == indi_levels[i])))
+#'   }
+#' }
+#' indi_names <- paste(indi_levels, collapse = ", ")
+#' 
+#' #Create move class object
+#' for(i in 1:length(indi_subset)){
+#'   if(i == 1){
+#'      data_ani <- list(move(x=indi_subset[[i]]$lon,y=indi_subset[[i]]$lat,
+#'                                  time=indi_subset[[i]]$dt,
+#'                                  proj=CRS("+proj=longlat +ellps=WGS84"),
+#'                                  animal=indi_levels[i]))
+#'   }else{
+#'      data_ani[i] <- list(move(x=indi_subset[[i]]$lon,y=indi_subset[[i]]$lat,
+#'                                  time=indi_subset[[i]]$dt,
+#'                                  proj=CRS("+proj=longlat +ellps=WGS84"),
+#'                                  animal=indi_levels[i]))}
+#' }
+#' 
+#' #Load basemap data (MODIS NDVI)
+#' data("basemap_data")
+#' layer = basemap_data[[1]]
+#' layer_dt = basemap_data[[2]]
+#' 
+#' #Find command or directory to convert tool of ImageMagick
+#' conv_dir <- get_imconvert()
+#' 
+#' #Specify output directory
+#' out_dir <- "/out/test"
+#' 
+#' #Call animate_stats()
+#' animate_stats(data_ani, out_dir, conv_dir = conv_dir,
+#'               layer=layer, layer_dt = layer_dt, layer_type = "gradient",
+#'               stats_digits = 1, stats_type = "bar", out_name = "final_gif",
+#'               log_level = 1,frames_nmax = 60)
+#'               
+#' #Define your own ggplot2 plot design
+#' stats_gg <- 'ggplot(data = pdat[[k]][[i]], aes_(x = ~val, y = ~value, colour = ~variable)) + 
+#'              geom_smooth() + geom_point() + theme_bw() + theme(aspect.ratio=1) +
+#'              scale_y_continuous(expand = c(0,0),limits = c(0,stats_max[k])) +
+#'              scale_x_continuous(expand = c(0,0)) + 
+#'              scale_color_manual(name="",values = cols[[k]]) +
+#'              labs(x = "Basemap Value", y="Frequency",
+#'                   title=stats_title[[k]], label=c("123","456")) +
+#'              theme(plot.title = element_text(hjust = 0.5),
+#'                    plot.subtitle = element_text(hjust = 0.5))'
+#'                   
+#' #Call animate_stats() with stats_gg
+#' animate_stats(data_ani, out_dir, conv_dir = conv_dir,
+#'               layer=layer, layer_dt = layer_dt, layer_type = "gradient",
+#'               stats_digits = 1, stats_gg = stats_gg, out_name = "final_gif",
+#'               log_level = 1,frames_nmax = 60)
+#'
+#' @author Jakob Schwalb-Willmann
+#' @seealso \code{\link{get_imconvert}}
+#'
+#' @export
+
+animate_stats <- function(data_ani, out_dir, conv_dir = "convert", layer = "basemap", layer_dt = "basemap", layer_int = FALSE, layer_type = "",
+         val_limits = NA, paths_col = "auto",  paths_mode = "true_data",
+         stats_type = "", stats_gg = "", stats_digits = 1, stats_tframe = 5, stats_lay = 0,
+         stats_title = "", frames_nmax =  0, frames_interval = .04, frames_nres = 1, frames_width = 600,
+         frames_height = 600, out_name = "final_gif", log_level = 1, log_logical = FALSE){
+
+  #Define output handling
+  out <- function(input,type = 1){
+    signs <- c("[LOG]: ", "[WARNING]: ")
+    if(type == 2 & log_level <= 2){print(paste(signs[2],input))}
+    else{if(type == 3){stop(input,call. = FALSE)}else{if(log_level == 1){print(paste(signs[1],input))}}}
+  }
+
+  if(layer[1] == "basemap"){out("Basemap cannot be a Google Basemap for computing stats pixelwise. Please provide a single-layer dataset.",type = 3)}
+  if(layer_type == "RGB"){out("Basemap cannot be of type 'RGB' for computing stats pixelwise. Please provide a single-layer data.",type = 3)}
+
+  #Call animate_move (alias function)
+  animate_move(data_ani, out_dir, conv_dir = conv_dir, layer = layer, layer_dt = layer_dt, layer_int = layer_int, layer_type = layer_type,
+               tail_elements = 1, paths_col = paths_col, paths_mode = "true_data",
+               stats_create = TRUE, stats_tframe = stats_tframe, stats_lay = stats_lay,
+               stats_type = stats_type, stats_title = stats_title,
+               stats_gg = stats_gg, stats_digits = stats_digits, frames_nmax =  frames_nmax, frames_interval = frames_interval, frames_nres = frames_nres, frames_width = frames_width,
+               frames_height = frames_height, out_name = out_name, log_level = log_level, log_logical = log_logical,  stats_only = TRUE)
+}
diff --git a/R/basemap_data.R b/R/basemap_data.R
@@ -0,0 +1,10 @@
+#' MODIS NDVI 2013 example data of Lake Constance area, Germany
+#'
+#' Dataset containing five MODIS NDVI scenes of 2013 covering the Lake Constance area.
+#'
+#' @details The example data have been pre-processed and have euqal extents and projections. 
+#' 
+#' @format List containing two lists of equal lengths: a list of rasters containing 10 MODIS NDVI raster class objects and a list of corresponding POSIXct class timestamp objects.
+#' @source MODIS 2013 freely available data, acsessed using MODIS R package: URL \url{https://cran.r-project.org/package=MODIS}
+#' 
+"basemap_data"
diff --git a/data/basemap_data.rda b/data/basemap_data.rda