added fill_na_values to align_move

Author: 16EAGLE

DESCRIPTION

@@ -1,10 +1,10 @@
 Package: moveVis
 Type: Package
 Title: Movement Data Visualization
-Version: 1.0.0
+Version: 1.0.1
 Depends:
   R (>= 3.5.0)
-Date: 2025-08-05
+Date: 2025-08-22
 Authors@R: c(
   person("Jakob", "Schwalb-Willmann", email = "[email protected]",
          role = c("aut", "cre"), comment = c(ORCID = "0000-0003-2665-1509")),

NEWS.md

@@ -1,5 +1,17 @@
 ***
 
+## moveVis 1.0.1
+Minor improvements.
+
+**New features:**
+
+* Added argument `fill_na_values` to `align_move` to allow control for whether `NA` values of columns at interpolated locations should be filled or not. `NA` values are filled with the value of the temporally closest location.
+
+
+<br>
+
+***
+
 ## moveVis 1.0.0
 Updating `moveVis` to support `move2` for representing trajectory data and `terra` for representing raster data.
 
@@ -29,6 +41,10 @@ Updating `moveVis` to support `move2` for representing trajectory data and `terr
 
 * `moveVis` was added to r-universe for continuous testing and integration. Like on CRAN, platform-specific binaries are build there to ease installation. You can now install the most recent `moveVis` version from r-universe using `install.packages("moveVis", repos = '16eagle.r-universe.dev')`
 
+<br>
+
+***
+
 ## moveVis 0.10.6
 New S3 class and methods to represent frames, lazy plotting, improvements.
 
@@ -55,7 +71,6 @@ New S3 class and methods to represent frames, lazy plotting, improvements.
 * Fixed bug with paths crossing end of grid (aka dateline) when `cross_dateline=TRUE` in `frames_spatial()`
 * Fixing bug causing no path to be displayed at all when `tail_length=0` (now correctly showing points without tails)
 
-
 <br>
 
 ***

R/align_move.R

@@ -6,14 +6,16 @@
 #' 
 #' @inheritParams frames_spatial
 #' @param m \code{move2} object, which is allowed to contain irregular timestamps and diverging temporal resolutions.
-#' @param res either  a \code{units} object representing the temporal resolution \code{m} should be aligned to, or a character being one of 'min', 'max', 'mean' or 'median' to indicate how the target resolution should be derived from \code{m}.
+#' @param res either  a \code{units} object representing the temporal resolution \code{m} should be aligned to, or a character being one of 'minimum', 'maximum', 'mean' or 'median' to indicate how the target resolution should be derived from \code{m}.
 #' @param start_end_time \code{NULL} (default) or a vector of two POSIXct times (one start time and one end time for alignment). If \code{NULL}, the start and end time are retrieved from \code{m} and used for alignment.
 #' \itemize{
 #'   \item \code{"minimum"} to use the smallest temporal resolution of \code{m} (default)
 #'   \item \code{"maximum"} to use the largest temporal resolution of \code{m}
 #'   \item \code{"mean"} to use the rounded average temporal resolution of \code{m}
 #'   \item \code{"median"} to use the rounded median temporal resolution of \code{m}
 #' }
+#' @param fill_na_values logical, whether to fill empty (\code{NA}) values of columns of \code{m} at interpolated locations (defaults to \code{TRUE}). Column values at interpolated locations are filled with the value of the temporally closest location.
+#' 
 #' @param ... deprecated arguments, including \code{digit}, \code{unit} and \code{spaceMethod}.
 #'
 #' @return \code{move2} object, with aligned positions at uniform temporal scale computed from \code{m}, ready to be used by \code{\link{frames_spatial}}.
@@ -70,22 +72,24 @@
 #' 
 #' @export
 
-align_move <- function(m, res = "minimum", start_end_time = NULL, ..., verbose = TRUE){
+align_move <- function(m, res = "minimum", start_end_time = NULL, fill_na_values = TRUE, ..., verbose = TRUE){
   if(inherits(verbose, "logical")) options(moveVis.verbose = verbose)
 
   extras <- list(...)
   if(!is.null(extras$digit)) out("Argument 'digit' is deprecated. See ?moveVis::align_move for details.", type = 2)
   if(!is.null(extras$unit)) out("Argument 'unit' is deprecated. See ?moveVis::align_move for details.", type = 2)
   if(!is.null(extras$spaceMethod)) out("Argument 'spaceMethod' is deprecated. See ?moveVis::align_move for details.", type = 2)
 
+  if(!is.logical(fill_na_values)) fill_na_values <- TRUE
+  
   # check inputs
   .check_move2(m)
   m_tracks <- split(m, mt_track_id(m))
   m_length <- if(mt_n_tracks(m) > 1) sapply(split(m, mt_track_id(m)), nrow) else nrow(m)
   if(any(m_length < 2)) out(paste0("Individual track(s) ", paste0(which(m_length < 2), collapse = ", "), " of 'm' consist(s) of less than 2 locations. A minimum of 2 locations per indvidual track is required for alignment."), type = 3)
 
   # check resolution and define resolution
-  if(all(!c(inherits(res, "units"), inherits(res, "character")))) out("Argument 'res' must either be a 'units' object or one of c('min', 'max', 'mean', 'median').", type = 3)
+  if(all(!c(inherits(res, "units"), inherits(res, "character")))) out("Argument 'res' must either be a 'units' object or one of c('minimum', 'maximum', 'mean', 'median').", type = 3)
   if(inherits(res, "units")){
     time_unit <- as_units("s")
     is_time_unit <- ud_are_convertible(deparse_unit(res), deparse_unit(time_unit))
@@ -177,6 +181,43 @@ align_move <- function(m, res = "minimum", start_end_time = NULL, ..., verbose =
   m_aligned <- m_aligned[order(m_aligned$timestamp),]
   m_aligned <- m_aligned[order(mt_track_id(m_aligned)),]
 
+  # fill variables
+  if(isTRUE(fill_na_values)){
+    m_aligend_filled <- lapply(split(m_aligned, mt_track_id(m_aligned)), function(m_track){
+      for(x in names_attr){
+        this_attr <- m_track[[x]]
+          
+        m_track[[x]] <- sapply(1:length(this_attr), function(i){
+          if(!is.na(this_attr[i])){
+            this_attr[i]
+          } else{
+            left <- if(i == 1) NULL else 1:(i-1)
+            right <- if(i == length(this_attr)) NULL else (i+1):length(this_attr)
+            
+            if(!is.null(left)){
+              non_na <- left[which(!is.na(this_attr[left]))[1]]
+            } else non_na <- NULL
+            if(!is.null(right)){
+              non_na <- c(non_na, right[which(!is.na(this_attr[right]))[1]])
+            }
+            
+            non_na_diff <- abs(sapply(non_na, function(.non_na){
+              difftime(
+                m_track[[mt_time_column(m_track)]][.non_na],
+                m_track[[mt_time_column(m_track)]][i],
+                units = "secs"
+              )
+            }))
+            
+            this_attr[non_na[which.min(non_na_diff)]]
+          }
+        })
+      }
+      return(m_track)
+    })
+    m_aligned <- do.call(rbind, m_aligend_filled)
+  }
+  
   # for now, we just return the aligned data
   m_aligned <- m_aligned[m_aligned$interpolated,]
   m_aligned$interpolated <- NULL

man/align_move.Rd

@@ -5,62 +5,72 @@ output: html_document
 
 *Note: This vignette has not yet been updated to the most recent `moveVis` version. Displayed code will likely not work as it relies on deprecated dependencies such as `move` (replaced by `move2`) or `raster` (replaced by `terra`). For details, see the help pages of `moveVis` and the README as those resources have already been updated.*
 
-`moveVis` is entirely based on the `ggplot2` grammar of graphics. Each list element in `frames` is a `ggplot2` object that represents a single animation frame. Thus, it is possible to customize each frame individually using `ggplot2` functions. Instead, `moveVis` provides a set of functions for making it simpler to cutomize frames. We will use some of them in the following to customize `frames` that we created in the prior section:
+`moveVis` is entirely based on the `ggplot2` grammar of graphics. Each `moveVis` frame is rendered as a `ggplot2` object that represents a single animation frame. Thus, it is possible to customize each frame individually using `ggplot2` functions. Also, `moveVis` provides a set of functions for making it easier to customize frames. Let's create some `moveVis` frames and change their apperance:
 
 ```R
 library(moveVis)
-library(move)
-library(raster)
+library(move2)
+library(sf)
 library(ggplot2)
 
 data("move_data")
 
 # align movement tracks
-move_data <- align_move(move_data, res = 4, unit = "mins")
+move_data <- align_move(move_data, res = units::set_units(4, "min"))
 
 # create frames
 frames <- frames_spatial(move_data, path_colours = c("red", "green", "blue"),
-                         map_service = "osm", map_type = "watercolor", alpha = 0.5)
+                         map_service = "osm", map_type = "topographic", alpha = 0.5)
 
 # edit frames
 frames <- add_labels(frames, x = "Longitude", y = "Latitude") # add labels, e.g. axis labels
 frames <- add_progress(frames) # add a progress bar
 frames <- add_scalebar(frames, height = 0.015) # add a scale bar
 frames <- add_northarrow(frames) # add a north arrow
