Merge pull request #224 from birdflow-science/bmtr

Rename `calc_flux()` to `calc_bmtr()`.

Author: ethanplunkett

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: BirdFlowR
 Title: Predict and Visualize Bird Movement
-Version: 0.1.0.9076
+Version: 0.1.0.9077
 Authors@R: 
     c(person("Ethan", "Plunkett",  email = "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-4405-2251")),

LICENSE

@@ -1,21 +1,2 @@
-MIT License
-
-Copyright (c) 2022 birdflow-science
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+YEAR: 2025
+COPYRIGHT HOLDER: birdflow-science

LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2022 BirdFlowR authors
+Copyright (c) 2025 birdflow-science
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

NAMESPACE

@@ -22,6 +22,7 @@ export(Routes)
 export(add_dynamic_mask)
 export(add_stay_id)
 export(add_stay_id_with_varied_intervals)
+export(animate_bmtr)
 export(animate_distr)
 export(animate_flux)
 export(animate_movement_vectors)
@@ -32,6 +33,7 @@ export(as_distr)
 export(as_transitions)
 export(birdflow_options)
 export(build_transitions)
+export(calc_bmtr)
 export(calc_flux)
 export(calc_interval_metrics)
 export(calc_movement_vectors)
@@ -88,6 +90,7 @@ export(n_parameters)
 export(n_timesteps)
 export(n_transitions)
 export(pad_timestep)
+export(plot_bmtr)
 export(plot_distr)
 export(plot_flux)
 export(plot_loss)

NEWS.md

@@ -1,3 +1,9 @@
+# BirdFlowR 0.1.0.9077
+2025-09-29
+
+Rename `calc_flux()` to `calc_bmtr()` 
+The old function now wraps the new with a deprecation warning.
+
 # BirdFlowR 0.1.0.9076
 2025-05-25
 

R/animate_bmtr.R

@@ -0,0 +1,39 @@
+#' Animate BirdFlow Migration Traffic Rate (BMTR)
+#'
+#' Animate migration traffic rates produced by [calc_bmtr()].
+#'
+#' @inheritParams plot_bmtr
+#' @inheritDotParams plot_bmtr
+#'
+#' @return A [`gganim`][gganimate::gganimate-package] object
+#' @export
+#' @inherit calc_bmtr examples
+#' @seealso [calc_bmtr()],[plot_bmtr()]
+animate_bmtr <- function(bmtr, bf, title = species(bf), ...) {
+  p <- plot_bmtr(bmtr, bf, ...)
+
+  anim <- p +
+    ggplot2::facet_null() +
+    gganimate::transition_manual(frames = .data$label) +
+    ggplot2::labs(title = title,
+                  subtitle = "{current_frame}")
+
+  return(anim)
+}
+
+
+
+
+#' Animate Bird Flow Migration Traffic Rate (BMTR)
+#'
+#' DEPRECATED FUNCTION.  Please use [animate_bmtr()] instead.
+#' @inheritDotParams animate_bmtr -bmtr
+#' @param flux the output from [calc_bmtr()] or, deprecated, [calc_flux()]
+#' @inherit animate_bmtr return
+#' @export
+animate_flux <- function(flux, ...){
+  warning("animate_flux() is deprecated. ",
+          "Please use animate_bmtr() instead.")
+  animate_bmtr(flux, ...)
+}
+

R/animate_flux.R

@@ -1,6 +1,6 @@
-#' Estimate bird flux
+#' Estimate BirdFlow Migration Traffic Rate (BMTR)
 #'
-#' `calc_flux()` estimates the proportion of the species that passes near
+#' `calc_bmtr()` estimates the proportion of the species that passes near
 #' a set of points during each transition in a BirdFlow model.
 #'
 #' @section Units:
@@ -18,14 +18,14 @@
 #'
 #' @section Limitations:
 #'
-#' `calc_flux()` makes the incorrect simplifying assumption
+#' `calc_bmtr()` makes the incorrect simplifying assumption
 #'  that birds follow the shortest (great circle) path
 #' between the center of the the source and destination raster cells.  Caution
 #' should be used when interpreting the results especially around
 #' major geographic features such as coasts, large lakes, mountain ranges, and
 #' ecological system boundaries that might result in non-linear migration paths.
 #'
-#' `calc_flux()` assumes that a line passes by a point if any part of the line
+#' `calc_bmtr()` assumes that a line passes by a point if any part of the line
 #' is within the radius of the point.  This assumption breaks down if the
 #' radius is much larger than the movement lengths as points that are ahead of
 #' the line may still be within a radius of the line.  In the extreme a large
@@ -34,9 +34,9 @@
 #' the default points and radius as the points ahead of the line will never be
 #' within the radius.
 #'
-#' The default points for `calc_flux()` are aligned with the cell centers as
+#' The default points for `calc_bmtr()` are aligned with the cell centers as
 #' are the movement lines. This alignment means that a very small radius will
-#' result in an overestimate of flux. The default value of half the cell size
+#' result in an overestimate of bmtr. The default value of half the cell size
 #' is sufficient for this not to be a problem, as we are capturing and
 #' standardizing the units based on the entire cell area that that point
 #' represents.
@@ -56,13 +56,13 @@
 #' or an even number. This is a placeholder, currently only `1` is supported.
 #' @param format The format to return the results in one of:
 #' \describe{
-#' \item{`"points"`}{Returns a list with `flux` a matrix or array of
-#'  flux values, and `points` a data frame of either the input `points` or the
+#' \item{`"points"`}{Returns a list with `bmtr` a matrix or array of
+#'  bmtr values, and `points` a data frame of either the input `points` or the
 #'  default cell center derived points.}
 #' \item{`"dataframe"`}{Returns a "long" data frame with columns:
 #' * `x` and `y` coordinates of the points.
 #' * `transition` Transition code.
