From c0898a385578aa7e612bb4df11e16c7c2ded3940 Mon Sep 17 00:00:00 2001
From: Edward Lavender <el72@st-andrews.ac.uk>
Date: Tue, 14 Sep 2021 22:56:50 +0100
Subject: [PATCH] Add new helper functions (kud_habitat(), pf_access_history(),
 xy_from_click()).

---
 NAMESPACE                |  3 +++
 R/flapper-package.R      |  4 +++-
 R/kud_tools.R            | 28 ++++++++++++++++++++++++++++
 R/pf_analyse_archive.R   | 40 ++++++++++++++++++++++++++++++++++++++++
 R/pf_analyse_either.R    |  4 ++++
 R/spatial_tools.R        | 24 ++++++++++++++++++++++++
 README.Rmd               |  6 ++++--
 README.md                | 10 ++++++----
 man/flapper.Rd           |  4 +++-
 man/kud_habitat.Rd       | 31 +++++++++++++++++++++++++++++++
 man/pf_access_history.Rd | 28 ++++++++++++++++++++++++++++
 man/pf_kud.Rd            |  4 ++++
 man/xy_from_click.Rd     | 24 ++++++++++++++++++++++++
 13 files changed, 202 insertions(+), 8 deletions(-)
 create mode 100644 man/kud_habitat.Rd
 create mode 100644 man/pf_access_history.Rd
 create mode 100644 man/xy_from_click.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 7a1aca3..7a8bf85 100644
--- a/NAMESPACE
+++ b/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,"%>%")
diff --git a/R/flapper-package.R b/R/flapper-package.R
index 59ed032..bc6a7f0 100644
--- a/R/flapper-package.R
+++ b/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;
diff --git a/R/kud_tools.R b/R/kud_tools.R
index aa40c77..65049f1 100644
--- a/R/kud_tools.R
+++ b/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_*()
diff --git a/R/pf_analyse_archive.R b/R/pf_analyse_archive.R
index dbc94b7..d0c5260 100644
--- a/R/pf_analyse_archive.R
+++ b/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()
diff --git a/R/pf_analyse_either.R b/R/pf_analyse_either.R
index 6130de4..b93636a 100644
--- a/R/pf_analyse_either.R
+++ b/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
diff --git a/R/spatial_tools.R b/R/spatial_tools.R
index 65a955b..ac52c31 100644
--- a/R/spatial_tools.R
+++ b/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()
diff --git a/README.Rmd b/README.Rmd
index 3f230d0..3196164 100644
--- a/README.Rmd
+++ b/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;
diff --git a/README.md b/README.md
index 39711cc..992534a 100644
--- a/README.md
+++ b/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
diff --git a/man/flapper.Rd b/man/flapper.Rd
index e26e108..94b9630 100644
--- a/man/flapper.Rd
+++ b/man/flapper.Rd
@@ -38,6 +38,7 @@ Some functions facilitate the acquisition, assembly, processing and checking of
 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');
@@ -112,7 +113,7 @@ The main thrust of flapper is the implementation of existing and new algorithms
     \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{
@@ -147,6 +148,7 @@ The main thrust of flapper is the implementation of existing and new algorithms
       \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;
diff --git a/man/kud_habitat.Rd b/man/kud_habitat.Rd
new file mode 100644
index 0000000..25ae23e
--- /dev/null
+++ b/man/kud_habitat.Rd
@@ -0,0 +1,31 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/kud_tools.R
+\name{kud_habitat}
+\alias{kud_habitat}
+\title{Define a `habitat' grid for kernel smoothing}
+\usage{
+kud_habitat(map, mask = map, mask_inside = FALSE, plot = TRUE, ...)
+}
+\arguments{
+\item{map}{A \code{\link[raster]{raster}} that defines grid properties.}
+
+\item{mask, mask_inside}{Mask options passed to \code{\link[flapper]{mask_io}}.}
+
+\item{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}}.}
+}
+\value{
+The function returns a \code{\link[sp]{SpatialPixelsDataFrame}} object that defines `habitat' (1) versus `non-habitat' (0).
+}
+\description{
+This function defines a `habitat' grid for kernel smoothing (e.g., via \code{\link[flapper]{kud_around_coastline}}).
+}
+\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
+}
diff --git a/man/pf_access_history.Rd b/man/pf_access_history.Rd
new file mode 100644
index 0000000..c53dd74
--- /dev/null
+++ b/man/pf_access_history.Rd
@@ -0,0 +1,28 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/pf_analyse_archive.R
+\name{pf_access_history}
+\alias{pf_access_history}
+\title{Access the `history' element of a \code{\link[flapper]{pf_archive-class}} object}
+\usage{
+pf_access_history(archive, bathy = NULL)
+}
+\arguments{
+\item{archive}{A \code{\link[flapper]{pf_archive-class}} object.}
+
+\item{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.}
+}
+\value{
+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').
+}
+\description{
+This function accesses and simplifies the `history' list in a \code{\link[flapper]{pf_archive-class}} object.
+}
+\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).
+}
+\examples{
+pf_access_history(dat_dcpf_histories)
+}
+\author{
+Edward Lavender
+}
diff --git a/man/pf_kud.Rd b/man/pf_kud.Rd
index 35db1d5..cf1b624 100644
--- a/man/pf_kud.Rd
+++ b/man/pf_kud.Rd
@@ -117,12 +117,14 @@ pf_kud_1(out_dcpf_particles_1,
          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
@@ -149,6 +151,7 @@ pf_kud_1(out_dcpf_particles_1,
          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,
@@ -157,6 +160,7 @@ pf_kud_1(out_dcpf_paths,
          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
diff --git a/man/xy_from_click.Rd b/man/xy_from_click.Rd
new file mode 100644
index 0000000..5b3b994
--- /dev/null
+++ b/man/xy_from_click.Rd
@@ -0,0 +1,24 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/spatial_tools.R
+\name{xy_from_click}
+\alias{xy_from_click}
+\title{Get location coordinates from mouse click(s)}
+\usage{
+xy_from_click()
+}
+\value{
+The function returns a two-column matrix with coordinates.
+}
+\description{
+This function defines a two-column matrix of x, y coordinates from clicked locations on a map.
+}
+\examples{
+\dontrun{
+raster::plot(dat_gebco)
+xy <- xy_from_click()
+graphics::points(xy, col = "red")
+}
+}
+\author{
+Edward Lavender
+}