-frames <- add_timestamps(frames, move_data, type = "label") # add timestamps
+frames <- add_timestamps(frames, type = "label") # add timestamps
 ```
 
 Alternatively, use the pipe, which (in my opinion) makes this more elegant:
 
 ```R
 # edit frames
-frames <- add_labels(frames, x = "Longitude", y = "Latitude") %>% 
-  add_progress() %>% 
-  add_scalebar(height = 0.015) %>% 
-  add_northarrow() %>% 
-  add_timestamps(move_data, type = "label")
+frames <- frames %>% 
+  add_labels(x = "Longitude", y = "Latitude") %>% # add labels, e.g. axis labels
+  add_progress() %>%  # add a progress bar
+  add_scalebar(height = 0.015) %>%  # add a scale bar
+  add_northarrow() %>%  # add a north arrow
+  add_timestamps(type = "label") # add timestamps
 
 ## Have a look at one of the frames:
 frames[[100]]
 ```
 
 <p align="center"><img width="700" src="https://raw.githubusercontent.com/16EAGLE/AUX_data/master/data/moveVis_readme/readme_example2_01.png"></p>
 
-For further details on these functions, please see their help files. If you want to apply your own `ggplot2` syntax to `frames`, e.g. for drawing polygons, lines or points that are static or even change with time, you can do this frame-wise. In the following example, we customize one individual frame just as if you would work with a single `ggplot2` object:
+It's also possible to apply your own `ggplot2` syntax to `frames`, e.g. for drawing polygons, lines or points that are static or change with time. Let's start with editing a single frame. In the following example, we create an `sf` polygon using Lat/Lon coordinates (EPSG:4326), transform it to Pseudo Mercator (EPSG 3857) to match the Coordinate Reference System of default basemaps, and add it to one individual frame:
 
 ```R
