Continue acdc* documentation updates.

R/acdc_analyse_record.R

@@ -102,11 +102,11 @@ acdc_access_maps <- function(record, type = c("map_timestep", "map_cumulative"),
 #### acdc_plot_trace()
 
 #' @title Plot AC* container dynamics
-#' @description This function visually reconstructs the dynamics of an acoustic-container algorithm (i.e., \code{\link[flapper]{ac}} or \code{\link[flapper]{acdc}}).
+#' @description This function visually reconstructs the dynamics of an acoustic-container* (AC*) algorithm (i.e., \code{\link[flapper]{ac}} or \code{\link[flapper]{acdc}}).
 #'
 #' To implement the function, an \code{\link[flapper]{acdc_record-class}} object (\code{record}) from \code{\link[flapper]{ac}} or \code{\link[flapper]{acdc}} plus \code{\link[flapper]{acdc_simplify}} that defines the outputs of the AC* algorithm is required. A \code{\link[sp]{SpatialPointsDataFrame}} that defines receiver locations and a matrix that defines the daily operational status of each receiver are also required.
 #'
-#' For each time step, the function plots the location-probability surface, the receiver(s) at which the individual was detected and the acoustic containers, illustrating how the expansion, contraction and intersection of acoustic containers capture the boundaries of an individual's location through time.
+#' For each time step, the function plots the probability surface, the receiver(s) at which the individual was detected and the acoustic containers, illustrating how the expansion, contraction and intersection of acoustic containers capture the set of possible locations for an individual through time.
 #'
 #' @param record A \code{\link[flapper]{acdc_record-class}} object from \code{\link[flapper]{ac}} or \code{\link[flapper]{acdc}} plus \code{\link[flapper]{acdc_simplify}}.
 #' @param plot An integer vector that defines the time steps for which to make plots. If \code{plot = NULL}, the function will make a plot for all time steps for which the necessary information is available in \code{record}.
@@ -122,7 +122,7 @@ acdc_access_maps <- function(record, type = c("map_timestep", "map_cumulative"),
 #' @param png_param (optional) A named list of arguments, passed to \code{\link[grDevices]{png}}, to save plots to file. If supplied, the plot for each time step is saved separately. The `filename' argument should be the directory in which plots are saved. Plots are then saved as "1.png", "2.png" and so on. If supplied, \code{prompt} is ignored (see below).
 #' @param prompt If \code{png_param} is not specified, \code{prompt} is a logical variable that defines whether or not to pause function execution between plots and between containers within plots to facilitate interpretation.
 #'
-#' @return The function returns, for each time step, a plot of the location-probability surface and acoustic containers.
+#' @return The function returns, for each time step, a plot of the probability surface and acoustic containers.
 #'
 #' @examples
 #' #### Prepare example AC algorithm outputs with spatial files
@@ -454,14 +454,14 @@ acdc_plot_trace <- function(record,
 #### acdc_plot_record()
 
 #' @title Plot time-specific maps from the AC/DC algorithm(s)
-#' @description This function is used to plot time-specific maps from the AC/DC algorithm(s). To implement the function, an \code{\link[flapper]{acdc_record-class}} list from \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} or \code{\link[flapper]{acdc}} plus \code{\link[flapper]{acdc_simplify}} must be supplied, from which the results can be extracted and plotted for specified time steps. For each time step, the function extracts the necessary information; sets up a blank background plot using \code{\link[raster]{plot}} and \code{\link[prettyGraphics]{pretty_axis}} and then adds requested spatial layers to this plot. Depending on user-inputs, this will usually show a cumulative map of where the individual could have spent more or less time, summed from the start of the algorithm to each time point. Coastline, receivers and acoustic containers (if applicable) can be added and customised and the finalised plots can be returned or saved to file.
+#' @description This function is used to plot time-specific maps from the AC/DC algorithm(s). To implement the function, an \code{\link[flapper]{acdc_record-class}} list from \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} or \code{\link[flapper]{acdc}} plus \code{\link[flapper]{acdc_simplify}} must be supplied, from which the results can be extracted and plotted for specified time steps. For each time step, the function extracts the necessary information; sets up a blank background plot using \code{\link[raster]{plot}} and \code{\link[prettyGraphics]{pretty_axis}} and then adds requested spatial layers to this plot. Depending on user-inputs, this will usually show a cumulative map of expected time spent in different parts of the study area (from the start of the algorithm to each time point). Coastline, receivers and acoustic containers (if applicable) can be added and customised and the finalised plots can be returned or saved to file.
 #' @param record An \code{\link[flapper]{acdc_record-class}} object.
 #' @param type A character that defines the plotted surface(s): \code{"map_cumulative"} plots the cumulative surface and \code{"map_timestep"} plots time step-specific surfaces.
 #' @param plot An integer vector that defines the time steps for which to make plots. If \code{plot = NULL}, the function will make a plot for all time steps for which the necessary information is available in \code{record}.
 #' @param add_coastline (optional) A named list of arguments, passed to \code{\link[raster]{plot}}, to add a polygon (i.e., of the coastline), to the plot. If provided, this must contain an `x' element that contains the coastline as a spatial object (e.g., a SpatialPolygonsDataFrame: see \code{\link[flapper]{dat_coast}} for an example).
 #' @param add_receivers (optional) A named list of arguments, passed to \code{\link[graphics]{points}}, to add points (i.e., receivers) to the plot. If provided, this must contain an `x' element that is a SpatialPoints object that specifies receiver locations (in the same coordinate reference system as other spatial data).
 #' @param add_raster (optional) A named list of arguments, passed to \code{\link[fields]{image.plot}}, to plot the RasterLayer of possible locations that is extracted from \code{record}.
-#' @param add_containers (optional) For outputs from the AC* algorithms (\code{\link[flapper]{ac}} or \code{\link[flapper]{acdc}}), \code{containers} is a named list of arguments, passed to \code{\link[raster]{plot}}, to add the acoustic container to the plot.
+#' @param add_containers (optional) For outputs from the AC* algorithms (\code{\link[flapper]{ac}} or \code{\link[flapper]{acdc}}), \code{containers} is a named list of arguments, passed to \code{\link[raster]{plot}}, to add the acoustic containers to the plot.
 #' @param add_additional (optional) A stand-alone function, to be executed after the background plot has been made and any specified spatial layers have been added to this, to customise the result (see Examples).
 #' @param crop_spatial A logical variable that defines whether or not to crop spatial data to lie within the axis limits.
 #' @param xlim,ylim,fix_zlim,pretty_axis_args Axis control arguments. \code{xlim} and \code{ylim} control the axis limits, following the rules of the \code{lim} argument in \code{\link[prettyGraphics]{pretty_axis}}. \code{fix_zlim} is a logical input that defines whether or not to fix z axis limits across all plots (to facilitate comparisons), or a vector of two numbers that define a custom range for the z axis which is fixed across all plots. \code{fix_zlim = FALSE} produces plots in which the z axis is allowed to vary flexibly between time units. Other axis options supported by \code{\link[prettyGraphics]{pretty_axis}} are implemented by passing a named list of arguments to this function via \code{pretty_axis_args}.

R/acdc_classes.R

@@ -5,9 +5,9 @@
 #' @title "acdc_record" class
 #' @description An S3 class that defines the object returned by an acoustic-container/depth-contour (AC/DC) algorithm (\code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} or \code{\link[flapper]{acdc}}), after simplification via \code{\link[flapper]{acdc_simplify}} or directly from internal routines.
 
-#' @return \subsection{A named list}{An "acdc_record" class object is a named list with the following elements: `map', `record', `time', `args', `chunks' and `simplify'. The main output element is the `map' RasterLayer that shows where the individual could have spent more or less time over the duration of the movement time series. The `record' element records time-specific maps of the possible locations of the individual, and can be used to plot maps of specific time points or to produce animations (for the time steps specified by the \code{save_record_spatial} argument). The `time' element is a dataframe that defines the times of sequential stages in the algorithm's progression, providing a record of computation time. The `args' element is a named list of user inputs that record the parameters used to generate the outputs (if \code{save_args = TRUE}, otherwise the `args' element is \code{NULL}). The `chunks' element is a list with chunk-specific information that is generated if the algorithm is implemented chunk-wise and then simplified via \code{\link[flapper]{acdc_simplify}} with the \code{keep_chunks = TRUE} argument. The \code{simplify} element is a logical value that defines whether or not the object was created from \code{\link[flapper]{ac}}/\code{\link[flapper]{dc}}/\code{\link[flapper]{acdc}} and \code{\link[flapper]{acdc_simplify}} or an internal routine. Below, more detail about the `map' and `record' elements is provided.}
+#' @return \subsection{A named list}{An "acdc_record" class object is a named list with the following elements: `map', `record', `time', `args', `chunks' and `simplify'. The main output element is the `map' RasterLayer that shows the expecte time spent in different parts of the study area over the duration of the movement time series. The `record' element records time-specific maps of the possible locations of the individual, and can be used to plot maps of specific time points or to produce animations (for the time steps specified by the \code{save_record_spatial} argument). The `time' element is a dataframe that defines the times of sequential stages in the algorithm's progression, providing a record of computation time. The `args' element is a named list of user inputs that record the parameters used to generate the outputs (if \code{save_args = TRUE}, otherwise the `args' element is \code{NULL}). The `chunks' element is a list with chunk-specific information that is generated if the algorithm is implemented chunk-wise and then simplified via \code{\link[flapper]{acdc_simplify}} with the \code{keep_chunks = TRUE} argument. The \code{simplify} element is a logical value that defines whether or not the object was created from \code{\link[flapper]{ac}}/\code{\link[flapper]{dc}}/\code{\link[flapper]{acdc}} and \code{\link[flapper]{acdc_simplify}} or an internal routine. Below, more detail about the `map' and `record' elements is provided.}
 #'
-#' \subsection{(A) `map'}{This is a RasterLayer that defines the locations in which an individual could have been (or was not), given the movement time series. Each cell is a count of the number of times when the acoustic and/or archival data were compatible with the individual having been in that cell, given the algorithm (unless normalisation has been implemented via \code{normalise = TRUE} in the algorithm or in  post-processing via \code{\link[flapper]{acdc_simplify}}). This provides an overall measure of the locations in which an individual could have spent more or less time, but not where it was.}
+#' \subsection{(A) `map'}{This is a RasterLayer that defines the locations in which an individual could have been (or was not), given the movement time series. The value in each cell defines the expected proportion of time steps in which the individual could have occupied that location (assuming normalisation has been implemented) given given the algorithm.}
 #'
 #' \subsection{(B) `record'}{This is a temporal record of the possible locations of each individual, with one element for each primary time step. For the AC* algorithms (\code{\link[flapper]{ac}} and \code{\link[flapper]{acdc}}), the `primary time step' refers to acoustic time steps; for the DC algorithm (\code{\link[flapper]{dc}}), the `primary time step' refers to archival time steps. Each element contains (a) a dataframe with the information for that time step and (b) a list of spatial objects, one for each `secondary time step' that record spatial outputs of the algorithm, as specified by \code{save_record_spatial} (see below). For the AC* algorithms, `secondary time steps' are the time steps in-between acoustic observations; for the DC algorithm, primary and secondary time steps are the same.}
 #'
@@ -38,8 +38,8 @@
 #'
 #' \subsection{(ii) record$spatial}{If \code{save_record_spatial > 0}, then for those time steps specified by \code{save_record_spatial}, each element in `record' contains a `spatial' list, with one element for each secondary time stamp, that records spatial information pertaining to the possible locations of the individual at that time step. For all algorithms, each `spatial' list includes the following elements:
 #' \itemize{
-#'   \item `map_timestep' is a RasterLayer of all the positions that the individual could have occupied at that time step, given the algorithm;
-#'   \item `map_cumulative' is a RasterLayer of the cumulative of the number of times when the movement data were compatible with the individual being in that cell, under the specified algorithm, from all previous time steps up to the current time step (i.e., the sum of `map_timestep' across all time steps from the first time step to the current time step) (unless \code{normalise = TRUE} in which case the interpretation differs);
+#'   \item `map_timestep' is a RasterLayer that defines the probability that the individual occupied any given cell at a each time step;
+#'   \item `map_cumulative' is a RasterLayer that defines the expected number of time steps in which the individual could have occupied each cell (i.e., the sum of `map_timestep' across all time steps from the first time step to the current time step);
 #' }
 #' For the AC* algorithms, this list also includes information on the acoustic containers and location probability:
 #' \itemize{

R/acdc_simplify.R

@@ -3,11 +3,11 @@
 #### acdc_simplify()
 
 #' @title Simplify the outputs of the AC/DC algorithms
-#' @description This function simplifies the output of \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} and \code{\link[flapper]{acdc}}, by processing information from the 'archive' elements of an \code{\link[flapper]{acdc_archive-class}} object that hold the results of calls to the workhorse routines. This is especially useful if the algorithm(s) have been applied chunk-wise, in which case the results for each chunk are returned in a list. The function aggregates information across chunks to generate a continuous time series of results and a map of where the individual could have spend more or less time over the entire time series.
+#' @description This function simplifies the output of \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} and \code{\link[flapper]{acdc}}, by processing information from the 'archive' elements of an \code{\link[flapper]{acdc_archive-class}} object that hold the results of calls to the workhorse routines. This is especially useful if the algorithm(s) have been applied chunk-wise, in which case the results for each chunk are returned in a list. The function aggregates information across chunks to generate a continuous time series of results and a map of the expected proportion of time steps spent in each grid cell.
 #' @param archive An \code{\link[flapper]{acdc_archive-class}} object returned by \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} or \code{\link[flapper]{acdc}}.
 #' @param type A character that defines whether the function should be implemented for the outputs of a call to an AC* algorithm (\code{\link[flapper]{ac}} or \code{\link[flapper]{acdc}}), in which case \code{type = "acs"}, or the DC algorithm (\code{\link[flapper]{dc}}), in which case \code{type = "dc"}.
 #' @param mask (optional) A spatial mask (e.g., the argument passed to \code{bathy} in \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} or \code{\link[flapper]{acdc}}) to mask areas (e.g., land) from the overall map. If implemented, cells in masked areas are assigned NAs rather than a score of 0.
-#' @param normalise A logical input that defines whether or not to normalise the overall map so that cell scores sum to one.
+#' @param normalise A logical input that defines whether or not to normalise the overall map so that cell scores sum to one. If \code{normalise = FALSE}, the overall map represents the expected number of time steps spent in each grid cell; if \code{normalise = TRUE}, the overall map represents the expected proportion of time steps spent in each grid cell.
 #' @param keep_chunks A logical variable that defines whether or not to retain all chunk-specific information.
 #' @return The function returns an object of class \code{\link[flapper]{acdc_record-class}}.
 #' @details If the \code{\link[flapper]{ac}}, \code{\link[flapper]{dc}} or \code{\link[flapper]{acdc}} function was implemented step-wise, this function simply extracts the necessary information and re-packages it into an \code{\link[flapper]{acdc_record-class}} object. For a chunk-wise implementation, the function (a) computes the map of where the individual could have spent more or less time by aggregating the chunk-specific maps) and (b) simplifies chunk-specific records into a single contiguous time series, with re-defined time stamps from the start to the end of the time series (for AC* algorithm(s)) to return an \code{\link[flapper]{acdc_record-class}} object.