128 plot distr (#134)

add plot_distr() and animate_distr()
update ouput format of rasterize_distr(format = "dataframe")

closes #128

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: BirdFlowR
 Title: Predict and Visualize Bird Movement
-Version: 0.1.0.9031
+Version: 0.1.0.9032
 Authors@R: 
     c(person("Ethan", "Plunkett",  email = "plunkett@umass.edu", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-4405-2251")),

NAMESPACE

@@ -14,6 +14,7 @@ S3method(st_as_sf,BirdFlowRoutes)
 S3method(st_bbox,BirdFlow)
 S3method(st_crs,BirdFlow)
 export(add_dynamic_mask)
+export(animate_distr)
 export(animate_movement_vectors)
 export(animate_routes)
 export(as_distr)
@@ -65,6 +66,7 @@ export(n_distr)
 export(n_parameters)
 export(n_timesteps)
 export(n_transitions)
+export(plot_distr)
 export(plot_movement_vectors)
 export(plot_routes)
 export(preprocess_species)
@@ -99,6 +101,8 @@ importClassesFrom(Matrix,dgCMatrix)
 importClassesFrom(Matrix,dgRMatrix)
 importClassesFrom(Matrix,sparseMatrix)
 importFrom(Matrix,Matrix)
+importFrom(grDevices,gray)
+importFrom(grDevices,grey)
 importFrom(grDevices,rgb)
 importFrom(methods,as)
 importFrom(methods,is)

NEWS.md

@@ -1,3 +1,15 @@
+# BirdFlowR 0.1.0.9032
+2023-09-20
+
+* BREAKING change to column names in data frame returned by `rasterize_distr(format = "dataframe")` 
+  * Old `"time"` is now `"label"` and is an ordered factor it is derived from
+  the column names in the distribution which are often but not always dates.
+  * Old `density` is now value. 
+
+* New functions to visualize distributions:
+  * `plot_distr()` 
+  * `animate_distr()` 
+
 # BirdFlowR 0.1.0.9031
 2023-09-08
 

R/animate_distr.R

@@ -0,0 +1,79 @@
+#' Animate distributions
+#'
+#' Animate distributions as produced by `get_distr()`,
+#' `as_distr()`, or `predict()`.  The distributions will be displayed
+#' in the column order in `distr` and column labels will be used as
+#' plot subtitle.
+#'
+#' @param distr A set of distributions it should be a matrix with `n_active(bf)`
+#' rowsand a column for each distribution. The animation will proceed in the
+#' in column order and column names will be used a subtitles in the plot.
+#' @param bf The BirdFlow object that `distr` is associated with.
+#' @param title The title to use for the animation. The default is
+#' the common name of the species.
+#' @inheritDotParams plot_distr -distr -bf -title
+#'
+#' @return A gganimate object that can be displayed with `print()` or
+#'  or `gganimate::animate()`.  See example for how to export to a file.
+#' @export
+#'
+#' @examples
+#'
+#' # Animate distributions from BirdFlow object - derived from
+#' # eBird Status and Trends:
+#'
+#' bf <- BirdFlowModels::amewoo
+#' ts <- lookup_timestep_sequence(bf, season = "prebreeding")
+#' distr <- get_distr(bf, ts)
+#' anim <- animate_distr(distr, bf,  show_dynamic_mask = TRUE)
+#'
+#' anim
+#'
+#' ### Project a distribution
+#'
+#' # Make starting distribution
+#' # Since we define the point in WGS84 (not crs(bf)) we also have to provide
+#' # the crs.
+#' point <- data.frame(x = -90, y = 35)
+#' d1 <- as_distr(point, bf, crs = "EPSG:4326" )
+#'
+#' # Project - density will spread over type resulting in a vastly different
+#' # range of values
+#' density_spread <- predict(bf, d1, season = "prebreeding")
+#'
+#' # Have the color gradient rescaled to the range of data in each
+#' # individual frame  - density scaling is dynamic.
+#' spread_anim <- animate_distr(density_spread, bf,   dynamic_scale= TRUE)
+#'
+#' # Or put in values to use for the limits of the color scale - values outside
+#' # of the limits will be truncated
+#' spread_anim <- animate_distr(density_spread, bf,  limit = c(0, 0.05))
+#'
+#'
+#' \dontrun{
+#'   # example render fo file
+#'   gif <- gganimate::animate(spread_anim,
+#'                             device = "ragg_png", # ragg_png is fast and pretty
+#'                             width = 7, height = 6,
+#'                             res = 150, units = "in")
+#'   # Display
+#'   print(gif)
+#'
+#'   # mv
+#'   gif_file <- tempfile("animation", fileext = ".gif")
+#'   gganimate::save_animation(gif, gif_file)
+#'   file.remove(gif_file) # cleanup
+#'   }
+animate_distr <- function(distr, bf, title = species(bf), ...){
+
+   p <- plot_distr(distr, bf, ...)
+
+  # Drop faceting and add animation
+  a <- p +
+    ggplot2::facet_null() +
+    gganimate::transition_manual(frames = .data$label) +
+    ggplot2::labs(title = title,
+                  subtitle = "{current_frame}")
+
+  return(a)
+}

R/is_location_valid.R

@@ -10,7 +10,7 @@
 #' one should be used: either `i` a vector of location indices
 #' (see [xy_to_i()]), or `x` and `y`.
 #'
-#' For both functions time shold be input either as `timestep` or `date`.
+#' For both functions time should be input either as `timestep` or `date`.
 #'
 #' The number of timesteps or dates should either be 1 or match to the number
 #' of locations or distributions; if singular it will be applied to all.