MAJOR: add zero_speed_ratio

R/graph_set_movement.R

@@ -15,14 +15,19 @@
 #' @param graph a GeoPressureR `graph` object.
 #' @param type Ground speed `"gs"` or airspeed `"as"`
 #' @param method method used to convert the speed to probability ("gamma", "logis" or "power")
-#' @param shape parameter of the gamma distribution
-#' @param scale  parameter of the gamma and logistic distribution
-#' @param location parameter for the logistic distribution
+#' @param shape parameter of the gamma distribution (km/h)
+#' @param scale  parameter of the gamma and logistic distribution (km/h)
+#' @param location parameter for the logistic distribution (km/h)
 #' @param bird A GeoPressureR `bird` object containing the basic morphological traits necessary:
 #'  mass, wing span, wing aspect ratio, and body frontal area. See `bird_create()`.
 #' @param power2prob function taking power as a single argument and returning a probability
-#' @param low_speed_fix speed below which the probability remains the same. This parameter is used
-#'   to allow short flights covering small distances.
+#' @param low_speed_fix speed below which the probability remains the same, i.e. we assign the same
+#' probability at `low_speed_fix` for any lower speed. This parameter is used to allow short
+#' flights covering small distances. (unit of km/h)
+#' @param zero_speed_ratio multiplicative ratio of the probability for speed zero. This ratio apply
+#' only when the bird is stayin at the same location (fly and come back or stay within pixel size).
+#' This parameter (when greater than 1) is used to favour a bird to stay at the same location rather
+#' than perform short fly.
 #'
 #' @return Graph list with a new list `graph$movement` storing all the parameters needed to compute
 #' the transition probability
@@ -74,7 +79,8 @@ graph_set_movement <- function(graph,
                                location = 40,
                                bird = NULL,
                                power2prob = \(power) (1 / power)^3,
-                               low_speed_fix = 15) {
+                               low_speed_fix = 15,
+                               zero_speed_ratio = 1) {
   graph_assert(graph)
 
   assertthat::assert_that(type == "as" | type == "gs")
@@ -85,11 +91,13 @@ graph_set_movement <- function(graph,
   assertthat::assert_that(is.numeric(scale))
   assertthat::assert_that(is.numeric(location))
   assertthat::assert_that(is.numeric(low_speed_fix))
+  assertthat::assert_that(is.numeric(zero_speed_ratio))
 
   mvt <- list(
     type = type,
     method = method,
-    low_speed_fix = low_speed_fix
+    low_speed_fix = low_speed_fix,
+    zero_speed_ratio = zero_speed_ratio
   )
 
   if (method == "gamma") {

R/graph_transition.R

@@ -30,7 +30,10 @@ graph_transition <- function(graph) {
 
 
   if (graph$param$graph_set_movement$type == "as") {
-    transition <- speed2prob(graph$gs - graph$ws, graph$param$graph_set_movement)
+    as <- graph$gs - graph$ws
+    # Set airspeed to zero when distance is zero (groundspeed=0)
+    as[graph$gs == 0] <- 0
+    transition <- speed2prob(as, graph$param$graph_set_movement)
   } else if (graph$param$graph_set_movement$type == "gs") {
     transition <- speed2prob(graph$gs, graph$param$graph_set_movement)
   } else {

R/param_create.R

@@ -82,7 +82,8 @@ param_create <- function(id, default = FALSE, ...) {
         scale = formals(graph_set_movement)$scale,
         location = formals(graph_set_movement)$location,
         power2prob = formals(graph_set_movement)$power2prob,
-        low_speed_fix = formals(graph_set_movement)$low_speed_fix
+        low_speed_fix = formals(graph_set_movement)$low_speed_fix,
+        zero_speed_ratio = formals(graph_set_movement)$zero_speed_ratio
       ),
       bird = list(
         mass = formals(bird_create)$mass,

R/plot_graph_movement.R

@@ -11,7 +11,7 @@
 #' @family movement
 #' @export
 plot_graph_movement <- function(graph,
-                                speed = seq(1, 120),
+                                speed = seq(0, 120),
                                 plot_plotly = FALSE) {
   # Check that graph is correct
   graph_assert(graph, "movement")

R/print.param.R

@@ -82,6 +82,7 @@ print.param <- function(x, ...) {
   bullets(param, "bird")
   bullets(param$graph_set_movement, "power2prob")
   bullets(param$graph_set_movement, "low_speed_fix")
+  bullets(param$graph_set_movement, "zero_speed_ratio")
 
   cli::cli_h3("Outputs {.fun graph_simulation} {.fun pressurepath_create}")
   bullets(param$graph_simulation, "nj")

R/speed2prob.R

@@ -51,6 +51,7 @@ speed2prob <- function(speed, movement) {
   # The normalization is computed as the sum of probability with a 1km/h unit grid
   norm_speed <- pmax(seq(0, 150), movement$low_speed_fix)
 
+  speed_0 <- speed == 0
   speed <- pmax(speed, movement$low_speed_fix)
 
   if (movement$method == "gamma") {
@@ -76,6 +77,8 @@ speed2prob <- function(speed, movement) {
     prob <- movement$power2prob(speed2power(as, movement$bird)) / norm
   }
 
+  prob[speed_0] <- prob[speed_0] * movement$zero_speed_ratio
+
   return(prob)
 }