Add new helper functions (kud_habitat(), pf_access_history(), xy_from…

…_click()).

NAMESPACE

@@ -44,6 +44,7 @@ export(get_residents)
 export(invert_poly)
 export(kud_around_coastline)
 export(kud_around_coastline_fast)
+export(kud_habitat)
 export(lcp_costs)
 export(lcp_from_point)
 export(lcp_graph_surface)
@@ -56,6 +57,7 @@ export(make_matrix_ids)
 export(make_matrix_receivers)
 export(mask_io)
 export(pf)
+export(pf_access_history)
 export(pf_animate_history)
 export(pf_kud_1)
 export(pf_kud_2)
@@ -82,6 +84,7 @@ export(sim_steps)
 export(sim_surface)
 export(split_raster_equally)
 export(update_extent)
+export(xy_from_click)
 importFrom(lubridate,"%within%")
 importFrom(lubridate,`%within%`)
 importFrom(magrittr,"%>%")

R/flapper-package.R

@@ -31,6 +31,7 @@
 #' Some functions facilitate spatial operations that support ecological investigations and space use algorithms:
 #' \itemize{
 #'   \item \link{buffer_and_crop} buffers a spatial object (e.g., receiver locations) and uses this buffered object to crop another (e.g., the local bathymetry);
+#'   \item \link{xy_from_click} gets location coordinates from mouse clicks;
 #'   \item \link{crop_from_click} crops a \code{\link[raster]{raster}} to an area defined by mouse clicks;
 #'   \item \link{cells_from_val} returns the cells (or a \code{\link[raster]{raster}} of the cells) of a \code{\link[raster]{raster}} that are equal to a specified value or lie within a specified range of values;
 #'   \item \link{invert_poly} inverts a polygon (e.g, to define the `sea' from a polygon of the `land');
@@ -97,7 +98,7 @@
 #'     \item \link{coa_setup_delta_t} informs decisions as to an appropriate time interval over which to calculate COAs;
 #'     \item \link{make_matrix_detections} summarises matrices over time intervals (see above);
 #'     \item \link{coa} implements the arithmetic version of the mean-position algorithm to calculate COAs;
-#'     \item \link{kud_around_coastline} and \code{kud_around_coastline_fast} facilitate the estimation of home ranges (e.g., from estimated COAs) in areas of complex coastline;
+#'     \item \link{kud_habitat}, \link{kud_around_coastline} and \code{kud_around_coastline_fast} facilitate the estimation of home ranges (e.g., from estimated COAs) in areas of complex coastline;
 #'   }
 #'   \item The `flapper` family of algorithms
 #'   \itemize{
@@ -132,6 +133,7 @@
 #'       \item \link{pf_setup_movement_pr} provides a simple movement model that defines the probability of movement between locations given the distance between them;
 #'       \item \link{pf_setup_record} creates an ordered list of input files;
 #'       \item \link{pf} implements the PF routine, building on the AC, DC and ACDC algorithms to form the ACPF, DCPF and ACDCPF algorithms;
+#'       \item \link{pf_access_history} accesses particle histories;
 #'       \item \link{pf_plot_history} plots simulated particle histories;
 #'       \item \link{pf_animate_history} animates simulated particle histories;
 #'       \item \link{pf_simplify} assembles movement paths from particle histories;

R/kud_tools.R

@@ -1,3 +1,31 @@
+######################################
+######################################
+#### kud_habitat()
+
+#' @title Define a `habitat' grid for kernel smoothing
+#' @description This function defines a `habitat' grid for kernel smoothing (e.g., via \code{\link[flapper]{kud_around_coastline}}).
+#' @param map A \code{\link[raster]{raster}} that defines grid properties.
+#' @param mask,mask_inside Mask options passed to \code{\link[flapper]{mask_io}}.
+#' @param plot,... A logical input that defines whether or not to plot the habitat grid, alongside any additional arguments passed to \code{\link[sp]{plot.SpatialPixelsDataFrame}}.
+#' @return The function returns a \code{\link[sp]{SpatialPixelsDataFrame}} object that defines `habitat' (1) versus `non-habitat' (0).
+#' @examples
+#' kud_habitat(map = dat_gebco, mask_inside = FALSE)
+#' kud_habitat(map = dat_gebco, mask = dat_coast, mask_inside = TRUE)
+#' @seealso \code{\link[flapper]{kud_around_coastline}}
+#' @author Edward Lavender
+#' @export
+
+kud_habitat <- function(map, mask = map, mask_inside = FALSE, plot = TRUE,...){
+  par_param <- graphics::par()
+  area <- raster::setValues(map, 1)
+  if(!is.null(mask)) area <- mask_io(area, mask = mask, mask_inside = mask_inside, updatevalue = 0)
+  grid <- methods::as(area, "SpatialPixelsDataFrame")
+  if(plot) sp::plot(grid,...)
+  on.exit(graphics::par(par_param))
+  return(grid)
+}
+
+
 ######################################
 ######################################
 #### kud_around_coastline_*()