-data <- data.frame(x = c(8.917, 8.924, 8.924, 8.916, 8.917),
-                   y = c(47.7678, 47.7675, 47.764, 47.7646, 47.7678))
-
-# just customize a single frame and have a look at it
-frame_test <- frames[[100]] + geom_path(aes(x = x, y = y), data = data,
-                                        colour = "red", linetype = "dashed")
-frame_test
+data <- cbind(
+  x = c(8.96, 8.955, 8.959, 8.963, 8.968, 8.963, 8.96),
+  y = c(47.725, 47.728, 47.729, 47.728, 47.725, 47.723, 47.725)
+)
+
+data <- list(data) %>% 
+  st_polygon() %>% 
+  st_geometry() %>% 
+  st_as_sf(crs = st_crs(4326)) %>% 
+  st_transform(crs = st_crs(3857))
+
+frame_edited <- frames[[100]] + geom_sf(
+    data = data, colour = "red", fill = "transparent", 
+    linetype = "dashed", lwd = 1
+) + coord_sf(expand = F)
+
+frame_edited
 ```
 
 <p align="center"><img width="700" src="https://raw.githubusercontent.com/16EAGLE/AUX_data/master/data/moveVis_readme/readme_example2_02.png"></p>
 
-
 If you just want to change one or a small selection of frames, you could just manipulate those frames like shown above and assign the cusomized `ggplot2` frames to the equivalent elements in your `frames` list.
 
 If you want to edit all frames, you can use the `add_gg()` function. Here, we want to mark a field on the map on all frames. For this, we use the `geom_path()` function of `ggplot2` with `add_gg()`: