Add new acdc_access_*() functions.

NAMESPACE

@@ -3,8 +3,10 @@
 export("%>%")
 export(ac)
 export(acdc)
+export(acdc_access_dat)
+export(acdc_access_maps)
+export(acdc_access_timesteps)
 export(acdc_animate_record)
-export(acdc_helper_access_timesteps)
 export(acdc_plot_record)
 export(acdc_simplify)
 export(acs_setup_centroids)

R/acdc_analyse_record.R

@@ -24,31 +24,75 @@ check_class_acdc_record <- function(x, arg = deparse(substitute(x))){
 
 ######################################
 ######################################
-#### acdc_helper_access_*()
+#### acdc_access_*()
 
 #' @title Short-cuts to elements of an \code{"acdc_record"} object
 #' @description These functions provide short-cuts to elements of an \code{\link[flapper]{acdc_record-class}} object.
+#'
 #' @param record An \code{\link[flapper]{acdc_record-class}} object.
+#' @param type For \code{\link[flapper]{acdc_access_maps}}, \code{type} is a character that specifies whether or not to access time step-specific maps (\code{type = "map_timestep"}) or  cumulative maps (\code{type = "map_cumulative"}).
+#' @param select (optional) For \code{\link[flapper]{acdc_access_maps}}, \code{select} is an integer vector that defines the cumulative time steps (i.e., accounting for both primary (acoustic) and secondary (archival) time steps) for which maps are required.
+#'
 #' @details
 #' \itemize{
-#'   \item \code{\link[flapper]{acdc_helper_access_timesteps}} gets the total number of time steps from an AC* algorithm implementation.
+#'   \item \code{\link[flapper]{acdc_access_dat}} accesses the \code{record$dat} elements of an \code{\link[flapper]{acdc_record-class}} object for all time steps.
+#'   \item \code{\link[flapper]{acdc_access_timesteps}} accesses the total number of time steps stored in an \code{\link[flapper]{acdc_record-class}} object, accounting for both primary (acoustic) and secondary (archival) time steps.
+#'   \item \code{\link[flapper]{acdc_access_maps}} accesses all, or specified, maps from the \code{record$spatial} elements of an \code{\link[flapper]{acdc_record-class}} object.
+#' }
+#'
+#' @return
+#' \itemize{
+#'   \item \code{\link[flapper]{acdc_access_dat}} returns a single dataframe for all time steps.
+#'   \item \code{\link[flapper]{acdc_access_timesteps}} returns an integer that defines the total number of time steps.
+#'   \item \code{\link[flapper]{acdc_access_maps}} returns a single list of time-step specific or cumulative maps for specified or all time steps.
 #' }
 #'
 #' @examples
-#' #### Example (1): acdc_helper_access_timesteps()
-#' acdc_helper_access_timesteps(acdc_simplify(dat_acdc))
+#' #### Example (1): acdc_access_dat()
+#' acdc_access_dat(acdc_simplify(dat_acdc))
+#'
+#' #### Example (2): acdc_access_timesteps()
+#' acdc_access_timesteps(acdc_simplify(dat_acdc))
+#'
+#' #### Example (3): acdc_access_maps()
+#' acdc_access_maps(acdc_simplify(dat_acdc))
 #'
 #' @author Edward Lavender
-#' @name acdc_helper_access
+#' @name acdc_access
 NULL
 
-#### acdc_helper_access_timesteps()
-#' @rdname acdc_helper_access
+#### acdc_access_dat()
+#' @rdname acdc_access
+#' @export
+
+acdc_access_dat <- function(record){
+  check_class_acdc_record(record)
+  dat <- lapply(record$record, function(record_elm) record_elm$dat)
+  dat <- do.call(rbind, dat)
+  return(dat)
+}
+
+#### acdc_access_timesteps()
+#' @rdname acdc_access
 #' @export
 
-acdc_helper_access_timesteps <- function(record){
+acdc_access_timesteps <- function(record){
   check_class_acdc_record(record)
-  record$record[[length(record$record)]]$dat$timestep_cumulative
+  max(record$record[[length(record$record)]]$dat$timestep_cumulative)
+}
+
+#### acdc_access_maps()
+#' @rdname acdc_access
+#' @export
+
+acdc_access_maps <- function(record, type = c("map_timestep", "map_cumulative"), select = NULL){
+  check_class_acdc_record(record)
+  maps <- lapply(record$record, function(record_elm){
+    lapply(record_elm$spatial, function(spatial_elm) spatial_elm$map_cumulative)
+  })
+  maps <- unlist(maps)
+  if(!is.null(select)) maps <- maps[select]
+  return(maps)
 }
 
 

R/acdc_classes.R

@@ -28,7 +28,7 @@
 #'
 #' For the DC algorithm, \code{record$dat} contains the \code{archival} data for the time step, as inputted, with the following additional columns:
 #' \itemize{
-#'   \item `index' is a cumulative integer that defines the time step;
+#'   \item `timestep_cumulative' is a cumulative integer that defines the time step;
 #'   \item `depth_lwr' is a number that defines the lower bound for the individual's possible depth on the bathymetry layer (\code{bathy}) given the depth error model (\code{calc_depth_error});
 #'   \item `depth_upr' is a number that defines the upper bound for the individual's possible depth on the bathymetry layer (\code{bathy}) given the depth error model (\code{calc_depth_error});
 #'   \item `availability' is a logical variable that defines whether or not there were any cells on the bathymetry layer (\code{bathy}) within the boundaries for the individual's depth at that time step;

R/dc.R

@@ -253,11 +253,11 @@ dc <- function(archival,
 
   #### Set up objects for algorithm
   ## Archival index (for saving the spatial record)
-  if(rlang::has_name(archival, "index")) {
-    warning("'archival$index overwritten.", immediate. = TRUE, call. = FALSE)
+  if(rlang::has_name(archival, "timestep_cumulative")) {
+    warning("'archival$timestep_cumulative overwritten.", immediate. = TRUE, call. = FALSE)
   }
-  archival$index <- 1:nrow(archival)
-  if(is.null(save_record_spatial)) save_record_spatial <- archival$index
+  archival$timestep_cumulative <- 1:nrow(archival)
+  if(is.null(save_record_spatial)) save_record_spatial <- archival$timestep_cumulative
   ## Archival time series with depth error
   cat_to_cf("... Implementing calc_depth_error()...")
   archival$depth_lwr <- archival$depth + calc_depth_error(archival$depth)[1, ]
@@ -315,14 +315,14 @@ dc <- function(archival,
       if(normalise) avail <- avail/raster::cellStats(avail, "sum")
       if(!is.null(write_record_spatial_for_pf)){
         write_record_spatial_for_pf$x <- avail
-        write_record_spatial_for_pf$filename <- paste0(write_record_spatial_for_pf_dir, "arc_", d$index[i])
+        write_record_spatial_for_pf$filename <- paste0(write_record_spatial_for_pf_dir, "arc_", d$timestep_cumulative[i])
         do.call(raster::writeRaster, write_record_spatial_for_pf)
       }
       use <- use + avail
       .out$record[[i]] <- list(dat = d[i, , drop = FALSE],
                                spatial = list())
       if(save_record_spatial[1] != 0) {
-        if(d$index[i] %in% save_record_spatial){
+        if(d$timestep_cumulative[i] %in% save_record_spatial){
           .out$record[[i]]$spatial[[1]] <- list(map_timestep = avail, map_cumulative = use)
         }
       }

R/flapper-package.R

@@ -118,8 +118,13 @@
 #'          }
 #'      \item AC/DC processing
 #'      \itemize{
-#'         \item \link{acdc_simplify} simplifies the results of the algorithm(s);
-#'         \item \link{acdc_helper_access_timesteps} accesses the total number of time steps from an AC* algorithm implementation;
+#'         \item \link{acdc_simplify} simplifies \link{acdc_archive-class} objects into \link{acdc_record-class} objects;
+#'         \item \link{acdc_access} functions provide short-cuts to different elements of \link{acdc_record-class} objects:
+#'           \itemize{
+#'              \item \link{acdc_access_dat} accesses stored dataframes;
+#'              \item \link{acdc_access_timesteps} accesses the total number of time steps;
+#'              \item \link{acdc_access_maps} accesses stored maps;
+#'           }
 #'         \item \link{acdc_plot_record} plots the results of the algorithm(s);
 #'         \item \link{acdc_animate_record} creates html animations of the algorithm(s);
 #'         }

README.Rmd

@@ -193,12 +193,13 @@ The `flapper` family-equivalent of the COA algorithm is the acoustic-contour (AC
 
 The AC/DC branch functions (`ac()`, `dc()` and `acdc()`) all return objects of class `acdc_archive`. These can be processed and analysed using several key functions: 
 
-* `acdc_simplify()` simplifies the results of the AC/DC algorithm(s); 
-* `acdc_helper_*()` functions provide simple 'helper' routines for working with simplified outputs: 
-    * `acdc_helper_access_*()` functions provide short-cuts to different elements of the output:
-      * `acdc_helper_access_timesteps()` accesses the total number of time steps from an AC* algorithm implementation;
-* `acdc_plot_record()` plots the results of the AC/DC algorithm(s); 
-* `acdc_animate_record()` creates html animations of the AC/DC algorithm(s); 
+* `acdc_simplify()` simplifies `acdc_archive-class` objects into `acdc_record-class` objects; 
+* `acdc_access_*()` functions provide short-cuts to different elements of `acdc_record-class` objects:
+    * `acdc_access_dat()` accesses stored dataframes; 
+    * `acdc_access_timesteps()` accesses the total number of time steps;
+    * `acdc_access_maps()` accesses stored maps; 
+* `acdc_plot_record()` plots the results of the algorithm(s); 
+* `acdc_animate_record()` creates html animations of algorithm(s); 
 
 ### Particle filtering branch algorithms 
 

README.md

@@ -397,16 +397,16 @@ The AC/DC branch functions (`ac()`, `dc()` and `acdc()`) all return
 objects of class `acdc_archive`. These can be processed and analysed
 using several key functions:
 
-  - `acdc_simplify()` simplifies the results of the AC/DC algorithm(s);
-  - `acdc_helper_*()` functions provide simple ‘helper’ routines for
-    working with simplified outputs:
-      - `acdc_helper_access_*()` functions provide short-cuts to
-        different elements of the output:
-          - `acdc_helper_access_timesteps()` accesses the total number
-            of time steps from an AC\* algorithm implementation;
-  - `acdc_plot_record()` plots the results of the AC/DC algorithm(s);
-  - `acdc_animate_record()` creates html animations of the AC/DC
-    algorithm(s);
+  - `acdc_simplify()` simplifies `acdc_archive-class` objects into
+    `acdc_record-class` objects;
+  - `acdc_access_*()` functions provide short-cuts to different elements
+    of `acdc_record-class` objects:
+      - `acdc_access_dat()` accesses stored dataframes;
+      - `acdc_access_timesteps()` accesses the total number of time
+        steps;
+      - `acdc_access_maps()` accesses stored maps;
+  - `acdc_plot_record()` plots the results of the algorithm(s);
+  - `acdc_animate_record()` creates html animations of algorithm(s);
 
 ### Particle filtering branch algorithms