R/pf_analyse_archive.R

@@ -1,3 +1,43 @@
+########################################
+########################################
+#### pf_access_history
+
+#' @title Access the `history' element of a \code{\link[flapper]{pf_archive-class}} object
+#' @description This function accesses and simplifies the `history' list in a \code{\link[flapper]{pf_archive-class}} object.
+#' @param archive A \code{\link[flapper]{pf_archive-class}} object.
+#' @param bathy (optional) A \code{\link[raster]{raster}} that defines the grid across the area over which particle filtering was applied. If unsupplied, this is extracted from \code{archive} if available.
+#' @details From the `history' element of a \code{\link[flapper]{pf_archive-class}} object, this function extracts particle samples as a dataframe with columns for time steps, cell IDs, cell probabilities and coordinates (if \code{bathy} is available).
+#' @return The function returns a dataframe that defines, for each time step (`timestep'), particle samples (`cell_id'), associated probabilities (`cell_pr') and, if \code{bathy} is available, cell coordinates (`cell_x', `cell_y' and `cell_z').
+#' @examples
+#' pf_access_history(dat_dcpf_histories)
+#' @author Edward Lavender
+#' @export
+
+pf_access_history <- function(archive,
+                              bathy = NULL
+){
+  check_class(input = archive, to_class = "pf_archive")
+  if(is.null(bathy)) bathy <- archive$args$bathy
+  history <- lapply(1:length(archive$history), function(t){
+    elm <- archive$history[[t]]
+    if(!rlang::has_name(elm, "timestep")) elm$timestep <- t
+    elm <- elm[, c("timestep", "id_current", "pr_current")]
+  })
+  history <- do.call(rbind, history)
+  colnames(history) <- c("timestep", "cell_id", "cell_pr")
+  if(!is.null(bathy)){
+    history[, c("cell_x", "cell_y")] <- raster::extract(bathy, history$cell_id)
+    history$cell_z <- raster::extract(bathy, history$cell_id)
+  }
+  cols <- c("timestep", "cell_id", "cell_x", "cell_y", "cell_z", "cell_pr")
+  history[, cols[cols %in% colnames(history)]]
+  history <-
+    history %>%
+    dplyr::arrange(.data$timestep, .data$cell_id, .data$cell_pr)
+  return(history)
+}
+
+
 ########################################
 ########################################
 #### pf_plot_history()

R/pf_analyse_either.R