-#' * `flux` The flux at the point. See "Units" below  .
+#' * `bmtr` The bmtr at the point. See "Units" below  .
 #' * `date` The date associated with the transition, will be at the midpoint
 #'          between timesteps.
 #'
@@ -71,7 +71,7 @@
 #' transition.}
 #'}
 #' @inheritParams is_between
-#' @param weighted If `FALSE` use the original and quicker version of flux
+#' @param weighted If `FALSE` use the original and quicker version of bmtr
 #' that sums all the marginal probability for transitions that pass within a
 #' fixed distance of the point.  If `TRUE` assign a weight to the point and
 #' transition combo that then is multiplied by the marginal probability before
@@ -86,25 +86,25 @@
 #'
 #' \dontrun{
 #' bf <- BirdFlowModels::amewoo
-#' flux <- calc_flux(bf)
+#' bmtr <- calc_bmtr(bf)
 #'
-#' plot_flux(flux, bf)
+#' plot_bmtr(bmtr, bf)
 #'
-#' animate_flux(flux, bf)
+#' animate_bmtr(bmtr, bf)
 #' }
 #'
-calc_flux <- function(bf, points = NULL, radius = NULL, n_directions = 1,
+calc_bmtr <- function(bf, points = NULL, radius = NULL, n_directions = 1,
                       format = NULL, batch_size = 5e5, check_radius = TRUE,
                       weighted = FALSE) {
 
 
   if (!requireNamespace("SparseArray", quietly = TRUE)) {
-    stop("The SparseArray package is required to use calc_flux(). ",
+    stop("The SparseArray package is required to use calc_bmtr(). ",
          "Please install it prior to calling this function.")
   }
 
   if (n_directions != 1)
-    stop("Only one directional flux is supported at the moment.")
+    stop("Only one directional bmtr is supported at the moment.")
 
   if (is.null(format)) {
     if (is.null(points)) {
@@ -131,7 +131,7 @@ calc_flux <- function(bf, points = NULL, radius = NULL, n_directions = 1,
   points <- result$points
   radius_km <- result$radius / 1000
 
-  bf_msg("Calculating Flux\n")
+  bf_msg("Calculating BMTR\n")
 
   timesteps <- lookup_timestep_sequence(bf)
   transitions <- lookup_transitions(bf)
@@ -174,12 +174,12 @@ calc_flux <- function(bf, points = NULL, radius = NULL, n_directions = 1,
     }
   }
 
-  bf_msg("  Formatting flux\n")
+  bf_msg("  Formatting BMTR\n")
   # Standardize to P of population to pass through KM of transect in a week
   net_movement <- net_movement / (radius_km * 2)
 
   if (format == "points") {
-    return(list(flux = net_movement, point = points))
+    return(list(bmtr = net_movement, point = points))
   }
 
   if (format == "spatraster") {
@@ -205,7 +205,7 @@ calc_flux <- function(bf, points = NULL, radius = NULL, n_directions = 1,
     wide <- cbind(as.data.frame(points)[, c("x", "y")],
                   net_movement)
     long <- tidyr::pivot_longer(wide, cols = setdiff(names(wide), c("x", "y")),
-                                names_to = "transition", values_to = "flux")
+                                names_to = "transition", values_to = "bmtr")
 
     long$date <- as.character(lookup_date(long$transition, bf))
 
@@ -215,3 +215,20 @@ calc_flux <- function(bf, points = NULL, radius = NULL, n_directions = 1,
 
   stop(format, "is not a recoginized format.") # shouldn't ever get here
 }
+
+
+
+
+#' Calculate Bird Flow Migration Traffic Rate
+#'
+#' DEPRECATED FUNCTION.  Please use [calc_bmtr()] instead.
+#' @inheritDotParams calc_bmtr
+#'
+#' @inherit calc_bmtr return
+#' @export
+calc_flux <- function(...){
+  warning("calc_flux() is deprecated. ",
+          "Please use calc_bmtr() instead.")
+  calc_bmtr(...)
+
+}

R/calc_flux.R R/calc_bmtr.RR/calc_flux.R renamed to R/calc_bmtr.R

@@ -2,7 +2,7 @@
 # Brownian bridge based weighting. This is a placeholder for now to allow
 # implementing weight_betweeness.
 
-#'  calculate the weights of transitions for flux points
+#'  calculate the weights of transitions for bmtr points
 #'
 #'  `calc_dist_weights()` is an internal function that takes summary stats
 #'  on the relationship between points and a transition line and returns
@@ -17,7 +17,7 @@
 #' @param dist_along_line How far along the line is the point, after
 #' projecting it  onto the line (m)
 #' @param line_lengths How long is the line (m)
-#' @param radius_m The radius of the transect at the flux points - used to
+#' @param radius_m The radius of the transect at the bmtr points - used to
 #' determine the band of probability density that will be added to form
 #' the weight.
 #' @param res_m The resolution of the associated bird flow model, used to

R/calc_distance_weights.R

@@ -87,12 +87,12 @@ is_between <- function(bf,  points = NULL, radius = NULL, n_directions = 1,
   if (is.null(radius)) {
     radius <- mean(res(bf)) / 2
   } else if (check_radius) {
-    # Analysis of the effect of changing radius is in test-calc_flux.R
+    # Analysis of the effect of changing radius is in test-calc_bmtr.R
 
     radius_cells <- radius / mean(res(bf)) # radius converted to cells
     if (radius_cells <= 0.25 || radius_cells >= 1) {
       stop("radius should be less than the resolution and more than 1/4 the ",
-           "resolution or the flux is likely to be biased. ",
+           "resolution or BMTR is likely to be biased. ",
            "Set check_radius to FALSE to ignore this advice.")
     }
   }