@@ -225,12 +225,14 @@ pf_plot_map <- function(xpf,
 #'          sample_size = 500,
 #'          estimate_ud = kud_around_coastline_fast, grid = grid)
 #' ## Implementation based on paths
+#' \dontrun{
 #' pf_kud_1(out_dcpf_paths,
 #'          bathy = bathy,
 #'          sample_size = 500,
 #'          estimate_ud = kud_around_coastline_fast, grid = grid)
 #' prettyGraphics::add_sp_path(x = out_dcpf_paths$cell_x, y = out_dcpf_paths$cell_y,
 #'                             length = 0.01)
+#' }
 #' par(pp)
 #'
 #' #### Example (2): Implement pf_kud_2() using default options
@@ -257,6 +259,7 @@ pf_plot_map <- function(xpf,
 #'          chunks = 2L,
 #'          cl = parallel::makeCluster(2L))
 #' ## Implementation based on paths
+#' \dontrun{
 #' cl <- parallel::makeCluster(2L)
 #' parallel::clusterEvalQ(cl = cl, library(raster))
 #' pf_kud_1(out_dcpf_paths,
@@ -265,6 +268,7 @@ pf_plot_map <- function(xpf,
 #'          estimate_ud = flapper::kud_around_coastline_fast, grid = grid,
 #'          chunks = 2L,
 #'          cl = cl)
+#' }
 #' par(pp)
 #'
 #' #### Example (4): For improved speed with pf_kud_2(), use sample_size

R/spatial_tools.R

@@ -82,6 +82,30 @@ buffer_and_crop <- function(to_buffer,
 }
 
 
+######################################
+######################################
+#### xy_from_clicks()
+
+#' @title Get location coordinates from mouse click(s)
+#' @description This function defines a two-column matrix of x, y coordinates from clicked locations on a map.
+#' @return The function returns a two-column matrix with coordinates.
+#' @examples
+#' \dontrun{
+#' raster::plot(dat_gebco)
+#' xy <- xy_from_click()
+#' graphics::points(xy, col = "red")
+#' }
+#' @author Edward Lavender
+#' @export
+
+xy_from_click <- function(){
+  cat("Please click locations on the map and press [Esc] when you are done...\n")
+  xy <- graphics::locator()
+  xy <- matrix(c(xy$x, xy$y), ncol = 2, byrow = FALSE)
+  return(xy)
+}
+
+
 ######################################
 ######################################
 #### crop_from_click()

README.Rmd

@@ -101,6 +101,7 @@ A number of functions facilitate the acquisition, assembly, processing and check
 A number of functions facilitate spatial operations that support ecological investigations and space use algorithms:
 
 * `buffer_and_crop()` buffers a spatial object (e.g., receiver locations) and uses this buffered object to crop another (e.g., the local bathymetry); 
+* `xy_from_click()` gets location coordinates from mouse clicks; 
 * `crop_from_click()` crops a raster to an area defined by mouse clicks;
 * `cells_from_val()` returns the cells (or a raster of the cells) of a raster that are equal to a specified value or lie within a specified range of values;
 * `invert_poly()` inverts a polygon (e.g, to define the 'sea' from a polygon of the 'land'); 
@@ -164,7 +165,7 @@ Centres of activity (COA) are one of the most widely used metrics for the recons
 * `coa_setup_delta_t()` informs decisions as to an appropriate time interval over which to calculate COAs; 
 * `make_matrix_detections()` summarises detections over time intervals (see above); 
 * `coa()` implements the arithmetic version of the mean-position algorithm to calculate COAs; 
-* `kud_around_coastline()` and `kud_around_coastline_fast()` facilitate the estimation of home ranges (e.g., from estimated COAs) in areas of complex coastline;
+* `kud_habitat()`, `kud_around_coastline()` and `kud_around_coastline_fast()` facilitate the estimation of home ranges (e.g., from estimated COAs) in areas of complex coastline;
 
 ### The `flapper` family of algorithms
 
@@ -208,7 +209,8 @@ Each algorithm (AC, DC and ACDC) can be extended through incorporation of a move
 * `pf_setup_movement_pr` provides a simple movement model that defines the probability of movement between locations given the distance between them; 
 * `pf_setup_record()` creates an ordered list of input files;
 * `pf()` implements the particle filtering routine; 
-* `pf_plot_history()` plot simulated particle histories; 
+* `pf_access_history()` accesses particle histories;
+* `pf_plot_history()` plots simulated particle histories; 
 * `pf_animate_history()` animates simulated particle histories;
 * `pf_simplify()` assembles movement paths from particle histories;
 * `pf_plot_map()` maps the 'probability of use' across an area based on sampled particles or reconstructed paths;

README.md

@@ -222,6 +222,7 @@ ecological investigations and space use algorithms:
   - `buffer_and_crop()` buffers a spatial object (e.g., receiver
     locations) and uses this buffered object to crop another (e.g., the
     local bathymetry);
+  - `xy_from_click()` gets location coordinates from mouse clicks;
   - `crop_from_click()` crops a raster to an area defined by mouse
     clicks;
   - `cells_from_val()` returns the cells (or a raster of the cells) of a
@@ -340,9 +341,9 @@ following functions:
     (see above);
   - `coa()` implements the arithmetic version of the mean-position
     algorithm to calculate COAs;
-  - `kud_around_coastline()` and `kud_around_coastline_fast()`
-    facilitate the estimation of home ranges (e.g., from estimated COAs)
-    in areas of complex coastline;
+  - `kud_habitat()`, `kud_around_coastline()` and
+    `kud_around_coastline_fast()` facilitate the estimation of home
+    ranges (e.g., from estimated COAs) in areas of complex coastline;
 
 ### The `flapper` family of algorithms
 
@@ -425,7 +426,8 @@ process provided by the `pf*()` family of functions:
     between them;
   - `pf_setup_record()` creates an ordered list of input files;
   - `pf()` implements the particle filtering routine;
-  - `pf_plot_history()` plot simulated particle histories;
+  - `pf_access_history()` accesses particle histories;
+  - `pf_plot_history()` plots simulated particle histories;
   - `pf_animate_history()` animates simulated particle histories;
   - `pf_simplify()` assembles movement paths from particle histories;
   - `pf_plot_map()` maps the ‘probability of use’ across an area based