From 56678e5c0bd9618064e913d28258b49e239e2509 Mon Sep 17 00:00:00 2001 From: Edward Lavender Date: Tue, 2 Feb 2021 16:11:43 +0000 Subject: [PATCH] Fix backwards ' issue in pdf (LaTeX) manual. --- R/acdc.R | 52 ++++++++++++++-------------- R/acdc_classes.R | 20 +++++------ R/assembles.R | 8 ++--- R/coa.R | 12 +++---- R/dats.R | 2 +- R/dc.R | 2 +- R/dists.R | 20 +++++------ R/evals.R | 4 +-- R/flapper-package.R | 6 ++-- R/get_detections.R | 30 ++++++++-------- R/kud_tools.R | 6 ++-- R/make_dfs.R | 4 +-- R/make_matrices.R | 22 ++++++------ R/processing.R | 20 +++++------ R/queries.R | 2 +- R/sims.R | 14 ++++---- R/spatial_tools.R | 4 +-- R/utils.R | 14 ++++---- man/acdc-class.Rd | 10 +++--- man/acdc.Rd | 10 +++--- man/acdc_animate.Rd | 18 +++++----- man/acdc_plot.Rd | 6 ++-- man/acdc_setup_mobility.Rd | 4 +-- man/acdc_setup_n_centroids.Rd | 6 ++-- man/assemble_sentinel_counts.Rd | 8 ++--- man/check....Rd | 2 +- man/check_class.Rd | 2 +- man/check_dir.Rd | 2 +- man/check_named_list.Rd | 2 +- man/check_names.Rd | 2 +- man/check_tz.Rd | 2 +- man/check_value.Rd | 2 +- man/coa.Rd | 4 +-- man/coa_setup_delta_t.Rd | 8 ++--- man/dat_moorings.Rd | 2 +- man/dc.Rd | 2 +- man/dist_btw_receivers.Rd | 4 +-- man/dot-acdc-class.Rd | 10 +++--- man/dot-acdc.Rd | 8 ++--- man/eval_by_kud.Rd | 4 +-- man/flapper.Rd | 6 ++-- man/get_detection_area_ts.Rd | 4 +-- man/get_detection_centroids.Rd | 2 +- man/get_detection_centroids_envir.Rd | 6 ++-- man/get_detection_days.Rd | 6 ++-- man/get_detection_pr.Rd | 2 +- man/get_id_rec_overlap.Rd | 8 ++--- man/get_n_operational_ts.Rd | 2 +- man/invert_poly.Rd | 2 +- man/kud_around_coastline.Rd | 6 ++-- man/lcp_over_surface.Rd | 16 ++++----- man/make_df_detections.Rd | 4 +-- man/make_matrix_cooccurence.Rd | 6 ++-- man/make_matrix_detections.Rd | 8 ++--- man/make_matrix_ids.Rd | 4 +-- man/make_matrix_receivers.Rd | 4 +-- man/process_false_detections_sf.Rd | 6 ++-- man/process_quality_check.Rd | 10 +++--- man/process_receiver_id.Rd | 4 +-- man/query_open_topo.Rd | 2 +- man/sim_array.Rd | 4 +-- man/sim_detections.Rd | 2 +- man/sim_path_ou_1.Rd | 6 ++-- man/sim_path_sa.Rd | 2 +- man/split_raster_equally.Rd | 2 +- 65 files changed, 242 insertions(+), 242 deletions(-) diff --git a/R/acdc.R b/R/acdc.R index 571eccc..e528f98 100644 --- a/R/acdc.R +++ b/R/acdc.R @@ -2,8 +2,8 @@ ###################################### #### acdc_setup_mobility() -#' @title Examine the constant 'mobility' assumption of the ACDC algorithm -#' @description In the simplest and fastest (and only) version of the ACDC algorithm currently implemented by \code{\link[flapper]{flapper}}, the rate at which acoustic centroids expand and contract depends on a single 'mobility' parameter that describes how the uncertainty in an individual's location changes through time according to the passive acoustic telemetry data. These changes essentially reflect the maximum horizontal distance that an individual can move in the time period between archival observations. However, in some situations, a fixed parameter for horizontal movement may not be well supported by archival data, particularly for animals that change dramatically in depth and for which changes in depth are likely to curtail the extent of horizontal movement*. Thus, this function investigates the extent to which the horizontal distance an animal could travel changes through time if the mobility parameter is instead conceptualised as the diagonal distance between sequential depth observations. +#' @title Examine the constant `mobility' assumption of the ACDC algorithm +#' @description In the simplest and fastest (and only) version of the ACDC algorithm currently implemented by \code{\link[flapper]{flapper}}, the rate at which acoustic centroids expand and contract depends on a single `mobility' parameter that describes how the uncertainty in an individual's location changes through time according to the passive acoustic telemetry data. These changes essentially reflect the maximum horizontal distance that an individual can move in the time period between archival observations. However, in some situations, a fixed parameter for horizontal movement may not be well supported by archival data, particularly for animals that change dramatically in depth and for which changes in depth are likely to curtail the extent of horizontal movement*. Thus, this function investigates the extent to which the horizontal distance an animal could travel changes through time if the mobility parameter is instead conceptualised as the diagonal distance between sequential depth observations. #' #' @param depth A vector of depth observations, whose units match the \code{mobility} parameter, to be incorporated into the ACDC algorithm. (Note that the ACDC algorithm may drop depth observations internally depending on their alignment with the acoustic time series and so, ideally, pre-processed time series should be passed to \code{depth} to ensure inferences correspond directly to the time series modelled by \code{\link[flapper]{acdc}}.) Depth observations should be regularly spaced in time (i.e., represent a time series for a single individual, without gaps). #' @param mobility A number, in the same units as \code{depth}, that defines the maximum horizontal distance that an individual could move in the time period between archival observations (see \code{\link[flapper]{acdc_setup_centroids}}). @@ -116,7 +116,7 @@ acdc_setup_mobility <- function(depth, #' @description The ACDC algorithm requires a list of acoustic centroids from \code{\link[flapper]{acdc_setup_centroids}}. The number of centroids that is required depends on (a) the duration between detections; (b) the distances among receivers; (c) the area of interest; and (d) other considerations such as the spatial extent and resolution of the bathymetry data that is required by the ACDC algorithm and presence or absence of a long tail of archival observations after the final acoustic detection. This function implements two approaches to facilitate a sensible choice of the number of centroids for the ACDC algorithm (see Details). This ensures that the number of centroids is sufficient to cover requirements but not so large that the centroids become slow to compute and unwieldy. The function requires a time series of detections, the deployment details of passive acoustic telemetry receivers and a mobility parameter. Given these inputs, the function returns a suggested upper and lower bound for the number of centroids. #' #' @param detections A POSIXct vector of time stamps when detections were made (for a particular individual). -#' @param moorings A dataframe that defines passive acoustic telemetry receiver locations and deployment periods. This must contain the following columns: 'receiver_id', a unique identifier of each receiver; 'receiver_lat' and 'receiver_long', the latitude and longitude of each receiver in decimal degrees; and 'receiver_start_date' and 'receiver_end_date', the start and end time of each receiver's deployment period (see \code{\link[flapper]{dat_moorings}} for an example). +#' @param moorings A dataframe that defines passive acoustic telemetry receiver locations and deployment periods. This must contain the following columns: `receiver_id', a unique identifier of each receiver; `receiver_lat' and `receiver_long', the latitude and longitude of each receiver in decimal degrees; and `receiver_start_date' and `receiver_end_date', the start and end time of each receiver's deployment period (see \code{\link[flapper]{dat_moorings}} for an example). #' @param mobility A number that defines the distance (m) that an individual could move in the time period between archival observations (see also \code{\link[flapper]{acdc_setup_centroids}}). #' @param double A logical variable that defines whether or not to double the minimum number of centroids given by approach two (see Details). #' @param hist A logical value that defines whether or not to plot the distribution of gaps across the detection time series as a histogram. @@ -129,9 +129,9 @@ acdc_setup_mobility <- function(depth, #' #' \subsection{Other considerations}{In practice, the most appropriate number of centroids is likely to be a compromise between these minimum and maximum values that depends on other considerations, particularly the spatial scale of the study, the effect of boundaries on the final centroid size and, perhaps in some cases, the geographical range of the species. For acoustic time series that are followed by a long tail of archival observations after final acoustic detection, both approaches may underestimate the number of centroids required to capture the increasing uncertainty in the individual's location over this time. However, in this case, it is advisable to use the depth-contour (DC) algorithm (see \code{\link[flapper]{dc}}) at some point after the last acoustic detection since the influence of that observation on putative patterns of space use will decay through time and the DC algorithm is more computationally efficient.} #' -#' @return The function returns an integer vector with the upper and lower suggested value for the number of centroids from methods (1) and (2). The parameters used to generate these suggestions (i.e., \code{detections}, \code{moorings}, \code{mobility} and \code{double}) are also included in a 'param' attribute. +#' @return The function returns an integer vector with the upper and lower suggested value for the number of centroids from methods (1) and (2). The parameters used to generate these suggestions (i.e., \code{detections}, \code{moorings}, \code{mobility} and \code{double}) are also included in a `param' attribute. #' -#' @seealso This function is designed to facilitate an informed choice for the 'n_timesteps' argument in \code{\link[flapper]{acdc_setup_centroids}}. \code{\link[flapper]{acdc_setup_mobility}} can also guide the implementation of this function. This underpins the ACDC algorithm, which is implemented by \code{\link[flapper]{acdc}}. +#' @seealso This function is designed to facilitate an informed choice for the `n_timesteps' argument in \code{\link[flapper]{acdc_setup_centroids}}. \code{\link[flapper]{acdc_setup_mobility}} can also guide the implementation of this function. This underpins the ACDC algorithm, which is implemented by \code{\link[flapper]{acdc}}. #' #' @examples #' n_timesteps <- @@ -430,8 +430,8 @@ acdc_setup_centroids <- function( #' @title Back-end implementation of the ACDC algorithm #' @description This function is the back-end of the ACDC algorithm. -#' @param acoustics A dataframe that contains passive acoustic telemetry detection time series for a specific individual (see \code{\link[flapper]{dat_acoustics}} for an example). This should contain the following columns: an integer vector of receiver IDs, named 'receiver_id' (that must match that inputted to the \code{rs} argument of \code{\link[flapper]{acdc_setup_centroids}}); a POSIXct vector of time stamps when detections were made, named 'timestamp'; and a numeric vector of those time stamps, named 'timestamp_num'. -#' @param archival A dataframe that contains depth time series for the same individual (see \code{\link[flapper]{dat_archival}} for an example). This should contain the following columns: a numeric vector of observed depths, named 'depth'; a POSIXct vector of time stamps when observations were made, named 'timestamp'; and a numeric vector of those time stamps, named 'timestamp_num'. Depths should be recorded in the same units and with the same sign as the bathymetry data (see \code{bathy}). Absolute depths (m) are suggested. Unlike the detection time series, archival time stamps are assumed to have occurred at regular intervals. Two-minute intervals are currently assumed. +#' @param acoustics A dataframe that contains passive acoustic telemetry detection time series for a specific individual (see \code{\link[flapper]{dat_acoustics}} for an example). This should contain the following columns: an integer vector of receiver IDs, named `receiver_id' (that must match that inputted to the \code{rs} argument of \code{\link[flapper]{acdc_setup_centroids}}); a POSIXct vector of time stamps when detections were made, named `timestamp'; and a numeric vector of those time stamps, named `timestamp_num'. +#' @param archival A dataframe that contains depth time series for the same individual (see \code{\link[flapper]{dat_archival}} for an example). This should contain the following columns: a numeric vector of observed depths, named `depth'; a POSIXct vector of time stamps when observations were made, named `timestamp'; and a numeric vector of those time stamps, named `timestamp_num'. Depths should be recorded in the same units and with the same sign as the bathymetry data (see \code{bathy}). Absolute depths (m) are suggested. Unlike the detection time series, archival time stamps are assumed to have occurred at regular intervals. Two-minute intervals are currently assumed. #' @param bathy A \code{\link[raster]{raster}} that defines the bathymetry across the area within which the individual could have moved. This must be recorded in the same units and with the same sign as the depth observations (see \code{archival}). The coordinate reference system should be the Universal Transverse Mercator system, with distances in metres (see also \code{\link[flapper]{acdc_setup_centroids}}). #' @param map (optional) A blank \code{\link[raster]{raster}}, with the same properties (i.e., dimensions, resolution, extent and coordinate reference system) as the bathymetry raster (see \code{bathy}), but in which all values are 0. If \code{NULL}, this is computed internally, but supplying a pre-defined raster can be more computationally efficient if the function is applied iteratively (e.g., over different time windows). #' @param detection_range A number that defines the maximum detection range (m) at which an individual could be detected from a receiver (see also \code{\link[flapper]{acdc_setup_centroids}}). @@ -447,9 +447,9 @@ acdc_setup_centroids <- function( #' @param keep_args A logical input that defines whether or not to include a list of function arguments in the outputs. This can be switched off if the function is applied iteratively. #' @param ... Additional arguments (none implemented). #' -#' @return The function returns a \code{\link[flapper]{.acdc-class}} object 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 information on 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 \code{plot}). 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{keep_args = TRUE}, otherwise the 'args' element is \code{NULL}). +#' @return The function returns a \code{\link[flapper]{.acdc-class}} object 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 information on 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 \code{plot}). 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{keep_args = TRUE}, otherwise the `args' element is \code{NULL}). #' -#' @seealso \code{\link[flapper]{acdc_setup_centroids}} defines the acoustic centroids required by this function, aided by \code{\link[flapper]{acdc_setup_centroids}}. \code{\link[flapper]{acdc_setup_mobility}} is used to examine the assumption of the constant 'mobility' parameter. \code{\link[flapper]{acdc}} is the front-end of the algorithm. \code{\link[flapper]{acdc_plot}} and \code{\link[flapper]{acdc_animate}} visualise the results. +#' @seealso \code{\link[flapper]{acdc_setup_centroids}} defines the acoustic centroids required by this function, aided by \code{\link[flapper]{acdc_setup_centroids}}. \code{\link[flapper]{acdc_setup_mobility}} is used to examine the assumption of the constant `mobility' parameter. \code{\link[flapper]{acdc}} is the front-end of the algorithm. \code{\link[flapper]{acdc_plot}} and \code{\link[flapper]{acdc_animate}} visualise the results. #' #' @examples #' #### Step (1) Implement setup_acdc_*() steps @@ -996,8 +996,8 @@ acdc_setup_centroids <- function( #' #' Under the default options, the approach is implemented step-wise (i.e., step-by-step across the whole time series). The result is a named list of outputs, including a record of the results for each time step, as well as a cumulative map of where the individual could have spent more or less time summed across the whole time series. Alternatively, the approach can be implemented chunk-wise, in which case the acoustic time series is split into chunks (e.g., hourly, daily, monthly segments) and the algorithm is implemented within each chunk step-by-step. The main benefits of this approach are that it can be used to reconstruct putative patterns in space use over biologically meaningful periods separately and/or the chunk-wise implementation can be parallelised, improving computation time. (Chunk-wise results results are easily combined across the duration of the original time series without the loss of information via \code{\link[flapper]{acdc_simplify}}.). This option is implemented if (a) a list, rather than a dataframe, of acoustic detections is provided (via \code{acoustics}); (b) the user specifies that the time series should be split into chunks of a particular duration before the algorithm is initiated (via the \code{split} argument); and/or (c) the algorithm is implemented on a cluster via \code{cl}, in which case the acoustic time series is split (if necessary) into user-defined or automatically defined chunks prior to computation. In this case, the result is a named list of outputs, as described above, but in which the results for each chunk are returned separately. If the chunks have been implemented simply to improve computation time via parallelisation, then the maps of space use for each chunk can be combined easily to generate a single, overall map of space use via \code{\link[flapper]{acdc_simplify}}. #' -#' @param acoustics A dataframe, or a list of dataframes, that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a single individual. Each dataframe should contain the following columns: an integer vector of receiver IDs, named 'receiver_id'; a POSIXct vector of time stamps when detections were made, named 'timestamp'; and a numeric vector of those time stamps, named 'timestamp_num'. If a list of dataframes is supplied, dataframes must be refer to the detections of a single individual and be ordered by time (e.g., in hourly chunks). The algorithm will be implemented on each dataframe, termed 'chunk', either in sequence or parallel. Any empty or NULL elements will be removed automatically. -#' @param archival A dataframe that contains depth time series (see \code{\link[flapper]{dat_archival}} for an example). This should contain the following columns: a numeric vector of observed depths, named 'depth'; a POSIXct vector of time stamps when observations were made, named 'timestamp'; and a numeric vector of those time stamps, named 'timestamp_num'. Depths should be recorded in the same units and with the same sign as the bathymetry data (see \code{bathy}). Absolute depths (m) are suggested. Unlike the detection time series, archival time stamps are assumed to have occurred at regular intervals. Two-minute intervals are currently assumed. +#' @param acoustics A dataframe, or a list of dataframes, that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a single individual. Each dataframe should contain the following columns: an integer vector of receiver IDs, named `receiver_id'; a POSIXct vector of time stamps when detections were made, named `timestamp'; and a numeric vector of those time stamps, named `timestamp_num'. If a list of dataframes is supplied, dataframes must be refer to the detections of a single individual and be ordered by time (e.g., in hourly chunks). The algorithm will be implemented on each dataframe, termed `chunk', either in sequence or parallel. Any empty or NULL elements will be removed automatically. +#' @param archival A dataframe that contains depth time series (see \code{\link[flapper]{dat_archival}} for an example). This should contain the following columns: a numeric vector of observed depths, named `depth'; a POSIXct vector of time stamps when observations were made, named `timestamp'; and a numeric vector of those time stamps, named `timestamp_num'. Depths should be recorded in the same units and with the same sign as the bathymetry data (see \code{bathy}). Absolute depths (m) are suggested. Unlike the detection time series, archival time stamps are assumed to have occurred at regular intervals. Two-minute intervals are currently assumed. #' @param bathy A \code{\link[raster]{raster}} that defines the bathymetry across the area within which the individual could have moved. This must be recorded in the same units and with the same sign as the depth observations (see \code{archival}). The coordinate reference system should be the Universal Transverse Mercator system, with distances in metres (see also \code{\link[flapper]{acdc_setup_centroids}}). #' @param map (optional) A blank \code{\link[raster]{raster}}, with the same properties (i.e., dimensions, resolution, extent and coordinate reference system) as the bathymetry raster (see \code{bathy}), but in which all values are 0. If \code{NULL}, this is computed internally, but supplying a pre-defined raster can be more computationally efficient if the function is applied iteratively (e.g., over multiple individuals). #' @param detection_range A number that defines the maximum detection range (m) at which an individual could be detected from a receiver (see also \code{\link[flapper]{acdc_setup_centroids}}). @@ -1017,13 +1017,13 @@ acdc_setup_centroids <- function( #' #' In outline, the crux of the approach is the recognition that acoustic detections typically occur irregularly, while archival observations occur at regular intervals. Each detection anchors our knowledge of the location of an individual around a particular receiver (assuming that all detections are true detections). As time passes between acoustic detections, our uncertainty about the geographical location of an individual expands around the receiver at which it was detected before shrinking towards the receiver at which it was next detected. During this time, regular depth observations restrict the number of possible locations in which the individual could have been located at each time step. #' -#' More specifically, when an individual is detected, it must be within some radius – say 800 m – of that receiver. This is the starting acoustic centroid. With a more-refined model of detection probability, it may be possible to predict more precisely where the individual is likely to have been within this centroid (but this approach is not yet implemented). The observed depth at this time further restricts the positions in which the individual could have been, assuming a benthic/demersal lifestyle and a non-homogenous bathymetric landscape. Moving forward in time, a number of depth records may be made before another acoustic detection. During this time, our uncertainty about where the individual could have been gets larger, because it could have moved further away from the receiver, so the acoustic centroids that define this uncertainty expand to a maximum size at the halfway point between acoustic detections. After that, the individual must have started to move towards the receiver at which it was next detected, so these acoustic centroids start to shrink towards that receiver. If the individual was detected by different receivers, the overlap between the centroids of these two receivers at the halfway point defines the set of positions in which the individual could have been at this time. Thereafter, our uncertainty in the individual’s location is given by the overlap between the expansion of this centroid region and the contraction of the centroid around the receiver at which it was next detected. Thus, when the individual is detected again, our uncertainty about where it could have been collapses to the detection radius around the next receiver, possibly weighted by a model of detection probability around this receiver (although that is not yet implemented). The rate of change in centroid size depends a movement parameter that describes an average swimming speed, which will depend on some underlying estimated behavioural state (although that is not yet implemented). +#' More specifically, when an individual is detected, it must be within some radius – say 800 m – of that receiver. This is the starting acoustic centroid. With a more-refined model of detection probability, it may be possible to predict more precisely where the individual is likely to have been within this centroid (but this approach is not yet implemented). The observed depth at this time further restricts the positions in which the individual could have been, assuming a benthic/demersal lifestyle and a non-homogenous bathymetric landscape. Moving forward in time, a number of depth records may be made before another acoustic detection. During this time, our uncertainty about where the individual could have been gets larger, because it could have moved further away from the receiver, so the acoustic centroids that define this uncertainty expand to a maximum size at the halfway point between acoustic detections. After that, the individual must have started to move towards the receiver at which it was next detected, so these acoustic centroids start to shrink towards that receiver. If the individual was detected by different receivers, the overlap between the centroids of these two receivers at the halfway point defines the set of positions in which the individual could have been at this time. Thereafter, our uncertainty in the individual's location is given by the overlap between the expansion of this centroid region and the contraction of the centroid around the receiver at which it was next detected. Thus, when the individual is detected again, our uncertainty about where it could have been collapses to the detection radius around the next receiver, possibly weighted by a model of detection probability around this receiver (although that is not yet implemented). The rate of change in centroid size depends a movement parameter that describes an average swimming speed, which will depend on some underlying estimated behavioural state (although that is not yet implemented). #' -#' The result is a map that shows where the individual could have spent more or less (or no) time over the time interval under construction. The main limitation of this approach is that reconstructs where the individual could have been, but not where it was. In reality, the individual’s current position constrains where it can go next. The ACDCPF/MP algorithms are extensions of this approach that incorporate a movement model for this reason. +#' The result is a map that shows where the individual could have spent more or less (or no) time over the time interval under construction. The main limitation of this approach is that reconstructs where the individual could have been, but not where it was. In reality, the individual's current position constrains where it can go next. The ACDCPF/MP algorithms are extensions of this approach that incorporate a movement model for this reason. #' #' @return The function returns a \code{\link[flapper]{acdc-class}} object. If a connection to write files has also been specified, an overall log (acdc_log.txt) as well as chunk-specific logs from calls to \code{\link[flapper]{.acdc}}, if applicable, are written to file. #' -#' @seealso The 'depth-contour' component of the algorithm can be implemented via \code{\link[flapper]{dc}}. For more information on the ACDC algorithm, see \code{\link[flapper]{acdc_setup_n_centroids}} and \code{\link[flapper]{acdc_setup_centroids}} which defined the acoustic centroids required by this function and \code{\link[flapper]{acdc_setup_mobility}} which examines the assumption of a constant 'mobility' parameter; \code{\link[flapper]{.acdc}}, the back-end workhorse of this function; \code{\link[flapper]{acdc_simplify}} which simplifies the outputs of the \code{\link[flapper]{acdc}} function; and \code{\link[flapper]{acdc_plot}} and \code{\link[flapper]{acdc_animate}}, which visualise the results. +#' @seealso The `depth-contour' component of the algorithm can be implemented via \code{\link[flapper]{dc}}. For more information on the ACDC algorithm, see \code{\link[flapper]{acdc_setup_n_centroids}} and \code{\link[flapper]{acdc_setup_centroids}} which defined the acoustic centroids required by this function and \code{\link[flapper]{acdc_setup_mobility}} which examines the assumption of a constant `mobility' parameter; \code{\link[flapper]{.acdc}}, the back-end workhorse of this function; \code{\link[flapper]{acdc_simplify}} which simplifies the outputs of the \code{\link[flapper]{acdc}} function; and \code{\link[flapper]{acdc_plot}} and \code{\link[flapper]{acdc_animate}}, which visualise the results. #' #' @examples #' #### Step (1) Implement setup_acdc_*() steps @@ -1696,15 +1696,15 @@ acdc_simplify <- function(acdc, keep_chunks = FALSE,...) { #' @description This function is used to plot time-specific maps from the ACDC algorithm. To implement the function, a \code{\link[flapper]{.acdc-class}} list from \code{\link[flapper]{acdc}} and \code{\link[flapper]{acdc_simplify}} (or \code{\link[flapper]{.acdc}}) 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 centroids can be added and customised and the finalised plots can be returned or saved to file. #' @param acdc An \code{\link[flapper]{.acdc-class}} object. #' @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{acdc}. -#' @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_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{acdc}. #' @param add_centroids (optional) A named list of arguments, passed to \code{\link[raster]{plot}}, to add the acoustic centroid 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}. #' @param par_param (optional) A named list of arguments, passed to \code{\link[graphics]{par}}, to control the plotting window. This is executed before plotting is initiated and therefore affects all plots. -#' @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. +#' @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. #' @param cl A cluster object created by \code{\link[parallel]{makeCluster}}. If supplied, the function loops over specified time steps in parallel to make plots. This is only implemented if plots are saved to file (i.e., \code{png_param} is supplied). If supplied, the connection to the cluster is closed within the function. #' @param verbose A logical variable that defines whether or not relay messages to the console to monitor function progress. #' @param check A logical variable that defines whether or not to check user inputs to the function before its initiation. @@ -2033,18 +2033,18 @@ acdc_plot <- function(acdc, #### acdc_animate() #' @title Create a html animation of the ACDC algorithm -#' @description This function is a simple wrapper for \code{\link[flapper]{acdc_plot}} and \code{\link[animation]{saveHTML}} which creates an animation of the ACDC algorithm over time. To implement this function, a named list of arguments for \code{\link[flapper]{acdc_plot}}, which creates the plots, must be supplied. This is embedded within \code{\link[animation]{saveHTML}}, which creates a folder in the working directory named 'images' that contains a .png file for each time step and an animation as a .html file. +#' @description This function is a simple wrapper for \code{\link[flapper]{acdc_plot}} and \code{\link[animation]{saveHTML}} which creates an animation of the ACDC algorithm over time. To implement this function, a named list of arguments for \code{\link[flapper]{acdc_plot}}, which creates the plots, must be supplied. This is embedded within \code{\link[animation]{saveHTML}}, which creates a folder in the working directory named `images' that contains a .png file for each time step and an animation as a .html file. #' @param expr_param A named list of arguments, passed to \code{\link[flapper]{acdc_plot}}, to create plots. -#' @param html_name A string that defines the name of the html file (see 'htmlfile' argument in \code{\link[animation]{saveHTML}}). -#' @param image_name A string that defines the names of the individual .png files creates (see 'img.name' argument in \code{\link[animation]{saveHTML}}). -#' @param html_title,html_description Character strings that provide a title and a description that are displayed within the html animation (see 'title' and 'description' arguments in \code{\link[animation]{saveHTML}}). -#' @param navigator A logical variable that defines whether or not to add a navigator panel to the animation (see 'navigator' argument in \code{\link[animation]{saveHTML}}). -#' @param ani_height,ani_width,ani_res Numbers that define the size and the resolution of the animation (see 'ani.height' 'ani.width' and 'ani.res' arguments in \code{\link[animation]{ani.options}}). -#' @param interval A number that defines the time interval between sequential frames (see 'interval' argument in \code{\link[animation]{ani.options}}). -#' @param verbose A logical or character variable that defines whether or not, or what, to write as a footer to the html animation (see 'verbose' argument in \code{\link[animation]{ani.options}}). +#' @param html_name A string that defines the name of the html file (see `htmlfile' argument in \code{\link[animation]{saveHTML}}). +#' @param image_name A string that defines the names of the individual .png files creates (see `img.name' argument in \code{\link[animation]{saveHTML}}). +#' @param html_title,html_description Character strings that provide a title and a description that are displayed within the html animation (see `title' and `description' arguments in \code{\link[animation]{saveHTML}}). +#' @param navigator A logical variable that defines whether or not to add a navigator panel to the animation (see `navigator' argument in \code{\link[animation]{saveHTML}}). +#' @param ani_height,ani_width,ani_res Numbers that define the size and the resolution of the animation (see `ani.height' `ani.width' and `ani.res' arguments in \code{\link[animation]{ani.options}}). +#' @param interval A number that defines the time interval between sequential frames (see `interval' argument in \code{\link[animation]{ani.options}}). +#' @param verbose A logical or character variable that defines whether or not, or what, to write as a footer to the html animation (see `verbose' argument in \code{\link[animation]{ani.options}}). #' @param ... Additional arguments passed to \code{\link[animation]{ani.options}}. #' -#' @return The function produces an animation in .html format in the working directory (or a sub-directory of this). A folder named 'images' is also produced which contains the images for each time step. The 'css' and 'js' folders are also produced by \code{\link[animation]{saveHTML}} which creates the animation. +#' @return The function produces an animation in .html format in the working directory (or a sub-directory of this). A folder named `images' is also produced which contains the images for each time step. The `css' and `js' folders are also produced by \code{\link[animation]{saveHTML}} which creates the animation. #' #' @examples #' dir_current <- getwd() diff --git a/R/acdc_classes.R b/R/acdc_classes.R index f56e320..346fe30 100644 --- a/R/acdc_classes.R +++ b/R/acdc_classes.R @@ -5,15 +5,15 @@ #' @title ".acdc" class #' @description An S3 class that defines the object returned by the \code{\link[flapper]{acdc}} algorithm, after simplification via \code{\link[flapper]{acdc_simplify}}, or directly from the back-end \code{\link[flapper]{.acdc}} function. -#' @return \subsection{A named list}{An ".acdc" 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{plot} 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{keep_args = TRUE}, otherwise the 'args' element is \code{NULL}). The 'chunks' element is a list with chunk-specific information that is generated if the \code{\link[flapper]{acdc}} 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]{acdc}} and \code{\link[flapper]{acdc_simplify}} or \code{\link[flapper]{.acdc}}. Below, more detail about the ‘map’ and ‘record’ elements is provided.} +#' @return \subsection{A named list}{An ".acdc" 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{plot} 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{keep_args = TRUE}, otherwise the `args' element is \code{NULL}). The `chunks' element is a list with chunk-specific information that is generated if the \code{\link[flapper]{acdc}} 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]{acdc}} and \code{\link[flapper]{acdc_simplify}} or \code{\link[flapper]{.acdc}}. 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 acoustic and archival data. Each cell is a count of the number of times when the acoustic and archival data were compatible with the individual having been in that cell, given the ACDC model. 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 acoustic and archival data. Each cell is a count of the number of times when the acoustic and archival data were compatible with the individual having been in that cell, given the ACDC model. 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{(B) ‘record’}{This is a temporal record of the possible locations of each individual, with one element for each acoustic detection. Each element contains (a) a dataframe that defines the details of each pair of detections (the ‘current’ detection and the ‘next’ detection) and all of the archival observations in-between these detections and (b) a named list of spatial objects, one for each archival time step between the pair of acoustic detections, that records the spatial parameters of the algorithm (e.g., the acoustic centroid) at each time step and the possible location(s) of the individual at that time step based on these parameters.} +#' \subsection{(B) `record'}{This is a temporal record of the possible locations of each individual, with one element for each acoustic detection. Each element contains (a) a dataframe that defines the details of each pair of detections (the `current' detection and the `next' detection) and all of the archival observations in-between these detections and (b) a named list of spatial objects, one for each archival time step between the pair of acoustic detections, that records the spatial parameters of the algorithm (e.g., the acoustic centroid) at each time step and the possible location(s) of the individual at that time step based on these parameters.} #' -#' \subsection{(i) record$dat}{‘dat’ contains the following columns: ‘timestep_cumulative’ is a cumulative vector that defines the time step of each observation (across all acoustic and archival time steps up to the current time step); ‘timestep_detection’ defines the time step of the detection time series; ‘timestep_archival’ defines the time step of the archival observations between the current and next acoustic detection; ‘receiver_1_id’ and ‘receiver_2_id’ define the receiver at which the individual was detected at the current and next acoustic time steps; ‘receiver_1_timestamp’ and ‘receiver_2_timestamp’ define the time stamps of these detections; ‘time_btw_dets’ provides the time, in minutes, between these acoustic detections, to the nearest two minutes (the assumed duration between archival records); ‘archival_timestamp’ defines the time stamp of these archival observations; ‘archival_depth’ defines the depth (m) of the individual each archival time step; and ‘centroid_radius’ refers to the size of radius (m) of the acoustic centroid at that time (which depends principally on the time since the last acoustic detection and the time until the next acoustic detection and is a metric of centroid size, bearing-in-mind that the actual centroids can be non-circular).} +#' \subsection{(i) record$dat}{`dat' contains the following columns: `timestep_cumulative' is a cumulative vector that defines the time step of each observation (across all acoustic and archival time steps up to the current time step); `timestep_detection' defines the time step of the detection time series; `timestep_archival' defines the time step of the archival observations between the current and next acoustic detection; `receiver_1_id' and `receiver_2_id' define the receiver at which the individual was detected at the current and next acoustic time steps; `receiver_1_timestamp' and `receiver_2_timestamp' define the time stamps of these detections; `time_btw_dets' provides the time, in minutes, between these acoustic detections, to the nearest two minutes (the assumed duration between archival records); `archival_timestamp' defines the time stamp of these archival observations; `archival_depth' defines the depth (m) of the individual each archival time step; and `centroid_radius' refers to the size of radius (m) of the acoustic centroid at that time (which depends principally on the time since the last acoustic detection and the time until the next acoustic detection and is a metric of centroid size, bearing-in-mind that the actual centroids can be non-circular).} #' -#' \subsection{(ii) record$spatial}{If \code{plot > 0}, then for those time steps specified by \code{plot}, each element in ‘record’ contains a 'spatial' element that is a list, with one element for each archival time stamp between the current and next acoustic detection (defined in ‘record$dat’, see above) that records spatial information pertaining to the possible locations of the individual at that time step. This includes the following elements: ‘centroid’ is a SpatialPolygonsDataFrame that defines the acoustic contour at that time step, which depends on the time since the previous detection, the time until the next detection, the mobility parameter and any spatial masks (i.e., the coastline and specified boundaries); ‘map_timestep’ is a RasterLayer of all the positions that the individual could (cells = 1) or could not (cells = 0) have occupied within that acoustic contour, given its depth and the depth_error, assuming it is on the seabed; and ‘map_cumulative’ is a RasterLayer of the cumulative of the number of times when the acoustic and archival data were compatible with the individual having been in that cell, under the ACDC model, 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). If the receiver at which the individual was detected at the current and next time step differs, after halfway between the archival time steps between these points, the ‘spatial’ list will also contain the following elements: ‘centroid_previous’ is a SpatialPolygonsDataFrame that defines the previous acoustic centroid (i.e., at the ‘current’ receiver); ‘centroid_next’ is a SpatialPolygonsDataFrame that defines the acoustic centroid from the perspective of the ‘next’ receiver at which the individual is detected; 'centroid_overlap' is the overlap between the centroids around the current and next receiver, within which the individual must have been located at the halfway point between detections; and 'centroid_overlap_expanded’ is the expanded version of the centroid overlap that is intersected with the acoustic centroid around the next receiver to determine the individual’s plausible location(s). For \code{plot = 0L} or elements outside of the specified input to \code{plot}, ‘spatial’ is simply an empty list.} +#' \subsection{(ii) record$spatial}{If \code{plot > 0}, then for those time steps specified by \code{plot}, each element in `record' contains a `spatial' element that is a list, with one element for each archival time stamp between the current and next acoustic detection (defined in `record$dat', see above) that records spatial information pertaining to the possible locations of the individual at that time step. This includes the following elements: `centroid' is a SpatialPolygonsDataFrame that defines the acoustic contour at that time step, which depends on the time since the previous detection, the time until the next detection, the mobility parameter and any spatial masks (i.e., the coastline and specified boundaries); `map_timestep' is a RasterLayer of all the positions that the individual could (cells = 1) or could not (cells = 0) have occupied within that acoustic contour, given its depth and the depth_error, assuming it is on the seabed; and `map_cumulative' is a RasterLayer of the cumulative of the number of times when the acoustic and archival data were compatible with the individual having been in that cell, under the ACDC model, 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). If the receiver at which the individual was detected at the current and next time step differs, after halfway between the archival time steps between these points, the `spatial' list will also contain the following elements: `centroid_previous' is a SpatialPolygonsDataFrame that defines the previous acoustic centroid (i.e., at the `current' receiver); `centroid_next' is a SpatialPolygonsDataFrame that defines the acoustic centroid from the perspective of the `next' receiver at which the individual is detected; `centroid_overlap' is the overlap between the centroids around the current and next receiver, within which the individual must have been located at the halfway point between detections; and `centroid_overlap_expanded' is the expanded version of the centroid overlap that is intersected with the acoustic centroid around the next receiver to determine the individual's plausible location(s). For \code{plot = 0L} or elements outside of the specified input to \code{plot}, `spatial' is simply an empty list.} #' #' #' @author Edward Lavender @@ -29,15 +29,15 @@ NULL #' @title "acdc" class #' @description An S3 class that defines the object returned by the \code{\link[flapper]{acdc}} algorithm. #' -#' @return An \code{\link[flapper]{acdc-class}} object is a named list that contains the output of a call to \code{\link[flapper]{acdc}}. This contains the following elements: ‘.acdc’, ‘ts_by_chunk’, ‘time’ and ‘args’. +#' @return An \code{\link[flapper]{acdc-class}} object is a named list that contains the output of a call to \code{\link[flapper]{acdc}}. This contains the following elements: `.acdc', `ts_by_chunk', `time' and `args'. #' -#' The main output is the ‘.acdc’ element. This contains a list of arguments returned by the call(s) to the \code{\link[flapper]{.acdc}} function, which is the workhorse that actually implements the algorithm. If the algorithm is implemented step-wise, this contains a single \code{\link[flapper]{.acdc-class}} object as returned by \code{\link[flapper]{.acdc}}. If the algorithm is implemented chunk-wise, this is a list, with one element for each chunk, each element containing a \code{\link[flapper]{.acdc-class}} object with results of the call to \code{\link[flapper]{.acdc}} for that chunk. The results across chunks can be aggregated using \code{\link[flapper]{acdc_simplify}}. +#' The main output is the `.acdc' element. This contains a list of arguments returned by the call(s) to the \code{\link[flapper]{.acdc}} function, which is the workhorse that actually implements the algorithm. If the algorithm is implemented step-wise, this contains a single \code{\link[flapper]{.acdc-class}} object as returned by \code{\link[flapper]{.acdc}}. If the algorithm is implemented chunk-wise, this is a list, with one element for each chunk, each element containing a \code{\link[flapper]{.acdc-class}} object with results of the call to \code{\link[flapper]{.acdc}} for that chunk. The results across chunks can be aggregated using \code{\link[flapper]{acdc_simplify}}. #' -#' The 'ts_by_chunk' element is a list, with one element for each chunk, that contains the acoustic and archival time series that were used in that chunk. If there is more than one chunk, the last observation of each acoustic chunk is the same as the first acoustic observation for the next chunk. This results from splitting chunks at acoustic observations, which enables the results of chunks that are computed independently to be simply aggregated without the loss of any information. +#' The `ts_by_chunk' element is a list, with one element for each chunk, that contains the acoustic and archival time series that were used in that chunk. If there is more than one chunk, the last observation of each acoustic chunk is the same as the first acoustic observation for the next chunk. This results from splitting chunks at acoustic observations, which enables the results of chunks that are computed independently to be simply aggregated without the loss of any information. #' -#' 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 `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 records the parameters used to generate the outputs. +#' The `args' element is a named list of user inputs that records the parameters used to generate the outputs. #' #' @author Edward Lavender #' @docType package diff --git a/R/assembles.R b/R/assembles.R index 09bb644..90555e7 100644 --- a/R/assembles.R +++ b/R/assembles.R @@ -8,15 +8,15 @@ #' #' @description This function assembles a dataframe of counts of transmissions/detections from sentinel tags over user-defined time windows. For each sentinel tag, in each time window, the function counts the number of transmissions of that tag (i.e., the expected number of detections at nearby receivers). At the same time, the function determines the number of detections at all nearby receivers (defined as those within a user-specified distance) that were active at the same time as the sentinel tag. The result is a dataframe which comprises, for each tag and each time window, the number of transmissions (i.e., the expected number of detections) and the observed number of detections at each nearby receiver, arranged in long format. #' -#' @param sentinel A dataframe that includes all sentinel tag transmissions and detections. This should include the following columns: 'timestamp', the time of each observation; 'type', the type of each observation ("transmission" or "detection"); 'sink_id', a unique identifier of the receivers which received the transmissions; and 'source_id', a unique identifier of the receivers from which the transmission was released (by the built-in sentinel tag). (When the 'source_id' is the same as the 'sink_id', the observation is of type "transmission"; otherwise, the observation must be of type "detection"). See \code{\link[flapper]{dat_sentinel}} for an example. -#' @param moorings A dataframe that includes receiver identifiers, deployment times and locations. This information is necessary so that, for each time window, only receivers that could have detected transmissions (i.e., were nearby to the transmitter and active at the time of transmission) are included in the processed dataframe. This should include the following columns: 'receiver_id', a unique identifier for each receiver; 'receiver_start_date', the deployment date for each receiver; 'receiver_end_date', the deployment end date for each receiver; 'receiver_long', the receiver longitude (decimal degrees); and 'receiver_lat', the receiver latitude (decimal degrees). See \code{\link[flapper]{dat_moorings}} for an example. +#' @param sentinel A dataframe that includes all sentinel tag transmissions and detections. This should include the following columns: `timestamp', the time of each observation; `type', the type of each observation ("transmission" or "detection"); `sink_id', a unique identifier of the receivers which received the transmissions; and `source_id', a unique identifier of the receivers from which the transmission was released (by the built-in sentinel tag). (When the `source_id' is the same as the `sink_id', the observation is of type "transmission"; otherwise, the observation must be of type "detection"). See \code{\link[flapper]{dat_sentinel}} for an example. +#' @param moorings A dataframe that includes receiver identifiers, deployment times and locations. This information is necessary so that, for each time window, only receivers that could have detected transmissions (i.e., were nearby to the transmitter and active at the time of transmission) are included in the processed dataframe. This should include the following columns: `receiver_id', a unique identifier for each receiver; `receiver_start_date', the deployment date for each receiver; `receiver_end_date', the deployment end date for each receiver; `receiver_long', the receiver longitude (decimal degrees); and `receiver_lat', the receiver latitude (decimal degrees). See \code{\link[flapper]{dat_moorings}} for an example. #' @param breaks The time interval over which transmissions/detections are counted (e.g. \code{"hours"}). This is passed to the \code{breaks} argument of \code{\link[base]{cut.POSIXt}}. #' @param as_POSIXct A function that defines how to convert character time bins (returned by \code{\link[base]{cut.POSIXt}}) to POSIXct format. Usually, \code{\link[base]{as.POSIXct}} is suitable but, for large time series, this is slow. In this case, \code{\link[fasttime]{fastPOSIXct}} can be used to improve algorithm speed, if suitable. The default function is \code{function(x, tz = "UTC",...) fasttime::fastPOSIXct(x, tz = tz,...)}. #' @param detection_range A number that defines the maximum distance (m) between a transmitting receiver and other receivers within with detections may plausibly be received. For each transmission, all detections at active receivers within this distance are counted; other receivers are not considered. -#' @param dist_btw_receivers (optional) A dataframe that specifies the distances between all combinations of receivers. If not provided, this is computed internally by \code{\link[flapper]{dist_btw_receivers}}, which assumes Euclidean distances are appropriate. If provided, the dataframe should contain columns: 'r1', 'r2', 'dist' (see \code{\link[flapper]{dist_btw_receivers}}). Note that, if provided, the 'dist' column should be in m, not km, as returned by default by \code{\link[flapper]{dist_btw_receivers}}, to match the units of \code{detection_range}. +#' @param dist_btw_receivers (optional) A dataframe that specifies the distances between all combinations of receivers. If not provided, this is computed internally by \code{\link[flapper]{dist_btw_receivers}}, which assumes Euclidean distances are appropriate. If provided, the dataframe should contain columns: `r1', `r2', `dist' (see \code{\link[flapper]{dist_btw_receivers}}). Note that, if provided, the `dist' column should be in m, not km, as returned by default by \code{\link[flapper]{dist_btw_receivers}}, to match the units of \code{detection_range}. #' @param ... Additional arguments (none implemented). #' -#' @return The function returns a dataframe that, for each source receiver (i.e., sentinel tag), specifies the number of transmissions from that receiver and the number of detections at each nearby receiver over the specified time window. The dataframe has the following columns: 'timestamp_bin', the time window; 'source_id', the identifier of the source of transmission; 'sink_id', the identifer of each potential recipient of each transmission; 'n_trms', the number of transmissions from the source over each time window; 'n_dets', the number of detections of each transmission at each potential recipient receiver; 'dist_btw_receivers', the distance between the source and the sink receiver. Rows are ordered by 'source_id', then 'timestamp' and finally 'sink_id'. +#' @return The function returns a dataframe that, for each source receiver (i.e., sentinel tag), specifies the number of transmissions from that receiver and the number of detections at each nearby receiver over the specified time window. The dataframe has the following columns: `timestamp_bin', the time window; `source_id', the identifier of the source of transmission; `sink_id', the identifer of each potential recipient of each transmission; `n_trms', the number of transmissions from the source over each time window; `n_dets', the number of detections of each transmission at each potential recipient receiver; `dist_btw_receivers', the distance between the source and the sink receiver. Rows are ordered by `source_id', then `timestamp' and finally `sink_id'. #' #' @examples #' #### Example (1): Use default options and example dataframes, which contain diff --git a/R/coa.R b/R/coa.R index 8588139..d7c9f6b 100644 --- a/R/coa.R +++ b/R/coa.R @@ -9,11 +9,11 @@ #' #' To implement these approaches, it is necessary to supply a dataframe with detections for a particular individual (\code{acoustics}), the interval to be evaluated (\code{delta_t}) and the \code{method}. For each method, two implementations are possible. The first implementation (\code{implementation = 1L}) follows Simpfendorfer et al.'s (2002) approach and examines the frequency distribution(s) for the total number of receivers and/or detections, which is appropriate if the total number of receivers is constant over the duration of detections. The second implementation (\code{implementation = 2L}) examines the distribution(s) of the percent of receivers with detections or the number of detections per receiver and can be more appropriate if the number of receivers changes substantially through time. Using these inputs, the function plots the specified distributions and returns a named list with the data plotted. This approach can be applied iteratively over multiple \code{delta_t} values to evaluate their relative suitability. #' -#' @param acoustics A dataframe with passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a specific individual. This should contain the following columns: a vector of receiver IDs, named 'receiver_id'; and a POSIXct vector of time stamps, named 'timestamp'. -#' @param delta_t A number or character, passed to the 'breaks' argument of \code{\link[base]{cut.POSIXt}}, that defines the time interval to be evaluated. +#' @param acoustics A dataframe with passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a specific individual. This should contain the following columns: a vector of receiver IDs, named `receiver_id'; and a POSIXct vector of time stamps, named `timestamp'. +#' @param delta_t A number or character, passed to the `breaks' argument of \code{\link[base]{cut.POSIXt}}, that defines the time interval to be evaluated. #' @param method An integer (\code{1L}, \code{2L} or \code{1:2L}) that defines the method(s) used to evaluate the time intervals (see Description). #' @param implementation An integer (\code{1L} or \code{2L}) that defines the metric(s) used in the evaluation: \code{1}, the total number of receivers/detections; or \code{2}, the percent of receivers/number of detections per receiver (see Description). If \code{implementation = 2L} and the total number of receivers is constant through time, the function reverts to \code{implementation = 1L}, the results of which are more interpretable. -#' @param moorings (optional) If \code{implementation = 2L}, \code{moorings} is a dataframe that defines, for each receiver, the deployment period. This is required to calculate the number of operational receivers over time (via \code{\link[flapper]{get_n_operational_ts}}). This must contain the following columns: a vector of receiver IDs that includes all receivers in \code{acoustics}, named 'receiver_id'; and the times of receiver deployment and retrieval, named 'receiver_start_date' and 'receiver_end_date' respectively. These are coerced to POSIXct vectors, if required, to match \code{acoustics$timestamp}. +#' @param moorings (optional) If \code{implementation = 2L}, \code{moorings} is a dataframe that defines, for each receiver, the deployment period. This is required to calculate the number of operational receivers over time (via \code{\link[flapper]{get_n_operational_ts}}). This must contain the following columns: a vector of receiver IDs that includes all receivers in \code{acoustics}, named `receiver_id'; and the times of receiver deployment and retrieval, named `receiver_start_date' and `receiver_end_date' respectively. These are coerced to POSIXct vectors, if required, to match \code{acoustics$timestamp}. #' @param xlim,ylim X and y axis limits. If \code{method = 1:2L}, a single vector will affect both plots identically, whereas a list with one element for each method will affect plots differently. #' @param xlab,ylab,main Character strings that define the x and y axis labels and the plot title. If \code{method = 1:2L}, a single input will label both plots identically, whereas a list with one element for each method will label the plots differently. #' @param add_additional (optional) A stand-alone function, to be executed after a plot has been made, to customise the result. @@ -22,7 +22,7 @@ #' #' @details The selection of the most appropriate time interval over which to calculate COAs reflects a trade off between (a) larger intervals, over which time more detections at more receivers are made, which enable more accurate estimates, versus (b) smaller intervals, over which time movement is more restricted and centres of activity are representative of the individual's location or short-term centre of activity (Simpfendorfer et al., 2002). As a starting point, Simpfendorfer et al. (2002) suggest intervals from 5 - 60 minutes may often be suitable, although longer intervals may be required. #' -#' @return The function returns a named list and a plot for each \code{method}. The list contains a 'data' element that is a named list of dataframes for each method ('m1', 'm2') and implementation ('i1', 'i2'). For 'm1_i1', the dataframe contains the number of receivers with detections ('n_receiver_with_detections') and the percent of the time series for which that number of receivers made detections ('pc_of_ts'). For 'm1_i2', the percentage of receivers with detections ('pc_receiver_with_detections') is given instead. For 'm2_i1', the number of detections ('n_detections') is given; for 'm2_i2', it is the number of detections per receiver ('n_detections_per_receiver'). The list also contains an 'args' element that records the inputs to \code{acoustics} and \code{delta_t} for reference. +#' @return The function returns a named list and a plot for each \code{method}. The list contains a `data' element that is a named list of dataframes for each method (`m1', `m2') and implementation (`i1', `i2'). For `m1_i1', the dataframe contains the number of receivers with detections (`n_receiver_with_detections') and the percent of the time series for which that number of receivers made detections (`pc_of_ts'). For `m1_i2', the percentage of receivers with detections (`pc_receiver_with_detections') is given instead. For `m2_i1', the number of detections (`n_detections') is given; for `m2_i2', it is the number of detections per receiver (`n_detections_per_receiver'). The list also contains an `args' element that records the inputs to \code{acoustics} and \code{delta_t} for reference. #' #' @examples #' #### Example (1): For a specified delta_t, use a specific method and implementation @@ -326,7 +326,7 @@ coa_setup_delta_t <- function(acoustics, #' #' To generate estimates of space use, COAs are usually taken as point estimates from which utilisation distributions (typically kernel utilisation distributions, KUDs) are estimated. Thus, in the case of a coupled COA-KUD approach, usually the estimate of space use is a (kernel) utilisation distribution which describes the probability of relocating an individual in any given area at a randomly chosen time. Alternative methods of home range analysis, including those which incorporate time, such as dynamic Brownian bridge movement models, can be used to estimate the utilisation distribution. Generally, the COA approach is most suitable when detections are relatively frequent, and receivers are regularly distributed across an area. Under other conditions, its performance as a method for estimating space use has been subject to relatively limited evaluation but it can be problematic (e.g., in clustered arrays). #' -#' @return The function returns a matrix or a dataframe, depending on the \code{output} argument, that represents a time series of COAs. If \code{na_omit = TRUE}, the time series may have 'gaps' over which COAs could not be calculated due to the absence of detections. +#' @return The function returns a matrix or a dataframe, depending on the \code{output} argument, that represents a time series of COAs. If \code{na_omit = TRUE}, the time series may have `gaps' over which COAs could not be calculated due to the absence of detections. #' #' @examples #' #### Define data for the calculation of COAs @@ -379,7 +379,7 @@ coa_setup_delta_t <- function(acoustics, #' cl = parallel::makeCluster(2L)) #' } #' -#' @seealso \code{\link[flapper]{coa_setup_delta_t}} suggests suitable time intervals over which to calculate COAs. \code{\link[flapper]{make_matrix_detections}} makes the detection matrices from detection time series data required by this function. For data in the VEMCO Vue export format, the 'COA' function in the VTrack package (https://github.com/RossDwyer/VTrack) can also be used to calculate centres of activity. +#' @seealso \code{\link[flapper]{coa_setup_delta_t}} suggests suitable time intervals over which to calculate COAs. \code{\link[flapper]{make_matrix_detections}} makes the detection matrices from detection time series data required by this function. For data in the VEMCO Vue export format, the `COA' function in the VTrack package (https://github.com/RossDwyer/VTrack) can also be used to calculate centres of activity. #' #' @references Simpfendorfer, C. A., M. R. Heupel, and R. E. Hueter. 2002. Estimation of short-term centers of activity from an array of omnidirectional hydrophones and its use in studying animal movements. Canadian Journal of Fisheries and Aquatic Sciences 59:23-32. #' diff --git a/R/dats.R b/R/dats.R index f96ec12..734cc6e 100644 --- a/R/dats.R +++ b/R/dats.R @@ -34,7 +34,7 @@ #' \describe{ #' \item{receiver_id}{An integer which distinguishes each unique receiver deployment.} #' \item{receiver}{A character which defines each receiver.} -#' \item{sentinel_id}{A character which defines each receiver's built-in acoustic transmitter ('sentinel tag'). Some receivers did not have sentinel tags; their \code{sentinel_id} is \code{NA}.} +#' \item{sentinel_id}{A character which defines each receiver's built-in acoustic transmitter (`sentinel tag'). Some receivers did not have sentinel tags; their \code{sentinel_id} is \code{NA}.} #' \item{receiver_start_date}{A date which defines the start date of each receiver's deployment.} #' \item{receiver_end_date}{A date which defines the end date of each receiver's deployment.} #' \item{receiver_long}{A number which defines the longitude (decimal degrees) of each receiver.} diff --git a/R/dc.R b/R/dc.R index 8b69818..85ddb9f 100644 --- a/R/dc.R +++ b/R/dc.R @@ -1,7 +1,7 @@ #' @title The depth-contour (DC) algorithm #' @description This function implements the depth-contour (DC) algorithm. Under the assumption that individuals are benthic/demersal, this algorithm relates one-dimensional depth time series to a two-dimensional bathymetry surface to determine the extent to which different parts of an area might have (or have not) been used, or effectively represent occupied depths, over time. To implement this function, a list of depth time series, one for each time unit (e.g. month/season) need to be supplied, along with a bathymetry \code{\link[raster]{raster}}. For each time unit, the function counts the number of depth observations in each user-defined depth bin (e.g., 10 m depth bins) and then relates these counts to the local bathymetry to produce a raster in which the value of each cell is given by the number of times in which the depth bin for that cell was used. The function returns a list of rasters, one for each time unit, and a plot of these rasters, if requested. #' -#' @param archival_ls A list of dataframes, with one element for each time unit (e.g., month), which contain depth time series to be related to the local bathymetry. Each dataframe should contain a column of depths ('depth') and a column that defines the time unit ('time_unit'). Depth should be recorded using absolute values in the same units as the bathymetry (see below). +#' @param archival_ls A list of dataframes, with one element for each time unit (e.g., month), which contain depth time series to be related to the local bathymetry. Each dataframe should contain a column of depths (`depth') and a column that defines the time unit (`time_unit'). Depth should be recorded using absolute values in the same units as the bathymetry (see below). #' @param bathy A \code{\link[raster]{raster}} of the bathymetry in an area within which the animal is likely to have been located over the study. Bathymetry values should be recorded as absolute values and in the same units as for depths (see \code{archival_ls}). #' @param bin A number that defines the interval into which depth observations are binned. This should be provided in the same units as depths (see \code{archival_ls}) and the bathymetry (see \code{bathy}). The appropriate value of \code{bin} depends on the measurement error of the \code{bathy} data and the depth time series, the tidal range in an area, computational requirements, and scale of biological research objectives. For large depth time series and/or large, high-resolution bathymetry rasters, it can be useful to test the algorithm's speed using a relatively large bin. #' @param transform (optional) A function, such as \code{sqrt}, to transform counts. This affects the returned rasters and any plots produced (see Value). Be careful with some functions, such as \code{log}, which can generate problematic outputs (such as z axis limits if these are not defined manually), in some situations (for example, if some cells in the area are not visited). diff --git a/R/dists.R b/R/dists.R index bda0b41..1ce748e 100644 --- a/R/dists.R +++ b/R/dists.R @@ -5,10 +5,10 @@ #' @title Compute Euclidean distances between receivers #' @description This function computes Euclidean distances (km) between all combinations of receivers. #' -#' @param moorings A dataframe which defines each unique receiver deployment. This should contain the columns: 'receiver_id', a unique identifier of each receiver, 'receiver_lat', the latitude of that receiver in decimal degrees; and 'receiver_long', the longitude of that receiver in decimal degrees (see \code{\link[flapper]{dat_moorings}}). +#' @param moorings A dataframe which defines each unique receiver deployment. This should contain the columns: `receiver_id', a unique identifier of each receiver, `receiver_lat', the latitude of that receiver in decimal degrees; and `receiver_long', the longitude of that receiver in decimal degrees (see \code{\link[flapper]{dat_moorings}}). #' @param f (optional) A function which is used to process distances before these are returned. For example, it may be useful to round distances to nearest km with \code{f = function(x) round(x, digits = 0)}. #' -#' @return The function returns a dataframe with columns 'r1', 'r2' and 'dist'. These define the IDs of each combination of receivers and the associated distance between them, in km. Note that the dataframe contains duplicate combinations of receivers (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). +#' @return The function returns a dataframe with columns `r1', `r2' and `dist'. These define the IDs of each combination of receivers and the associated distance between them, in km. Note that the dataframe contains duplicate combinations of receivers (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). #' #' @examples #' #### Example (1): Compute distances between all combinations of receivers in km @@ -184,14 +184,14 @@ dist_over_surface <- function(path, surface){ #### lcp_over_surface() #' @title Calculate shortest path(s) and/or distance(s) over a surface between origin and destination coordinates -#' @description This function computes the shortest path(s) and/or distance(s) over a \code{surface} between \code{origin} and \code{destination} coordinates. To implement this function, \code{origin} and \code{destination} coordinates need to be specified as matrices and the surface over which movement occurs should be supplied as a \code{\link[raster]{raster}}. Since determining shortest paths can be computationally and memory-intensive, the \code{surface} can be reduced in size and/or resolution before these are computed, by (a) cropping the surface within user-defined extents; (b) focusing on a buffer zone along a Euclidean transect connecting \code{origin} and \code{destination} coordinates; (c) aggregating the surface to reduce the resolution; and/or (d) masking out areas over which movement is impossible (e.g., land for marine animals). Then, the function computes distances between connected cells, given (a) the planar distances between connected cells and (b) their difference in elevation. These distances are taken as a measure of 'cost'. For each pair of \code{origin} and \code{destination} coordinates, or for all combinations of coordinates, these distances are used to compute the least-cost (i.e., shortest) path and/or the distance of this path, using functions in the \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} package. The function returns the shortest path(s) and/or their distance(s) (m) along with a plot and a list of objects involved in the calculations. +#' @description This function computes the shortest path(s) and/or distance(s) over a \code{surface} between \code{origin} and \code{destination} coordinates. To implement this function, \code{origin} and \code{destination} coordinates need to be specified as matrices and the surface over which movement occurs should be supplied as a \code{\link[raster]{raster}}. Since determining shortest paths can be computationally and memory-intensive, the \code{surface} can be reduced in size and/or resolution before these are computed, by (a) cropping the surface within user-defined extents; (b) focusing on a buffer zone along a Euclidean transect connecting \code{origin} and \code{destination} coordinates; (c) aggregating the surface to reduce the resolution; and/or (d) masking out areas over which movement is impossible (e.g., land for marine animals). Then, the function computes distances between connected cells, given (a) the planar distances between connected cells and (b) their difference in elevation. These distances are taken as a measure of `cost'. For each pair of \code{origin} and \code{destination} coordinates, or for all combinations of coordinates, these distances are used to compute the least-cost (i.e., shortest) path and/or the distance of this path, using functions in the \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} package. The function returns the shortest path(s) and/or their distance(s) (m) along with a plot and a list of objects involved in the calculations. #' @param origin A matrix which defines the coordinates (x, y) of the starting location(s). Coordinates should lie on a plane (i.e., Universal Transverse Mercator projection). #' @param destination A matrix which defines the coordinates (x, y) of the finishing location(s). Coordinates should lie on a plane (i.e., Universal Transverse Mercator projection). -#' @param surface A \code{\link[raster]{raster}} over which the object (e.g., individual) must move from \code{origin} to \code{destination}. The \code{surface} must be planar (i.e., Universal Transverse Mercator projection) with units of metres in x, y and z directions (m). The \code{surface}'s \code{\link[raster]{resolution}} is taken to define the distance between horizontally and vertically connected cells and must be the same in both x and y directions (for \code{surface}'s with unequal horizontal resolution, \code{\link[raster]{resample}} can be used to equalise resolution: see Examples). Any cells with NA values (e.g., due to missing data) are treated as 'impossible' to move though by the algorithm. In this case, the \code{surface} might need to be pre-processed so that NAs are replaced/removed before implementing the function, depending on their source. +#' @param surface A \code{\link[raster]{raster}} over which the object (e.g., individual) must move from \code{origin} to \code{destination}. The \code{surface} must be planar (i.e., Universal Transverse Mercator projection) with units of metres in x, y and z directions (m). The \code{surface}'s \code{\link[raster]{resolution}} is taken to define the distance between horizontally and vertically connected cells and must be the same in both x and y directions (for \code{surface}'s with unequal horizontal resolution, \code{\link[raster]{resample}} can be used to equalise resolution: see Examples). Any cells with NA values (e.g., due to missing data) are treated as `impossible' to move though by the algorithm. In this case, the \code{surface} might need to be pre-processed so that NAs are replaced/removed before implementing the function, depending on their source. #' @param crop (optional) An \code{\link[raster]{extent}} object that is used to \code{\link[raster]{crop}} the extent of the \code{surface}, before the least-cost algorithms are implemented. This may be useful for large rasters to reduce memory requirements/computation time. #' @param buffer (optional) A named list of arguments, passed to \code{\link[rgeos]{gBuffer}} (e.g. \code{buffer = list(width = 1000)}) (m) that is used to define a buffer around a Euclidean transect connecting the \code{origin} and \code{destination}. (This option can only be implemented for a single \code{origin} and \code{destination} pair.) The \code{surface} is then cropped to the extent of this buffer before the least-cost algorithms are implemented. This may be useful for large rasters to reduce memory requirements and/or computation time. #' @param aggregate (optional) A named list of arguments, passed to \code{\link[raster]{aggregate}}, to aggregate raster cells before the least-cost algorithms are implemented. This may be useful for large rasters to reduce memory requirements and/or computation time. -#' @param mask (optional) A Raster or Spatial \code{\link[raster]{mask}} that is used to prevent movement over 'impossible' areas on the \code{surface}. This must also lie on a planar surface (i.e., Universal Transverse Mercator projection). For example, for marine animals, \code{mask} might be a \code{\link[sp]{SpatialPolygonsDataFrame}} which defines the coastline. The effect of the \code{mask} depends on \code{mask_inside} (see below). +#' @param mask (optional) A Raster or Spatial \code{\link[raster]{mask}} that is used to prevent movement over `impossible' areas on the \code{surface}. This must also lie on a planar surface (i.e., Universal Transverse Mercator projection). For example, for marine animals, \code{mask} might be a \code{\link[sp]{SpatialPolygonsDataFrame}} which defines the coastline. The effect of the \code{mask} depends on \code{mask_inside} (see below). #' @param mask_inside A logical input that defines whether or not to mask the \code{surface} inside (\code{TRUE}) or outside (\code{FALSE}) of the \code{mask} (see \code{\link[flapper]{mask_io}}). #' @param plot A logical input that defines whether or not to plot the inputted and processed surfaces. If \code{TRUE}, the inputted and processed plots are produced side-by-side. For the inputted surface, the \code{mask} and the region selected (via \code{crop} and/or \code{buffer}) are shown along with the \code{origin} and \code{destination}. For the processed surface, the surface and the \code{origin} and \code{destination} are shown, along with the shortest path(s) (if and once computed: see \code{goal}). This is useful for checking that any \code{surface} processing steps have been applied correctly and the \code{origin} and \code{destination} are positioned correctly on the \code{surface}. #' @param goal An integer that defines the output of the function: \code{goal = 1} computes shortest distances, \code{goal = 2} computes shortest paths and \code{goal = 3} computes both shortest paths and the corresponding distances. Note that \code{goal = 3} results in least-cost algorithms being implemented twice, which will be inefficient for large problems; in this case, use \code{goal = 2} to compute shortest paths and then calculate their distance using outputs returned by the function (see Value). @@ -207,23 +207,23 @@ dist_over_surface <- function(path, surface){ #' \subsection{Methods}{ #' This function was motivated by the need to determine the shortest paths and their distances between points for benthic animals, which must move over the seabed to navigate from A to B. For these animals, especially in areas with heterogeneous bathymetric landscapes and/or coastline, the shortest path that an individual must travel to move from A and B may differ substantially from the Euclidean path that is often used as a proxy for distance in biological studies. However, this function can still be used in situations where the surface over which an individual must move is irrelevant (e.g., for a pelagic animal), by supplying a flat surface; then shortest paths/distances simply depend on the planar distances between locations and any barriers (e.g., the coastline). (However, this process will be somewhat inefficient.) #' -#' The function conceptualises an object moving across a landscape as a queen on a chessboard which can move, in eight directions around its current position, across this surface. Given the potentially large number of possible paths between an \code{origin} and \code{destination}, the surface may be reduced in extent or size before the game begins. To determine shortest path/distance over the surface between each \code{origin} and \code{destination} pair/combination, the function first considers the distance that an object must travel between pairs of connected cells. This depends on the planar distances between cells and their differences in elevation. Planar distances (\eqn{d_p}, m) depend on the movement type: under a rook's movement (i.e., horizontally or vertically), the distance (\eqn{d_{p,r}}) between connected cells is extracted from the raster's resolution (which is assumed to be identical in the x and y directions); under a bishop's movement (i.e., diagonally), the distance between connected cells \eqn{d_{p,b}} is given by Pythagoras' Theorem: \eqn{d_{p,b} = \sqrt{(d_{p, r}^2 + d_{p, r}^2)}}. Vertical distances (\eqn{d_v}, m) are simply the differences in height between cells. The total distance (\eqn{d_t}) between any two connected cells is a combination of these distances given by Pythagoras' Theorem: \eqn{d_t = \sqrt{(d_p^2 + d_v^2)}}. These distances are taken to define the 'cost' of movement between connected cells. Thus, 'costs' are symmetric (i.e., the cost of moving from A to B equals the cost of moving from B to A). +#' The function conceptualises an object moving across a landscape as a queen on a chessboard which can move, in eight directions around its current position, across this surface. Given the potentially large number of possible paths between an \code{origin} and \code{destination}, the surface may be reduced in extent or size before the game begins. To determine shortest path/distance over the surface between each \code{origin} and \code{destination} pair/combination, the function first considers the distance that an object must travel between pairs of connected cells. This depends on the planar distances between cells and their differences in elevation. Planar distances (\eqn{d_p}, m) depend on the movement type: under a rook's movement (i.e., horizontally or vertically), the distance (\eqn{d_{p,r}}) between connected cells is extracted from the raster's resolution (which is assumed to be identical in the x and y directions); under a bishop's movement (i.e., diagonally), the distance between connected cells \eqn{d_{p,b}} is given by Pythagoras' Theorem: \eqn{d_{p,b} = \sqrt{(d_{p, r}^2 + d_{p, r}^2)}}. Vertical distances (\eqn{d_v}, m) are simply the differences in height between cells. The total distance (\eqn{d_t}) between any two connected cells is a combination of these distances given by Pythagoras' Theorem: \eqn{d_t = \sqrt{(d_p^2 + d_v^2)}}. These distances are taken to define the `cost' of movement between connected cells. Thus, `costs' are symmetric (i.e., the cost of moving from A to B equals the cost of moving from B to A). #' #' This cost surface is then used to compute the shortest path and/or distance of the shortest path between each \code{origin} and \code{destination} pair/combination using functions in the \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} package. The functions implemented depend on the \code{goal} (i.e., whether the aim is to compute shortest paths, shortest distances or both) and, if there is more than one \code{origin}/\code{destination}, the \code{combination} type (i.e., whether to compute shortest paths/distances for each sequential pair of coordinates or all possible combinations of coordinates). #' } #' #' \subsection{Warnings}{ -#' The function returns a warning produced by \code{\link[gdistance]{transition}} which is implemented to facilitate the definition of the cost surface, before shortest paths/distances are computed by either method: 'In .TfromR(x, transitionFunction, directions, symm) : transition function gives negative values'. This warning arises because the height differences between connecting cells can be negative. It can be safely ignored. +#' The function returns a warning produced by \code{\link[gdistance]{transition}} which is implemented to facilitate the definition of the cost surface, before shortest paths/distances are computed by either method: `In .TfromR(x, transitionFunction, directions, symm) : transition function gives negative values'. This warning arises because the height differences between connecting cells can be negative. It can be safely ignored. #' } #' #' @return -#' \subsection{A named list}{The function returns a named list. The most important element(s) of this list are 'path_lcp' and/or 'dist_lcp', the shortest path(s) and/or distance(s) (m) between \code{origin} and \code{destination} coordinate pairs/combinations. 'path_lcp' is returned if \code{goal = 2} or \code{goal = 3} and 'dist_lcp' is returned if \code{goal = 1} or \code{goal = 3}. 'path_lcp' contains (a) a dataframe with the cells comprising each path ('cells'), (b) a named list containing a \code{\link[sp]{SpatialLines}} object for each path ('SpatialLines') and (c) a named list of matrices of the coordinates of each path ('coordinates'). 'dist_lcp' is a (a) numeric vector or (b) matrix with the distances (m) between each pair or combination of coordinates respectively. If 'dist_lcp' is computed, 'dist_euclid', the Euclidean distances (m) between the \code{origin} and \code{destination}, is also returned for comparison. +#' \subsection{A named list}{The function returns a named list. The most important element(s) of this list are `path_lcp' and/or `dist_lcp', the shortest path(s) and/or distance(s) (m) between \code{origin} and \code{destination} coordinate pairs/combinations. `path_lcp' is returned if \code{goal = 2} or \code{goal = 3} and `dist_lcp' is returned if \code{goal = 1} or \code{goal = 3}. `path_lcp' contains (a) a dataframe with the cells comprising each path (`cells'), (b) a named list containing a \code{\link[sp]{SpatialLines}} object for each path (`SpatialLines') and (c) a named list of matrices of the coordinates of each path (`coordinates'). `dist_lcp' is a (a) numeric vector or (b) matrix with the distances (m) between each pair or combination of coordinates respectively. If `dist_lcp' is computed, `dist_euclid', the Euclidean distances (m) between the \code{origin} and \code{destination}, is also returned for comparison. #' } #' -#' \subsection{Common elements}{Other elements of the list record important outputs at sequential stages of the algorithm's progression. These include the following elements: 'args', a named list of user inputs; 'time', a dataframe that defines the times of sequential stages in the algorithm's progression; 'surface', the surface over which shortest distances are computed (this may differ from the inputted surface if any of the processing options, such as \code{crop}, have been implemented); 'surface_param', a named list that defines the cell IDs, the number of rows, the number of columns, the coordinates of the implemented surface and the cell IDs of the \code{origin} and \code{destination} nodes; 'cost', a named list of arguments that defines the distances (m) between connected cells under a rook's or bishop's movement ('dist_rook' and 'dist_bishop'), the planar and vertical distances between connected cells ('dist_planar' and 'dist_vertical') and the total distance between connected cells ('dist_total'); and 'cppRouting_param' or 'gdistance_param', a named list of arguments used to compute shortest paths/distances via \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} (see below). +#' \subsection{Common elements}{Other elements of the list record important outputs at sequential stages of the algorithm's progression. These include the following elements: `args', a named list of user inputs; `time', a dataframe that defines the times of sequential stages in the algorithm's progression; `surface', the surface over which shortest distances are computed (this may differ from the inputted surface if any of the processing options, such as \code{crop}, have been implemented); `surface_param', a named list that defines the cell IDs, the number of rows, the number of columns, the coordinates of the implemented surface and the cell IDs of the \code{origin} and \code{destination} nodes; `cost', a named list of arguments that defines the distances (m) between connected cells under a rook's or bishop's movement (`dist_rook' and `dist_bishop'), the planar and vertical distances between connected cells (`dist_planar' and `dist_vertical') and the total distance between connected cells (`dist_total'); and `cppRouting_param' or `gdistance_param', a named list of arguments used to compute shortest paths/distances via \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} (see below). #' } #' -#' \subsection{Method-specific elements}{If \code{method = "cppRouting"}, the 'cppRouting_param' list contains a named list of arguments passed to \code{\link[cppRouting]{makegraph}} ('makegraph_param') as well as \code{\link[cppRouting]{get_path_pair}} ('get_path_pair_param') or \code{\link[cppRouting]{get_multi_paths}} ('get_multi_paths_param') and/or \code{\link[cppRouting]{get_distance_pair}} ('get_distance_pair_param') or \code{\link[cppRouting]{get_distance_matrix}} ('get_distance_matrix_param'), depending on whether or not shortest paths and/or distances have been computed (see \code{goal}) and whether or not shortest paths/distances have been computed for each pair of coordinates or all combinations of coordinates. If \code{method = "gdistance"}, this list contains a named list of arguments passed iteratively, for each pair/combination of coordinates, to \code{\link[gdistance]{shortestPath}} ('shortestPath_param') or \code{\link[gdistance]{costDistance}} ('costDistance_param'). This includes an object of class TransitionLayer (see \code{\link[gdistance]{Transition-classes}}), in which the \code{transitionMatrix} slot contains a (sparse) matrix that defines the ease of moving between connected cells (the reciprocal of the 'dist_total' matrix). +#' \subsection{Method-specific elements}{If \code{method = "cppRouting"}, the `cppRouting_param' list contains a named list of arguments passed to \code{\link[cppRouting]{makegraph}} (`makegraph_param') as well as \code{\link[cppRouting]{get_path_pair}} (`get_path_pair_param') or \code{\link[cppRouting]{get_multi_paths}} (`get_multi_paths_param') and/or \code{\link[cppRouting]{get_distance_pair}} (`get_distance_pair_param') or \code{\link[cppRouting]{get_distance_matrix}} (`get_distance_matrix_param'), depending on whether or not shortest paths and/or distances have been computed (see \code{goal}) and whether or not shortest paths/distances have been computed for each pair of coordinates or all combinations of coordinates. If \code{method = "gdistance"}, this list contains a named list of arguments passed iteratively, for each pair/combination of coordinates, to \code{\link[gdistance]{shortestPath}} (`shortestPath_param') or \code{\link[gdistance]{costDistance}} (`costDistance_param'). This includes an object of class TransitionLayer (see \code{\link[gdistance]{Transition-classes}}), in which the \code{transitionMatrix} slot contains a (sparse) matrix that defines the ease of moving between connected cells (the reciprocal of the `dist_total' matrix). #' } #' #' \subsection{Plot}{If \code{plot = TRUE}, a plot is also produced of the inputted and processed surfaces that are used in the calculations, along with the shortest path(s) (if and once computed). diff --git a/R/evals.R b/R/evals.R index f270b20..4153dff 100644 --- a/R/evals.R +++ b/R/evals.R @@ -10,8 +10,8 @@ #' @param grid,h,hlim,kern,extent,boundary Arguments passed to \code{estimate_ud} (and ultimately \code{\link[adehabitatHR]{kernelUD}}, where they are defined) to estimate kernel utilisation distributions. If \code{\link[flapper]{kud_around_coastline}} is supplied to \code{estimate_ud}, then \code{grid} must be a \code{\link[sp]{SpatialPixelsDataFrame}}. #' @param process (optional) A function, applied to a \code{\link[raster]{raster}}, to process the home range raster (extracted from from \code{\link[adehabitatHR]{getvolumeUD}}). For example, \code{function(r) { r[r > 95] <- NA; return(r) }} can help to produce prettier plots by masking areas beyond the 95 percent contour. #' @param plot An integer vector (\code{1:4L}) that defines which plots to produce. \code{1} and \code{2} plot the receiver array and the simulated or estimated path respectively. In contrast, \code{3} and \code{4} plot the receiver array and the kernel utilisation distribution based on the simulated or estimated path respectively. -#' @param array A named list that defines the properties of an array (e.g., the 'array' element of \code{\link[flapper]{sim_array}}). At a minimum, this must contain an 'area' element that defines the area as a \code{\link[sp]{SpatialPolygons-class}} object. To add receivers, land and sea to the plot(s), 'xy', 'land' and 'sea' elements are also required (see \code{\link[flapper]{sim_array}}). -#' @param add_land,add_sea,add_receivers,add_path_sim,add_path_est,add_vol_sim,add_vol_est (optional) Named lists of arguments that customise the appearance of the land and sea, receivers, the simulated and estimated paths and the kernel volumes for the simulated and estimated paths respectively. An empty list (\code{list()}) will implement default graphical options. If \code{add_receivers}, \code{add_land} and \code{add_sea} are specified, then \code{array} must contain 'xy', 'land' and 'sea' elements as described above. Alternatively, \code{add_receivers}, \code{add_land} and \code{add_sea} can be \code{NULL} to suppress their addition to plots, but the other arguments cannot be \code{NULL}. +#' @param array A named list that defines the properties of an array (e.g., the `array' element of \code{\link[flapper]{sim_array}}). At a minimum, this must contain an `area' element that defines the area as a \code{\link[sp]{SpatialPolygons-class}} object. To add receivers, land and sea to the plot(s), `xy', `land' and `sea' elements are also required (see \code{\link[flapper]{sim_array}}). +#' @param add_land,add_sea,add_receivers,add_path_sim,add_path_est,add_vol_sim,add_vol_est (optional) Named lists of arguments that customise the appearance of the land and sea, receivers, the simulated and estimated paths and the kernel volumes for the simulated and estimated paths respectively. An empty list (\code{list()}) will implement default graphical options. If \code{add_receivers}, \code{add_land} and \code{add_sea} are specified, then \code{array} must contain `xy', `land' and `sea' elements as described above. Alternatively, \code{add_receivers}, \code{add_land} and \code{add_sea} can be \code{NULL} to suppress their addition to plots, but the other arguments cannot be \code{NULL}. #' @param one_page A logical variable that defines whether or not to produce all plots on a single page. #' @param verbose A logical variable that defines whether or not to print messages to the console to relay function progress. #' @param ... Additional arguments, passed to \code{\link[prettyGraphics]{pretty_map}}, that affect all plots. diff --git a/R/flapper-package.R b/R/flapper-package.R index ec95f48..0138a13 100644 --- a/R/flapper-package.R +++ b/R/flapper-package.R @@ -31,8 +31,8 @@ #' \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{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; -#' \item \link{invert_poly} inverts a polygon (e.g, to define the ‘sea’ from a polygon of the ‘land’); -#' \item \link{mask_io} masks values in a raster that lie inside or outside of a spatial mask (e.g., to mask the ‘land’ from the ‘sea’); +#' \item \link{invert_poly} inverts a polygon (e.g, to define the `sea' from a polygon of the `land'); +#' \item \link{mask_io} masks values in a raster that lie inside or outside of a spatial mask (e.g., to mask the `land' from the `sea'); #' \item \link{sim_surface} populates a raster with simulated values; #' \item \link{split_raster_equally} splits a raster into equal pieces (using code from the greenbrown (http://greenbrown.r-forge.r-project.org) package); #' \item \link{update_extent} shrinks or inflates an extent object; @@ -76,7 +76,7 @@ #' } #' \item The acoustic-centroid depth-contour (ACDC) algorithm #' \itemize{ -#' \item \link{acdc_setup_mobility} examines the assumption of a constant 'mobility' parameter; +#' \item \link{acdc_setup_mobility} examines the assumption of a constant `mobility' parameter; #' \item \link{acdc_setup_n_centroids} suggests the number of acoustic centroids for the algorithm; #' \item \link{acdc_setup_centroids} defines the acoustic centroids for the algorithm; #' \item \link{acdc} implements the algorithm, via the back-end function \link{.acdc}; diff --git a/R/get_detections.R b/R/get_detections.R index f768dff..7cc0bfb 100644 --- a/R/get_detections.R +++ b/R/get_detections.R @@ -11,7 +11,7 @@ #' @param output An integer (\code{1L}, \code{2L} or \code{3L}) that defines the output type. \code{1L} returns a plot of detection probability against distance; \code{2L} returns a numeric vector of detection probabilities; and \code{3L} returns both of the above. #' @param ... Additional arguments, passed to \code{\link[prettyGraphics]{pretty_plot}}, to customise the plot. These are only implemented if \code{output = 1L} or \code{output = 3L}. #' -#' @return The function calculates detection probability at each specified distance and returns a plot, a vector of detection probabilities, or both, depending on the value of the \code{output} argument. If a vector of detection probabilities is returned, this contains the following attributes: 'X', the model matrix; 'beta', the regression coefficients; and 'inv_link', the inverse link function. +#' @return The function calculates detection probability at each specified distance and returns a plot, a vector of detection probabilities, or both, depending on the value of the \code{output} argument. If a vector of detection probabilities is returned, this contains the following attributes: `X', the model matrix; `beta', the regression coefficients; and `inv_link', the inverse link function. #' #' @examples #' #### Example (1): Implement the function using the default parameters @@ -86,7 +86,7 @@ get_detection_pr <- function(distance = 1:1000, #### get_detection_centroids() #' @title Define detection centroids around receivers -#' @description This function defines the areas surveyed by receivers (termed 'detection centroids') as a spatial object, based on an estimate of the detection range (m) and any barriers to detection. To implement the function, receiver locations must be supplied as a SpatialPoints or SpatialPointsDataFrame object with the Universe Transverse Mercator coordinate reference system. The function defines a spatial buffer around each receiver according to the estimated detection range, cuts out any barriers to detection, such as the coastline, and returns a SpatialPolygons object that defines the combined detection centroid across all receivers or receiver-specific detection centroids. +#' @description This function defines the areas surveyed by receivers (termed `detection centroids') as a spatial object, based on an estimate of the detection range (m) and any barriers to detection. To implement the function, receiver locations must be supplied as a SpatialPoints or SpatialPointsDataFrame object with the Universe Transverse Mercator coordinate reference system. The function defines a spatial buffer around each receiver according to the estimated detection range, cuts out any barriers to detection, such as the coastline, and returns a SpatialPolygons object that defines the combined detection centroid across all receivers or receiver-specific detection centroids. #' #' @param xy A \code{\link[sp]{SpatialPoints-class}} or \code{\link[sp]{SpatialPointsDataFrame-class}} object that defines receiver locations. The coordinate reference system should be the Universe Transverse Mercator coordinate reference system. #' @param detection_range A number that defines the detection range (m) of receivers. @@ -251,14 +251,14 @@ get_detection_area_sum <- function(xy, #' @title Calculate the area sampled by receivers through time #' @description This function extends \code{\link[flapper]{get_detection_area_sum}} to calculate how the total area sampled by receivers changes through time. #' -#' @param xy,detection_range,coastline,scale Arguments required to calculate the total area surveyed by receivers (at each time point) via \code{\link[flapper]{get_detection_area_sum}}. For this function, \code{xy} should be a \code{\link[sp]{SpatialPolygonsDataFrame-class}} object that includes both receiver locations and corresponding deployment times (in columns named 'receiver_start_date' and 'receiver_end_date' respectively). +#' @param xy,detection_range,coastline,scale Arguments required to calculate the total area surveyed by receivers (at each time point) via \code{\link[flapper]{get_detection_area_sum}}. For this function, \code{xy} should be a \code{\link[sp]{SpatialPolygonsDataFrame-class}} object that includes both receiver locations and corresponding deployment times (in columns named `receiver_start_date' and `receiver_end_date' respectively). #' @param plot A logical input that defines whether or not to plot a time series of the total area sampled by receivers. #' @param verbose A logical input that defines whether or not to print messages to the console to relay function progress. #' @param cl (optional) A cluster object created by \code{\link[parallel]{makeCluster}} to implement the algorithm in parallel. The connection to the cluster is closed within the function. #' @param varlist (optional) A character vector of names of objects to export, to be passed to the \code{varlist} argument of \code{\link[parallel]{clusterExport}}. This may be required if \code{cl} is supplied. Exported objects must be located in the global environment. #' @param ... Additional arguments, passed to \code{\link[prettyGraphics]{pretty_plot}}, to customise the plot produced. #' -#' @return The function returns a dataframe with, for each date ('date') from the time of the first receiver's deployment to the time of the last receiver's retrieval, the number of receivers operational on that date ('n') and the total area sampled ('receiver_area'). If \code{plot = TRUE}, the function also returns a plot of the area sampled by receivers through time. +#' @return The function returns a dataframe with, for each date (`date') from the time of the first receiver's deployment to the time of the last receiver's retrieval, the number of receivers operational on that date (`n') and the total area sampled (`receiver_area'). If \code{plot = TRUE}, the function also returns a plot of the area sampled by receivers through time. #' #' @examples #' #### Define SpatialPointsDataFrame with receiver locations and deployment dates @@ -368,7 +368,7 @@ get_detection_area_ts <- function(xy, #' #' @details This is a simple metric of sampling effort. For acoustic receivers, \code{\link[flapper]{get_detection_area_ts}} provides another metric of sampling effort. #' -#' @return The function returns a dataframe that, for each time step ('time'), defines the number of operational units at that time ('n'). If \code{plot = TRUE}, the function also plots a time series of the number of operational units. +#' @return The function returns a dataframe that, for each time step (`time'), defines the number of operational units at that time (`n'). If \code{plot = TRUE}, the function also plots a time series of the number of operational units. #' #' @examples #' #### Example (1): Number of operational receivers over an acoustic telemetry study @@ -451,15 +451,15 @@ get_n_operational_ts <- function(data, start, stop, times = NULL, plot = TRUE,.. #' @title Calculate the overlap between individuals' time at liberty and receivers' operational periods #' @description This function calculates the duration of the overlap (in days) between individuals' time at liberty and receivers' operational periods. To implement this function, a dataframe with individual deployment periods and another with receiver deployment periods must be specified. The duration of the overlap between these intervals can be calculated for all combinations of individuals and receivers within these two dataframes, for all combinations of specified individuals and receivers, or for specific individual/receiver pairs. The function returns a dataframe of the overlap duration for these individual/receiver combinations or a vector of values that is matched against another dataframe. -#' @param ids A dataframe that defines individual deployment periods. This must contain a column that defines individual IDs (named 'individual_id') and the time of tagging (named 'tag_start_date') and time of tag retrieval ('tag_end_date') (see \code{\link[flapper]{dat_ids}} for an example). -#' @param moorings A dataframe that defines receiver deployment periods. This must contain a column that defines receiver IDs (named 'receiver_id') and the time of receiver deployment (named 'receiver_start_date') and retrieval (named 'receiver_end_date') (see \code{\link[flapper]{dat_moorings}} for an example). +#' @param ids A dataframe that defines individual deployment periods. This must contain a column that defines individual IDs (named `individual_id') and the time of tagging (named `tag_start_date') and time of tag retrieval (`tag_end_date') (see \code{\link[flapper]{dat_ids}} for an example). +#' @param moorings A dataframe that defines receiver deployment periods. This must contain a column that defines receiver IDs (named `receiver_id') and the time of receiver deployment (named `receiver_start_date') and retrieval (named `receiver_end_date') (see \code{\link[flapper]{dat_moorings}} for an example). #' @param individual_id (optional) A vector of individuals for which to calculate overlap duration. #' @param receiver_id (optional) A vector of receivers for which to calculate overlap duration. #' @param type If both \code{individual_id} and \code{receiver_id} are specified, then \code{type} is an integer that defines whether or not to calculate overlap duration for (a) each individual/receiver pair (\code{type = 1L}) or (b) all combinations of specified individuals/receivers (\code{type = 2L}). -#' @param match_to (optional) A dataframe against which to match the calculated overlap duration(s). This must contain an 'individual_id' and 'receiver_id' column, as in \code{ids} and \code{moorings} respectively. If supplied, an integer vector of overlap durations for individual/receiver combinations, matched against the individuals/receivers in this dataframe, is returned (see also Value). +#' @param match_to (optional) A dataframe against which to match the calculated overlap duration(s). This must contain an `individual_id' and `receiver_id' column, as in \code{ids} and \code{moorings} respectively. If supplied, an integer vector of overlap durations for individual/receiver combinations, matched against the individuals/receivers in this dataframe, is returned (see also Value). #' @param ... Additional arguments (none implemented). #' -#' @return The function returns a dataframe with the deployment overlap duration for specific or all combinations of individuals and receivers, with the 'individual_id', 'receiver_id', 'tag_start_date', 'tag_end_date', 'receiver_start_date' and 'receiver_end_date' columns retained, plus 'tag_interval' and 'receiver_interval' columns that define individual and receiver deployment periods as \code{\link[lubridate]{Interval-class}} objects. The 'id_rec_overlap' column defines the temporal overlap (days). Alternatively, if \code{match_to} is supplied, a vector of overlap durations that matches each individual/receiver observation in that dataframe is returned. +#' @return The function returns a dataframe with the deployment overlap duration for specific or all combinations of individuals and receivers, with the `individual_id', `receiver_id', `tag_start_date', `tag_end_date', `receiver_start_date' and `receiver_end_date' columns retained, plus `tag_interval' and `receiver_interval' columns that define individual and receiver deployment periods as \code{\link[lubridate]{Interval-class}} objects. The `id_rec_overlap' column defines the temporal overlap (days). Alternatively, if \code{match_to} is supplied, a vector of overlap durations that matches each individual/receiver observation in that dataframe is returned. #' #' @examples #' #### Prepare data to include required columns @@ -587,14 +587,14 @@ get_id_rec_overlap <- function(ids, #' @param xy,detection_range,coastline,plot,... Arguments required to calculate and visualise detection centroids via \code{\link[flapper]{get_detection_centroids}}; namely, receiver locations (\code{xy}), the detection range (\code{detection_range}), barriers to detection (\code{coastline}) and whether or not to plot the centroids (\code{plot}). Additional arguments can be passed via \code{...} but note that \code{byid} is necessarily \code{TRUE} and should not be provided. #' @param envir A \code{\link[raster]{raster}} that defines the values of an environmental variable across the study area. The coordinate reference system should be the Universal Transverse Mercator system. -#' @param sample_size (optional) An integer that defines the number of samples of the environmental variable to draw from the area around each receiver (see the 'size' argument of \code{\link[base]{sample}}). If this is provided, \code{sample_size} samples are taken from this area; otherwise, all values are extracted. -#' @param sample_replace (optional) If \code{sample_size} is specified, \code{sample_replace} is a logical input that defines whether to implement sampling with (\code{sample_replace = TRUE}, the default) or without (\code{sample_replace = FALSE}) replacement (see the 'replace' argument of \code{\link[base]{sample}}). +#' @param sample_size (optional) An integer that defines the number of samples of the environmental variable to draw from the area around each receiver (see the `size' argument of \code{\link[base]{sample}}). If this is provided, \code{sample_size} samples are taken from this area; otherwise, all values are extracted. +#' @param sample_replace (optional) If \code{sample_size} is specified, \code{sample_replace} is a logical input that defines whether to implement sampling with (\code{sample_replace = TRUE}, the default) or without (\code{sample_replace = FALSE}) replacement (see the `replace' argument of \code{\link[base]{sample}}). #' @param sample_probs (optional) If \code{sample_size} is specified, \code{sample_probs} is a function that calculates the detection probability given the distance (m) between a cell and a receiver. #' @param cl A cluster object created by \code{\link[parallel]{makeCluster}}. If supplied, the connection to the cluster is closed within the function. #' @param varlist A character vector of names of objects to export, to be passed to the \code{varlist} argument of \code{\link[parallel]{clusterExport}}. This may be required if \code{cl} is supplied. Exported objects must be located in the global environment. #' @param verbose A logical variable that defines whether or not relay messages to the console to monitor function progress. #' -#' @return The function returns a list of dataframes (one for each element in \code{xy}; i.e., each receiver), each of which includes the cell IDs of \code{envir} from which values were extracted ('cell'), the value of the environmental variable in that cell ('envir') and, if applicable, the distance between that cell and the receiver ('dist', m) and the detection probability in that cell ('prob'). +#' @return The function returns a list of dataframes (one for each element in \code{xy}; i.e., each receiver), each of which includes the cell IDs of \code{envir} from which values were extracted (`cell'), the value of the environmental variable in that cell (`envir') and, if applicable, the distance between that cell and the receiver (`dist', m) and the detection probability in that cell (`prob'). #' #' @examples #' #### Define receiver locations as a SpatialPoints object with a UTM CRS @@ -779,13 +779,13 @@ get_detection_centroids_envir <- function(xy, #### get_detection_days() #' @title Calculate detection days -#' @description The function calculates the total number of days (termed 'detection days') during which individuals were detected at passive acoustic telemetry receivers. To implement the function, a dataframe with passive acoustic telemetry detections of individuals at receivers must be supplied. Detection days can be calculated for all combinations of individuals/receivers in this dataframe, for all combinations of specified individuals and receivers, or for specific individual/receiver pairs. The function returns a dataframe of detection days for these individual/receiver combinations or a vector of detection days that is matched against another dataframe. +#' @description The function calculates the total number of days (termed `detection days') during which individuals were detected at passive acoustic telemetry receivers. To implement the function, a dataframe with passive acoustic telemetry detections of individuals at receivers must be supplied. Detection days can be calculated for all combinations of individuals/receivers in this dataframe, for all combinations of specified individuals and receivers, or for specific individual/receiver pairs. The function returns a dataframe of detection days for these individual/receiver combinations or a vector of detection days that is matched against another dataframe. #' -#' @param acoustics A dataframe that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example). This should contain the following columns: a vector of individual IDs, named 'individual_id'; a vector of receiver IDs, named 'receiver_id'; and a POSIXct vector of time stamps when detections were made, named 'timestamp'. +#' @param acoustics A dataframe that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example). This should contain the following columns: a vector of individual IDs, named `individual_id'; a vector of receiver IDs, named `receiver_id'; and a POSIXct vector of time stamps when detections were made, named `timestamp'. #' @param individual_id (optional) A vector of individuals for which to calculate detection days. #' @param receiver_id (optional) A vector of receivers for which to calculate detection days. #' @param type If both \code{individual_id} and \code{receiver_id} are specified, then \code{type} is an integer that defines whether or not to calculate detection days for (a) each individual/receiver pair (\code{type = 1L}) or (b) all combinations of individuals/receivers. -#' @param match_to (optional) A dataframe against which to match detection days. This must contain the 'individual_id' and 'receiver_id' column, as in \code{acoustics}. If supplied, an integer vector of detection days for individual/receiver combinations, matched against the individuals/receivers in \code{match_to}, is returned (see also Value). +#' @param match_to (optional) A dataframe against which to match detection days. This must contain the `individual_id' and `receiver_id' column, as in \code{acoustics}. If supplied, an integer vector of detection days for individual/receiver combinations, matched against the individuals/receivers in \code{match_to}, is returned (see also Value). #' @param ... Additional arguments passed to \code{\link[pbapply]{pblapply}}. #' #' @return The function returns a dataframe with the detection days for all, or specified, combinations of individuals and receivers. Note that if \code{acoustics} only contains individuals/receivers that made detections, then this will only contain individuals/receivers for/at which detections were made. Alternatively, if \code{match_to} is supplied, a vector of detection days, matched against each individual/receiver observation in that dataframe, is returned. diff --git a/R/kud_tools.R b/R/kud_tools.R index c035e58..db4d3bf 100644 --- a/R/kud_tools.R +++ b/R/kud_tools.R @@ -3,15 +3,15 @@ #### kud_around_coastline() #' @title Process a kernel utilisation distribution around a barrier -#' @description Given an animal movement path over a gridded surface, this function estimates a 'raw' kernel utilisation distribution (from \code{\link[adehabitatHR]{kernelUD}}) and then processes the distribution to account for barriers to movement, such as coastline. To implement the function, the movement path(s) should be supplied as a SpatialPointsDataFrame and the grid over which estimation is implemented as a SpatialPixelsDataFrame with values 0 and 1 defining unsuitable and suitable habitat respectively. +#' @description Given an animal movement path over a gridded surface, this function estimates a `raw' kernel utilisation distribution (from \code{\link[adehabitatHR]{kernelUD}}) and then processes the distribution to account for barriers to movement, such as coastline. To implement the function, the movement path(s) should be supplied as a SpatialPointsDataFrame and the grid over which estimation is implemented as a SpatialPixelsDataFrame with values 0 and 1 defining unsuitable and suitable habitat respectively. #' #' @param xy A \code{\link[sp]{SpatialPointsDataFrame}} object that defines the movement path(s). This should contain a column that defines the individual ID(s) as a factor. #' @param grid A \code{\link[sp]{SpatialPixelsDataFrame}} object that defines the grid over which estimation is implemented and binary habitat suitability (0, unsuitable; or 1, suitable). #' @param ... Additional arguments passed to \code{\link[adehabitatHR]{kernelUD}}. #' -#' @details Utilisation distributions (UDs) are bivariate probability distributions that describe the probability (density) of locating an individual in any given area at a randomly chosen time. These can be estimated using the \code{\link[adehabitatHR]{kernelUD}} function. The algorithms implemented by this function can incorporate simple barriers, but restrictions on the shapes of barriers mean that in many real-world settings (e.g., in areas with complex coastline) barriers cannot be implemented. As a result, a pragmatic (if somewhat unsatisfactory) approach is to post-process the raw utilisation distribution by removing areas in which movement is impossible and then re-normalise the distribution (so that probabilities sum to one). This function achieves this by implementing the estimation over a grid, which defines whether (1) or not (0) an area is 'habitat'. After the estimation of the raw UD across the grid, probability density scores are combined (multipled) with the habitat suitability score (0, 1) and then renormalised (by dividing by the total score across suitable areas). +#' @details Utilisation distributions (UDs) are bivariate probability distributions that describe the probability (density) of locating an individual in any given area at a randomly chosen time. These can be estimated using the \code{\link[adehabitatHR]{kernelUD}} function. The algorithms implemented by this function can incorporate simple barriers, but restrictions on the shapes of barriers mean that in many real-world settings (e.g., in areas with complex coastline) barriers cannot be implemented. As a result, a pragmatic (if somewhat unsatisfactory) approach is to post-process the raw utilisation distribution by removing areas in which movement is impossible and then re-normalise the distribution (so that probabilities sum to one). This function achieves this by implementing the estimation over a grid, which defines whether (1) or not (0) an area is `habitat'. After the estimation of the raw UD across the grid, probability density scores are combined (multipled) with the habitat suitability score (0, 1) and then renormalised (by dividing by the total score across suitable areas). #' -#' @return The function returns an object of class 'estUDm'. This is a list, with one component per animal, of \code{\link[adehabitatHR]{estUD-class}} objects. The 'h' slot of the output (\code{output@h}) has been modified so that the method ('meth') is given as 'specified'. +#' @return The function returns an object of class `estUDm'. This is a list, with one component per animal, of \code{\link[adehabitatHR]{estUD-class}} objects. The `h' slot of the output (\code{output@h}) has been modified so that the method (`meth') is given as `specified'. #' #' @examples #' #### Set up diff --git a/R/make_dfs.R b/R/make_dfs.R index e51e141..4f07f28 100644 --- a/R/make_dfs.R +++ b/R/make_dfs.R @@ -1,12 +1,12 @@ #' @title Convert a detection matrix into a dataframe #' @description This function converts a matrix of detections (0, 1) by time stamp and receiver into a dataframe. #' -#' @param acoustics A detection matrix (time stamps x receivers) in which the cells define whether (1) or not (0) a detection was made at each time stamp/receiver combination. 'Meaningful' time stamps and receiver IDs can be taken from the row and column names of this matrix, if specified (see \code{set_names}). +#' @param acoustics A detection matrix (time stamps x receivers) in which the cells define whether (1) or not (0) a detection was made at each time stamp/receiver combination. `Meaningful' time stamps and receiver IDs can be taken from the row and column names of this matrix, if specified (see \code{set_names}). #' @param only_keep_detections A logical variable that defines whether or not to retain only observations that correspond to detections. (If \code{only_keep_detections = FALSE}, the returned dataframe includes time stamps without detections.) #' @param set_names A logical variable that defines whether or not to take the row and column names of \code{acoustics} as the time stamps and receiver IDs. (If \code{set_names = FALSE}, time stamps and receiver IDs are simply given as integer vectors of 1 to the number of rows or columns respectively.) #' @param as_POSIXct If \code{set_names = TRUE}, \code{as_POSIXct} is a function that converts the row names of \code{acoustics} into POSIXct time stamps. #' -#' @return The function returns a dataframe with time stamps ('timestamp') and receivers ('receiver_id'). If \code{set_names = FALSE}, these are integer vectors that match the dimensions of \code{acoustics}. Otherwise they are are taken from row and column names of \code{acoustics}. In this case, if \code{as_POSIXct} is defined, time stamps are returned in POSIXct format and receivers are returned as a factor. If \code{only_keep_detections = FALSE}, the dataframe also includes a 'detection' column that defines whether (1) or not (0) a detection was made for each observation; otherwise, this column is dropped (mirroring real-world data). +#' @return The function returns a dataframe with time stamps (`timestamp') and receivers (`receiver_id'). If \code{set_names = FALSE}, these are integer vectors that match the dimensions of \code{acoustics}. Otherwise they are are taken from row and column names of \code{acoustics}. In this case, if \code{as_POSIXct} is defined, time stamps are returned in POSIXct format and receivers are returned as a factor. If \code{only_keep_detections = FALSE}, the dataframe also includes a `detection' column that defines whether (1) or not (0) a detection was made for each observation; otherwise, this column is dropped (mirroring real-world data). #' #' @examples #' #### Define detection matrix diff --git a/R/make_matrices.R b/R/make_matrices.R index 5862147..bcfc0b7 100644 --- a/R/make_matrices.R +++ b/R/make_matrices.R @@ -7,9 +7,9 @@ #' #' @description This function creates a matrix that, for each time step (matrix row) in a sequence of user-defined times, defines whether or not each individual (matrix column) was at liberty. To implement the function, a dataframe with individual IDs and deployment start and end times must be supplied (via \code{ids}). The times for which to express whether or not each individual was at liberty are provided by optionally defining a \code{start} and \code{end} date (these can be taken from the range of deployment times in \code{ids} if unspecified) and the interval (\code{delta_t}) between time steps. #' -#' @param ids A dataframe that defines individual IDs and deployment times. This must contain the following columns: an identifier for individuals (named 'individual_id'), the start time of individuals' deployment periods ('tag_start_date') and the end time of individuals' deployment periods ('tag_end_date'). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see \code{as_POSIXct}). +#' @param ids A dataframe that defines individual IDs and deployment times. This must contain the following columns: an identifier for individuals (named `individual_id'), the start time of individuals' deployment periods (`tag_start_date') and the end time of individuals' deployment periods (`tag_end_date'). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see \code{as_POSIXct}). #' @param start,end Date or POSIXct objects that define the start and end time. If unspecified, these are taken from the range of deployment times in \code{ids}. -#' @param delta_t A number or character that defines the time interval between successive time steps. This is passed to the 'by' argument of \code{\link[base]{seq.POSIXt}}. +#' @param delta_t A number or character that defines the time interval between successive time steps. This is passed to the `by' argument of \code{\link[base]{seq.POSIXt}}. #' @param as_POSIXct A function that coerces any supplied times (\code{ids$tag_start_date}, \code{ids$tag_end_date}, \code{start} and \code{end}) that are not POSIXct objects to POSIXct objects. #' @param set_names A logical variable that defines whether or not to set the row and column names of the matrix to the time steps and the individual IDs respectively. #' @param ... Additional arguments (none implemented). @@ -65,9 +65,9 @@ make_matrix_ids <- function(ids, #' #' @description This function creates a matrix that, for each time step (matrix row) in a sequence of user-defined times, defines whether or not each receiver (matrix column) was active. To implement the function, a dataframe with receiver IDs and deployment start and end times must be supplied (via \code{moorings}). The times for which to express whether or not each receiver was active are provided by optionally defining a \code{start} and \code{end} date (these can be taken from the range of deployment times in \code{moorings} if unspecified) and the interval (\code{delta_t}) between time steps. #' -#' @param moorings A dataframe that defines receiver IDs and deployment times. This must contain the following columns: an identifier for receivers (named 'receiver_id'), the start time of receiver' deployment periods ('receiver_start_date') and the end time of receivers' deployment periods ('receiver_end_date') (see \code{\link[flapper]{dat_moorings}} for an example). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see \code{as_POSIXct}). +#' @param moorings A dataframe that defines receiver IDs and deployment times. This must contain the following columns: an identifier for receivers (named `receiver_id'), the start time of receiver' deployment periods (`receiver_start_date') and the end time of receivers' deployment periods (`receiver_end_date') (see \code{\link[flapper]{dat_moorings}} for an example). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see \code{as_POSIXct}). #' @param start,end Date or POSIXct objects that define the start and end time. If unspecified, these are taken from the range of deployment times in \code{moorings}. -#' @param delta_t A number or character that defines the time interval between successive time steps. This is passed to the 'by' argument of \code{\link[base]{seq.POSIXt}}. +#' @param delta_t A number or character that defines the time interval between successive time steps. This is passed to the `by' argument of \code{\link[base]{seq.POSIXt}}. #' @param as_POSIXct A function that coerces supplied any supplied times (\code{moorings$receiver_start_date}, \code{moorings$receiver_end_date}, \code{start} and \code{end}) that are not POSIXct objects to POSIXct objects. #' @param set_names A logical variable that defines whether or not to set the row and column names of the matrix to the time steps and the receiver IDs respectively. #' @param ... Additional arguments (none implemented). @@ -117,12 +117,12 @@ make_matrix_receivers <- function(moorings, #### make_matrix_detections() #' @title Matricise detection time series -#' @description This function creates a list of matrices that, for each individual (list element), defines the number of detections of that individual in each time interval (matrix row) at each receiver (matrix column). To implement the function, a dataframe with acoustic detection time series must be provided via \code{acoustics}. The time intervals over which to count detections are provided by optionally defining a \code{start} and \code{end} date (these can be taken from the range of times in \code{acoustics} if unspecified) and the interval (\code{delta_t}) between time steps. By default, matrix elements that are 'outside' individual or receiver deployment periods are defined as 0 (not detected) but can be changed to another value (e.g., NA) via \code{set_outside}. In this case, the \code{acoustics} dataframe also needs to include the deployment times for each individual and an additional dataframe must be supplied with the same information for receivers via \code{moorings}. +#' @description This function creates a list of matrices that, for each individual (list element), defines the number of detections of that individual in each time interval (matrix row) at each receiver (matrix column). To implement the function, a dataframe with acoustic detection time series must be provided via \code{acoustics}. The time intervals over which to count detections are provided by optionally defining a \code{start} and \code{end} date (these can be taken from the range of times in \code{acoustics} if unspecified) and the interval (\code{delta_t}) between time steps. By default, matrix elements that are `outside' individual or receiver deployment periods are defined as 0 (not detected) but can be changed to another value (e.g., NA) via \code{set_outside}. In this case, the \code{acoustics} dataframe also needs to include the deployment times for each individual and an additional dataframe must be supplied with the same information for receivers via \code{moorings}. #' -#' @param acoustics A dataframe that defines passive acoustic telemetry detection time series. This should contain the following columns: a vector of individual IDs, named 'individual_id'; a (factor) vector of receiver IDs, named 'receiver_id'. If \code{set_outside} is specified, this should also contain POSIXct vectors of the start and end time of each individual's time at liberty, named 'tag_start_date' and 'tag_end_date' respectively. -#' @param moorings (optional) If \code{set_outside} is specified, \code{moorings} is dataframe that defines passive acoustic telemetry receiver metadata. This should contain the following columns: a vector of receiver IDs, named 'receiver_id (as in \code{acoustics}); and POSIXct vectors of the start and end times of each receiver's deployment time, named 'receiver_start_date' and 'receiver_end_date' respectively. +#' @param acoustics A dataframe that defines passive acoustic telemetry detection time series. This should contain the following columns: a vector of individual IDs, named `individual_id'; a (factor) vector of receiver IDs, named `receiver_id'. If \code{set_outside} is specified, this should also contain POSIXct vectors of the start and end time of each individual's time at liberty, named `tag_start_date' and `tag_end_date' respectively. +#' @param moorings (optional) If \code{set_outside} is specified, \code{moorings} is dataframe that defines passive acoustic telemetry receiver metadata. This should contain the following columns: a vector of receiver IDs, named `receiver_id (as in \code{acoustics}); and POSIXct vectors of the start and end times of each receiver's deployment time, named `receiver_start_date' and `receiver_end_date' respectively. #' @param start,end POSIXct objects that define the start and end time. If unspecified, these are taken from the range of detection times in \code{acoustics}. -#' @param delta_t A number or character that defines the time interval between successive time steps. This is passed to the 'by' argument of \code{\link[base]{seq.POSIXt}}. +#' @param delta_t A number or character that defines the time interval between successive time steps. This is passed to the `by' argument of \code{\link[base]{seq.POSIXt}}. #' @param simplify (optional) A function that simplifies detection matrices, such as \code{function(x) (x > 0) + 0} to convert counts into a boolean outcomes that define whether or a detection was made. #' @param set_outside (optional) A value (e.g., \code{NA}) that is assigned to any matrix element that is outside of an individual's or receiver's deployment period when detection was not possible. #' @param as_POSIXct A function that coerces any supplied times that are not POSIXct objects to POSIXct objects. @@ -275,14 +275,14 @@ make_matrix_detections <- function(acoustics, #### make_matrix_cooccurence() #' @title Compute a detection history similarity matrix -#' @description The function computes a detection history similarity matrix. For all combinations of individuals, this shows the total number (or percentage) of detections 'nearby' in space and time, which can help to elucidate possible interactions among individuals that affect space use (see Details). To compute this matrix, the function pairs detections for each individual with the detections nearest in time for each other individual. The function computes the time (minutes) between paired detection time series, and the distance (m) between the receiver(s) at which paired detections occurred, dropping any detection pairs that are further apart in time or space than user-defined thresholds (which depend on the mobility of the species under investigation). For each combination of individuals, the function returns total number (or percentage) of detections that are closely associated in time and space. For very large combinations of individuals, especially those with long, overlapping time series, the function may take some time to run; therefore, testing the function on a small subset of individuals first is advisable. Parallelisation can be used to improve computation time. Similarity matrices can be visualised with \code{\link[prettyGraphics]{pretty_mat}}. +#' @description The function computes a detection history similarity matrix. For all combinations of individuals, this shows the total number (or percentage) of detections `nearby' in space and time, which can help to elucidate possible interactions among individuals that affect space use (see Details). To compute this matrix, the function pairs detections for each individual with the detections nearest in time for each other individual. The function computes the time (minutes) between paired detection time series, and the distance (m) between the receiver(s) at which paired detections occurred, dropping any detection pairs that are further apart in time or space than user-defined thresholds (which depend on the mobility of the species under investigation). For each combination of individuals, the function returns total number (or percentage) of detections that are closely associated in time and space. For very large combinations of individuals, especially those with long, overlapping time series, the function may take some time to run; therefore, testing the function on a small subset of individuals first is advisable. Parallelisation can be used to improve computation time. Similarity matrices can be visualised with \code{\link[prettyGraphics]{pretty_mat}}. #' -#' @param acoustics_ls A list of dataframes, with one element for each individual, which contains each individual's detection time series. Each dataframe must include the following columns: 'individual_id', a factor which specifies unique individuals; 'timestamp', a POSIXct object which specifies the time of each detection; 'receiver_long', the longitude (decimal degrees) of the receiver(s) at the individual was detected; and 'receiver_lat', the latitude (decimal degrees) of the receiver(s) at which individual was detected. Each dataframe should be ordered by 'individual_id' and then by 'timestamp'. Careful ordering of 'individual_id' factor levels (e.g. perhaps by population group, then by the number of detections of each individual) can aid visualisation of similarity matrices, in which the order or rows/columns corresponds directly to the order of individuals in \code{acoustics_ls}. Sequential elements in \code{acoustics_ls} should correspond to sequential factor levels for 'individual_id', which should be the same across all dataframes. +#' @param acoustics_ls A list of dataframes, with one element for each individual, which contains each individual's detection time series. Each dataframe must include the following columns: `individual_id', a factor which specifies unique individuals; `timestamp', a POSIXct object which specifies the time of each detection; `receiver_long', the longitude (decimal degrees) of the receiver(s) at the individual was detected; and `receiver_lat', the latitude (decimal degrees) of the receiver(s) at which individual was detected. Each dataframe should be ordered by `individual_id' and then by `timestamp'. Careful ordering of `individual_id' factor levels (e.g. perhaps by population group, then by the number of detections of each individual) can aid visualisation of similarity matrices, in which the order or rows/columns corresponds directly to the order of individuals in \code{acoustics_ls}. Sequential elements in \code{acoustics_ls} should correspond to sequential factor levels for `individual_id', which should be the same across all dataframes. #' @param thresh_time A number which specifies the time, in minutes, after which detections at nearby receivers are excluded. #' @param thresh_dist A number which specifies the (Euclidean) distance between receivers, in metres, beyond which detections are excluded (see Details). #' @param cl (optional) A cluster object created by \code{\link[parallel]{makeCluster}}. This is required if you want to run the algorithm in parallel. If supplied, the connection to the cluster is stopped within the function. #' @param varlist (optional) A character vector of names of objects to export, to be passed to the \code{varlist} argument of \code{\link[parallel]{clusterExport}}. This may be required if \code{cl} is supplied. Exported objects must be located in the global environment. -#' @param output A number which specifies the output type. If \code{output = 1}, the function returns a (usually) symmetric similarity matrix in which each number represents the number of detections nearby in space and time for each pair of individuals. Row and column names are assigned from the 'individual_id' column in \code{acoustics_ls} dataframes. This matrix is usually symmetric, but this is not necessarily the case for data collected from tags which transmit at random intervals around a nominal delay: under this scenario, the tag for a given individual (i) may transmit multiple signals in the space of time that the tag for another individual (j) only releases a single transmission. In this case, the pairing i,j will comprise all unique transmissions for individual i, paired with the nearest observations for individual j, some of which will be duplicate observations. Therefore, this pairing will contain more 'shared observations' than the pairing j,i. However, even under random transmission, the matrix will usually be either symmetric or very nearly symmetric, with only small differences between identical pairs. If \code{output = 2}, the function returns a list with the following elements: (1) 'mat_sim', the symmetric similarity matrix (see above); 'mat_nobs', a matrix with the same dimensions as 'mat_sim' which specifies the number of observations for each individual (by row, used to calculate 'mat_pc', see later); 'mat_pc', a non-symmetric matrix in which each cell represents the percent of observations of the individual in the i'th row that are shared with the individual in the j'th column; and 'dat', a nested list, with one element for each individual which comprises a list of dataframes, one for each other individual, each one of which contains the subset of observations that are shared between the two individuals. Each dataframe contains the same columns as in the \code{acoustics_ls} dataframes with the following columns added: 'pos_in_acc2', 'timestamp_acc2', 'receiver_lat_acc2' and 'receiver_long_acc2', which represent the positions, time stamps and locations of corresponding observations in the second individual's dataframe to the first individual's dataframe, and 'difftime_abs' and 'dist_btw_receivers' which represent the duration (minutes) and distances (m) between corresponding observations. When there are no shared observations between a pair of individuals, the element simply contains \code{NULL}. Note that 'mat_pc' is computed by (mat_sim/mat_nobs)*100. The matrix is therefore non-symmetric (if individuals have differing numbers of observations); i.e., mat_pc[i, j] is the percent of individual i's observations that are shared with individual j; while mat_pc[j, i] is the percent of individual j's observations that are shared with individual i. NaN elements are possible in 'mat_pc' for levels of the factor 'individual_id' without observations. +#' @param output A number which specifies the output type. If \code{output = 1}, the function returns a (usually) symmetric similarity matrix in which each number represents the number of detections nearby in space and time for each pair of individuals. Row and column names are assigned from the `individual_id' column in \code{acoustics_ls} dataframes. This matrix is usually symmetric, but this is not necessarily the case for data collected from tags which transmit at random intervals around a nominal delay: under this scenario, the tag for a given individual (i) may transmit multiple signals in the space of time that the tag for another individual (j) only releases a single transmission. In this case, the pairing i,j will comprise all unique transmissions for individual i, paired with the nearest observations for individual j, some of which will be duplicate observations. Therefore, this pairing will contain more `shared observations' than the pairing j,i. However, even under random transmission, the matrix will usually be either symmetric or very nearly symmetric, with only small differences between identical pairs. If \code{output = 2}, the function returns a list with the following elements: (1) `mat_sim', the symmetric similarity matrix (see above); `mat_nobs', a matrix with the same dimensions as `mat_sim' which specifies the number of observations for each individual (by row, used to calculate `mat_pc', see later); `mat_pc', a non-symmetric matrix in which each cell represents the percent of observations of the individual in the i'th row that are shared with the individual in the j'th column; and `dat', a nested list, with one element for each individual which comprises a list of dataframes, one for each other individual, each one of which contains the subset of observations that are shared between the two individuals. Each dataframe contains the same columns as in the \code{acoustics_ls} dataframes with the following columns added: `pos_in_acc2', `timestamp_acc2', `receiver_lat_acc2' and `receiver_long_acc2', which represent the positions, time stamps and locations of corresponding observations in the second individual's dataframe to the first individual's dataframe, and `difftime_abs' and `dist_btw_receivers' which represent the duration (minutes) and distances (m) between corresponding observations. When there are no shared observations between a pair of individuals, the element simply contains \code{NULL}. Note that `mat_pc' is computed by (mat_sim/mat_nobs)*100. The matrix is therefore non-symmetric (if individuals have differing numbers of observations); i.e., mat_pc[i, j] is the percent of individual i's observations that are shared with individual j; while mat_pc[j, i] is the percent of individual j's observations that are shared with individual i. NaN elements are possible in `mat_pc' for levels of the factor `individual_id' without observations. #' @param verbose A logical input which specifies whether or not to print messages to the console which relay function progress. This is ignored if \code{cl} is supplied. #' #' @details diff --git a/R/processing.R b/R/processing.R index 6b52ee3..9a86bb3 100644 --- a/R/processing.R +++ b/R/processing.R @@ -5,8 +5,8 @@ #' @title Add unique receiver IDs to passive acoustic telemetry time series #' @description This function extracts the unique receiver deployment IDs (e.g., 1,...n) from a dataframe containing receiver attributes (e.g. unique receiver deployment IDs, receiver codes and locations), termed \code{moorings}, that correspond to passive acoustic telemetry (PAT) receiver codes in detection time series, termed \code{acoustics}. This is especially useful if the same receiver has been deployed multiple times (e.g. in different locations) over the course of the study. In this scenario, the receiver code in the PAT detection time series does not uniquely identify the unique receiver deployment, which means that receiver codes in PAT data and metadata cannot simply be matched: instead, both receiver code(s) and the time of detection(s) need to be included in the matching procedure. In this case, \code{\link[flapper]{process_receiver_id}} examines each receiver with detections in \code{acoustics}. If that receiver was redeployed, the function examines the time of each detection and returns the ID of the receiver that recorded that detection (given the timing of receiver deployment). If each receiver was only deployed once, this function simply matches receiver codes in \code{moorings} and receiver codes in \code{acoustics} and returns the receiver IDs (which, in this case, may be the same as the receiver codes) in \code{moorings} that correspond to each receiver code in \code{acoustics}. #' -#' @param acoustics A dataframe which comprises passive acoustic telemetry detection time series. This must contain two named columns: 'timestamp', a POSIXct vector which defines the time of each detection; and 'receiver', a vector which defines the receiver at which each detection was made. The column 'receiver' should also be found in \code{moorings} (see below). -#' @param moorings A dataframe which contains passive acoustic telemetry receiver metadata. This must contain four named columns: 'receiver', as above for \code{acoustics}; 'receiver_id', a unique identifier for each receiver deployment; 'receiver_start_date', a POSIXct vector which defines the time of each receiver deployment; and 'receiver_end_date', a POSIXct vector which defines the end of each receiver deployment. If objects of class Date are provided for 'receiver_start_date' and 'receiver_end_date', these are coerced to POSIXct objects with a warning so that the timing of receiver detections and deployment is comparable (i.e., of the same object type). +#' @param acoustics A dataframe which comprises passive acoustic telemetry detection time series. This must contain two named columns: `timestamp', a POSIXct vector which defines the time of each detection; and `receiver', a vector which defines the receiver at which each detection was made. The column `receiver' should also be found in \code{moorings} (see below). +#' @param moorings A dataframe which contains passive acoustic telemetry receiver metadata. This must contain four named columns: `receiver', as above for \code{acoustics}; `receiver_id', a unique identifier for each receiver deployment; `receiver_start_date', a POSIXct vector which defines the time of each receiver deployment; and `receiver_end_date', a POSIXct vector which defines the end of each receiver deployment. If objects of class Date are provided for `receiver_start_date' and `receiver_end_date', these are coerced to POSIXct objects with a warning so that the timing of receiver detections and deployment is comparable (i.e., of the same object type). #' #' @details The function implements \code{\link[data.table]{foverlaps}} to overlap the timing of detections with the timing of receiver deployments to account for receiver deployment in the assignment of receiver IDs. #' @@ -123,14 +123,14 @@ process_receiver_id <- #' #' This function passes false detections flagged by \code{\link[glatos]{false_detections}} through a spatial filter. The key idea is that detections at nearby receivers within a defined time window may, in fact, be plausible. To implement this approach, the user must define a dataframe comprising detections, a temporal threshold, a spatial threshold and a dataframe of distances between receivers. The function examines whether any putative false detections are accompanied by additional detections at other receivers within a user-defined time window and Euclidean distance of that receiver. If so, these could be explained by an individual that dips in-and-out of the detection ranges of receivers (e.g. in a sparse acoustic array) and may not, in fact, be false. #' -#' @param det A dataframe containing detection time series. Following \code{\link[glatos]{false_detections}}, this should contain the following columns: 'detection_timestamp_utc', 'transmitter_codespace', 'transmitter_id' and 'receiver_sn', as well as 'passed_filter' (see \code{\link[glatos]{false_detections}}). +#' @param det A dataframe containing detection time series. Following \code{\link[glatos]{false_detections}}, this should contain the following columns: `detection_timestamp_utc', `transmitter_codespace', `transmitter_id' and `receiver_sn', as well as `passed_filter' (see \code{\link[glatos]{false_detections}}). #' @param tf A number that defines the time threshold (s) used to flag false detections (see \code{\link[glatos]{false_detections}}). #' @param sf A number that defines the threshold Euclidean distance between receivers beyond which, even if a false detection is accompanied by detections at other receivers, it is likely to be a true false detection, because the individual could not have moved between receivers separated by more than this threshold over the specified time interval. \code{sf} should be defined in the same units as the distances provided in \code{dist_btw_receivers} (see below). -#' @param dist_btw_receivers A dataframe that defines the distances between receiver pairs. This should contain the columns: 'r1', 'r2' and 'dist', whereby 'r1' and 'r2' contain the unique receiver serial number for all combinations of receivers and 'dist' contains the distance between them. This dataframe should include duplicate combinations (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). This can be created with \code{\link[flapper]{dist_btw_receivers}}. +#' @param dist_btw_receivers A dataframe that defines the distances between receiver pairs. This should contain the columns: `r1', `r2' and `dist', whereby `r1' and `r2' contain the unique receiver serial number for all combinations of receivers and `dist' contains the distance between them. This dataframe should include duplicate combinations (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). This can be created with \code{\link[flapper]{dist_btw_receivers}}. #' #' @details There are limitations with the application of this spatial filter to false detections. First, the spatial threshold beyond which false detections are likely to be false is based on Euclidean distances at present. These may be problematic (e.g. when receivers hug complex coastlines). Second, for small arrays, fast-swimming organisms and/or a large nominal transmission delay (i.e., time threshold), the spatial filter is a poor filter because individuals can access the whole area over the whole time interval. #' -#' @return The function returns a vector, of the same length as \code{det} with three possible values: NA, which identifies detections which have not been flagged as false detections (i.e., \code{passed_filter = 0}, see \code{\link[glatos]{false_detections}}) and are therefore not passed through the spatial filter; 1, which identifies detections which 'passed' the spatial filter (i.e., false detections which are accompanied by detections at nearby receivers within the defined spatial and temporal thresholds); or 0, which defines detections which 'failed' the spatial filter (i.e., false detections which are not accompanied by detections at nearby receivers within the defined spatial and temporal thresholds). This vector has one attribute, 'details', a dataframe with the same number of rows as \code{det} with the following columns: 'passed_filter_sf', 'n_wn_sf', 'detection_timestamp_utc_sf' and 'receiver_sn_sf'. 'passed_filter_sf' takes a value of NA, 0 or 1 depending on whether or not the detection was flagged as a false detection (if not, NA) and whether each false detection passed the spatial filter (no, 0; yes, 1). If the detection did pass the spatial filter, 'n_wn_sf' provides the number of detections at nearby receivers within \code{tf} and \code{sf}; and 'detection_timestamp_utc_sf', 'receiver_sn_sf' and 'dist_sf' define the timestamp of the detection at the nearest receiver, the receiver at which the detection was made and the distance between the two receivers respectively. +#' @return The function returns a vector, of the same length as \code{det} with three possible values: NA, which identifies detections which have not been flagged as false detections (i.e., \code{passed_filter = 0}, see \code{\link[glatos]{false_detections}}) and are therefore not passed through the spatial filter; 1, which identifies detections which `passed' the spatial filter (i.e., false detections which are accompanied by detections at nearby receivers within the defined spatial and temporal thresholds); or 0, which defines detections which `failed' the spatial filter (i.e., false detections which are not accompanied by detections at nearby receivers within the defined spatial and temporal thresholds). This vector has one attribute, `details', a dataframe with the same number of rows as \code{det} with the following columns: `passed_filter_sf', `n_wn_sf', `detection_timestamp_utc_sf' and `receiver_sn_sf'. `passed_filter_sf' takes a value of NA, 0 or 1 depending on whether or not the detection was flagged as a false detection (if not, NA) and whether each false detection passed the spatial filter (no, 0; yes, 1). If the detection did pass the spatial filter, `n_wn_sf' provides the number of detections at nearby receivers within \code{tf} and \code{sf}; and `detection_timestamp_utc_sf', `receiver_sn_sf' and `dist_sf' define the timestamp of the detection at the nearest receiver, the receiver at which the detection was made and the distance between the two receivers respectively. #' #' @examples #' #### Add some false detections for demonstration purposes @@ -339,11 +339,11 @@ process_false_detections_sf <- #### process_quality_check() #' @title Basic quality checks of passive acoustic telemetry datasets -#' @description This function passes through passive acoustic telemetry datasets through some basic quality checks (see Details). Following data processing, these provide a useful 'final check' prior to analysis. +#' @description This function passes through passive acoustic telemetry datasets through some basic quality checks (see Details). Following data processing, these provide a useful `final check' prior to analysis. #' -#' @param acoustics A dataframe which comprises passive acoustic telemetry detection time series. This must contain the following named columns: 'timestamp', a POSIXct vector which defines the time of each detection; 'receiver_id', a unique identifier of each receiver; and 'individual_id', a unique identifier of each individual (see \code{\link[flapper]{dat_acoustics}} for an example). -#' @param moorings A dataframe which contains passive acoustic telemetry receiver metadata. This must contain the following named columns: 'receiver_id', a unique identifier for each receiver deployment; 'receiver_start_date', a POSIXct vector which defines the time of each receiver's deployment; and 'receiver_end_date', a POSIXct vector which defines the end of each receiver's deployment (see \code{\link[flapper]{dat_moorings}} for an example). If objects of class Date are provided for 'receiver_start_date' and 'receiver_end_date', these are coerced to POSIXct objects with a warning. -#' @param ids A dataframe which contains the passive acoustic telemetry individual metadata. This must contain the following named columns: 'individual_id', a unique identifier for each individual; 'tag_start_date', a POSIXct vector which defines the time of each tag's deployment; and 'tag_end_date', a POSIXct vector which defines the end of each tag's deployment (see \code{\link[flapper]{dat_ids}} for an example). If objects of class Date are provided for 'tag_start_date' and 'tag_end_date', these are coerced to POSIXct objects with a warning. +#' @param acoustics A dataframe which comprises passive acoustic telemetry detection time series. This must contain the following named columns: `timestamp', a POSIXct vector which defines the time of each detection; `receiver_id', a unique identifier of each receiver; and `individual_id', a unique identifier of each individual (see \code{\link[flapper]{dat_acoustics}} for an example). +#' @param moorings A dataframe which contains passive acoustic telemetry receiver metadata. This must contain the following named columns: `receiver_id', a unique identifier for each receiver deployment; `receiver_start_date', a POSIXct vector which defines the time of each receiver's deployment; and `receiver_end_date', a POSIXct vector which defines the end of each receiver's deployment (see \code{\link[flapper]{dat_moorings}} for an example). If objects of class Date are provided for `receiver_start_date' and `receiver_end_date', these are coerced to POSIXct objects with a warning. +#' @param ids A dataframe which contains the passive acoustic telemetry individual metadata. This must contain the following named columns: `individual_id', a unique identifier for each individual; `tag_start_date', a POSIXct vector which defines the time of each tag's deployment; and `tag_end_date', a POSIXct vector which defines the end of each tag's deployment (see \code{\link[flapper]{dat_ids}} for an example). If objects of class Date are provided for `tag_start_date' and `tag_end_date', these are coerced to POSIXct objects with a warning. #' #' @details The function implements the following checks: #' \enumerate{ @@ -354,7 +354,7 @@ process_false_detections_sf <- #' \item False detections. False detections should be flagged. #' } #' -#' \code{\link[flapper]{process_quality_check}} is mainly designed to be implemented after data-processing has already taken place as a basic 'final check' for common issues in passive acoustic telemetry datasets. For each check, the function returns a message or warning depending on the outcome; subsequently, the most appropriate course of action (e.g., retention versus removal of flagged observations in \code{acoustics} will depend on the context). Other important checks -- such as checking for receivers which were lost and later recovered, excluding observations during receiver servicing dates, excluding observations during tag capture events and further investigation of false detections -- may be required. +#' \code{\link[flapper]{process_quality_check}} is mainly designed to be implemented after data-processing has already taken place as a basic `final check' for common issues in passive acoustic telemetry datasets. For each check, the function returns a message or warning depending on the outcome; subsequently, the most appropriate course of action (e.g., retention versus removal of flagged observations in \code{acoustics} will depend on the context). Other important checks -- such as checking for receivers which were lost and later recovered, excluding observations during receiver servicing dates, excluding observations during tag capture events and further investigation of false detections -- may be required. #' #' @return For each check, the function returns a message or a warning with relevant details. #' diff --git a/R/queries.R b/R/queries.R index ee0fec8..0f691de 100644 --- a/R/queries.R +++ b/R/queries.R @@ -10,7 +10,7 @@ #' #' @details Open Topo Data is an elevation API. Further information, including on supported datasets, supported numbers of locations (which, at the time of writing, is limited to 100) and other details are provided here: https://www.opentopodata.org/. This function requires the \code{\link[httr]{httr}} and \code{\link[jsonlite]{jsonlite}} packages to query databases. #' -#' @return The function returns elevation ('z') values from the specified database as a matrix, if code \code{x} is a matrix, or a \code{\link[raster]{raster}}, if code \code{x} is a \code{\link[raster]{raster}} or an \code{\link[raster]{Extent}} object. Coordinates/areas without data are returned as NAs. +#' @return The function returns elevation (`z') values from the specified database as a matrix, if code \code{x} is a matrix, or a \code{\link[raster]{raster}}, if code \code{x} is a \code{\link[raster]{raster}} or an \code{\link[raster]{Extent}} object. Coordinates/areas without data are returned as NAs. #' #' @examples #' \dontrun{ diff --git a/R/sims.R b/R/sims.R index 2be4429..67b5f6d 100644 --- a/R/sims.R +++ b/R/sims.R @@ -7,7 +7,7 @@ #' #' @param boundaries An \code{\link[raster]{extent}} object that defines the boundaries of the (simulated) study area. #' @param coastline (optional) This argument is used to incorporate the presence of barriers, such as coastline, in the area. There are three options. If \code{coastline = NULL}, no barriers are incorporated. If \code{coastline = "simple_random"}, then a triangular island is simulated in the study area. Alternatively, a spatial object, such as a SpatialPolygonsDataFrame, that defines the coastline in an area can be incorporated into the array design by passing this \code{coastline}. -#' @param land_inside_coastline A logical variable that defines whether or not the land is 'inside' the polygon(s) defined by \code{coastline} (\code{land_inside_coastline = TRUE}) or the sea is 'inside' the polygon(s) (\code{land_inside_coastline = FALSE}). +#' @param land_inside_coastline A logical variable that defines whether or not the land is `inside' the polygon(s) defined by \code{coastline} (\code{land_inside_coastline = TRUE}) or the sea is `inside' the polygon(s) (\code{land_inside_coastline = FALSE}). #' @param n_receivers An integer that defines the number of receivers in the array. This is ignored if receiver locations are specified via \code{arrangement}. #' @param arrangement,... A character string or a SpatialPoints object that defines the arrangement of receivers. Supported character string options for simulated arrays are \code{"regular"}, \code{"random"}, \code{"stratified"}, \code{"nonaligned"}, \code{"hexagonal"} and \code{"clustered"} (see \code{\link[sp]{spsample}}, which is used to simulate receiver locations). Additional arguments can be passed to this function via \code{...} for further control. Otherwise, a SpatialPoints object that defines the coordinates of receivers (in the same coordinate reference system as \code{boundaries} and, if applicable, \code{coastline}) is assumed to have been provided. #' @param seed An integer that is used to set the seed to enable reproducible simulations (see \code{\link[base]{set.seed}}). @@ -18,7 +18,7 @@ #' #' @details Note that this function does not currently support temporally varying array designs. #' -#' @return The function returns a named list of (a) the spatial objects that define the simulated array ('array') and (b) the arguments used to generate this array ('args'). The 'array' element is a named list contains the following elements: 'boundaries', an \code{\link[raster]{Extent-class}} object that defines the boundaries of the area (as inputted); 'area', a \code{\link[sp]{SpatialPolygons-class}} object that defines the boundaries of the area; 'land' and 'sea', \code{\link[sp]{SpatialPolygons-class}} or \code{\link[sp]{SpatialPolygonsDataFrame-class}} objects that define the land and sea respectively; and 'xy', a \code{\link[sp]{SpatialPoints-class}} object that defines receiver locations. If \code{plot = TRUE}, the function also returns a plot of the array. +#' @return The function returns a named list of (a) the spatial objects that define the simulated array (`array') and (b) the arguments used to generate this array (`args'). The `array' element is a named list contains the following elements: `boundaries', an \code{\link[raster]{Extent-class}} object that defines the boundaries of the area (as inputted); `area', a \code{\link[sp]{SpatialPolygons-class}} object that defines the boundaries of the area; `land' and `sea', \code{\link[sp]{SpatialPolygons-class}} or \code{\link[sp]{SpatialPolygonsDataFrame-class}} objects that define the land and sea respectively; and `xy', a \code{\link[sp]{SpatialPoints-class}} object that defines receiver locations. If \code{plot = TRUE}, the function also returns a plot of the array. #' #' @examples #' #### Example (1): Simulate an array using default parameters @@ -250,7 +250,7 @@ NULL #' #' This function requires the \code{\link[circular]{circular}} package. #' -#' @return The function returns a named list of arguments that defines the simulated path ('xy_mat', 'angle_mat', 'step_mat' and 'path') and a named list of arguments that were used to generate the path ('args'). 'xy_mat' is an n-row, two-column matrix that defines the simulated position (x, y) at each time step; 'angle_mat' and 'step_mat' are n-row, one-column matrices that define the simulated turning angle (degrees) and step length (in map units) at each time step; and 'path' is a \code{\link[sp]{SpatialLines}} representation of the movement path. +#' @return The function returns a named list of arguments that defines the simulated path (`xy_mat', `angle_mat', `step_mat' and `path') and a named list of arguments that were used to generate the path (`args'). `xy_mat' is an n-row, two-column matrix that defines the simulated position (x, y) at each time step; `angle_mat' and `step_mat' are n-row, one-column matrices that define the simulated turning angle (degrees) and step length (in map units) at each time step; and `path' is a \code{\link[sp]{SpatialLines}} representation of the movement path. #' #' @seealso For movement simulations, see \code{\link[flapper]{sim_path_*}} for the full list of functions currently implemented in \code{\link[flapper]{flapper}}. For example, \code{\link[flapper]{sim_path_ou_1}} simulates a movement path based on past locations according to an Ornstein-Uhlenbeck process (which is not based on step lengths and turning angles). More broadly, \code{\link[flapper]{sim_array}}, \code{\link[flapper]{sim_path_*}} and \code{\link[flapper]{sim_detections}} provide an integrated workflow for simulating acoustic arrays, movement paths in these areas and detections at receivers arising from movement. #' @@ -511,8 +511,8 @@ sim_angles <- function(...) { #' #' @param n An integer that defines the number of time steps in the simulation. #' @param r_1 (optional) A matrix with one row and two columns that defines the starting location (x, y). If \code{r_1 = NULL}, then a random location is simulated from a uniform distribution with a minimum and maximum value of 0 and 1 respectively. -#' @param r_h A matrix with one row and two columns that defines the 'home range' centre location (x, y). -#' @param k A number that defines the strength of the 'central harmonic force' that pulls an individual back towards its home range centre. +#' @param r_h A matrix with one row and two columns that defines the `home range' centre location (x, y). +#' @param k A number that defines the strength of the `central harmonic force' that pulls an individual back towards its home range centre. #' @param delta_t A number that defines the number of time units between each time step. #' @param eps A number that defines the variance. #' @param plot A logical variable that defines whether or not to plot the simulated path. @@ -520,7 +520,7 @@ sim_angles <- function(...) { #' @param verbose A logical variable that defines whether or not to print messages to the console that relay function progress. #' @param ... Additional arguments, passed to \code{\link[prettyGraphics]{pretty_map}}, to customise the map. #' -#' @details Ornstein-Uhlenbeck processes are convenient models for animal movement around a 'home range' centre. In the model, a parameter (\code{k}) 'pulls' the location of the individual (\eqn{\vec{r}}) back towards the centre of its home range (\eqn{\vec{r}^H}) as it moves away from this centre. This function implements the discretised form of the Ornstein-Uhlenbeck model in which the parameters of the movement model remain constant through time, and in which movement is not constrained by barriers, described by Alós et al. (2016) (see equations (8) and (9) in particular). Under this model, the position \eqn{\vec{r}} of the animal at time \eqn{n + 1} is given by: +#' @details Ornstein-Uhlenbeck processes are convenient models for animal movement around a `home range' centre. In the model, a parameter (\code{k}) `pulls' the location of the individual (\eqn{\vec{r}}) back towards the centre of its home range (\eqn{\vec{r}^H}) as it moves away from this centre. This function implements the discretised form of the Ornstein-Uhlenbeck model in which the parameters of the movement model remain constant through time, and in which movement is not constrained by barriers, described by Alós et al. (2016) (see equations (8) and (9) in particular). Under this model, the position \eqn{\vec{r}} of the animal at time \eqn{n + 1} is given by: #' #' \deqn{\vec{r}_{n + 1} = \vec{r}^H + e^{-k \Delta t} (\vec{r}_n - \vec{r}^H) + \vec{R}_n,} #' @@ -677,7 +677,7 @@ summarise_along_walk <- function(vec, every, summarise = sum, na.rm = FALSE,...) #' #' @details The function assumes that the individual transmits an acoustic signal which has the capacity to be detected at each time step. In reality, acoustic transmitters are often programmed with a randomly varying delay, but this is not currently implemented. The function also assumes that all receivers that are supplied are able to make detections. If the receivers at which an individual could be detected change over time, it may be necessary to apply the function iteratively or post-process the outcomes to ensure that individuals are not detected at inactive receivers. #' -#' @return If \code{delta_t = NULL}, then function returns a named list with three matrices that define, for each path position (rows) and each receiver (columns), (a) the distance of that position from each receiver ('dist_mat'), (b) the probability of detection at that receiver ('prob_mat') and (c) the simulated outcome (0, no detection; 1, detection) ('det_mat'). If \code{delta_t} is specified, then the function returns a list with a 'raw' and an 'agg' element. The raw elements contains the matrices described above; the 'agg' element contains the aggregated versions of these matrices, with detections summed over each \code{delta_t} interval and distances and probabilities averaged (using the arithmetic mean) over each interval. If \code{plot = TRUE}, the function also returns a plot of the (raw) detections (0, 1) and, if specified, the corresponding probabilities. +#' @return If \code{delta_t = NULL}, then function returns a named list with three matrices that define, for each path position (rows) and each receiver (columns), (a) the distance of that position from each receiver (`dist_mat'), (b) the probability of detection at that receiver (`prob_mat') and (c) the simulated outcome (0, no detection; 1, detection) (`det_mat'). If \code{delta_t} is specified, then the function returns a list with a `raw' and an `agg' element. The raw elements contains the matrices described above; the `agg' element contains the aggregated versions of these matrices, with detections summed over each \code{delta_t} interval and distances and probabilities averaged (using the arithmetic mean) over each interval. If \code{plot = TRUE}, the function also returns a plot of the (raw) detections (0, 1) and, if specified, the corresponding probabilities. #' #' @examples #' #### Step (1) Simulate an array in an area diff --git a/R/spatial_tools.R b/R/spatial_tools.R index e935060..3b6d587 100644 --- a/R/spatial_tools.R +++ b/R/spatial_tools.R @@ -88,7 +88,7 @@ buffer_and_crop <- function(to_buffer, #### invert_poly() #' @title Invert a (spatial) polygon -#' @description This function inverts a (spatial) polygon so that the 'inside' of the original polygon becomes the 'outside' and vice-versa. The function was motivated by marine applications in which polygons that define the coastline 'contain' land and need to be inverted to define the sea. +#' @description This function inverts a (spatial) polygon so that the `inside' of the original polygon becomes the `outside' and vice-versa. The function was motivated by marine applications in which polygons that define the coastline `contain' land and need to be inverted to define the sea. #' #' @param x An \code{\link[sp]{SpatialPolygons-class}} or \code{\link[sp]{SpatialPolygonsDataFrame-class}} object. #' @param boundaries A \code{\link[raster]{extent}} object that defines the boundaries of the area under consideration. By default, this is defined by the extent of \code{x}. @@ -257,7 +257,7 @@ mask_io <- function(x, mask, mask_inside = FALSE,...){ #' lapply(l, function(r) prettyGraphics::pretty_map(add_rasters = list(x = r))) #' graphics::par(pp) #' -#' @source The function taken and slightly modified from the 'greenbrown' package (see https://rdrr.io/rforge/greenbrown/src/R/SplitRasterEqually.R). The function is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +#' @source The function taken and slightly modified from the `greenbrown' package (see https://rdrr.io/rforge/greenbrown/src/R/SplitRasterEqually.R). The function is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. #' @references Forkel M, Wutzler T (2015) greenbrown -- land surface phenology and trend analysis. A package for the R software. Version 2.2, 2015-04-15, http://greenbrown.r-forge.r-project.org/. #' @export diff --git a/R/utils.R b/R/utils.R index e326047..dc6037e 100644 --- a/R/utils.R +++ b/R/utils.R @@ -27,7 +27,7 @@ NULL #' #' @return The function checks arguments supplied via \code{...}; if these contain an argument that is not allowed, the function returns an error. Otherwise, nothing is returned. #' -#' @source This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +#' @source This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. #' @author Edward Lavender #' @keywords internal #' @@ -58,7 +58,7 @@ check... <- function(not_allowed,...){ #' #' @return The function returns \code{input}, an error or a warning and \code{default} depending on whether or not \code{input} is within \code{supp} (i.e., whether or not the input to the argument of a parent function is supported). #' -#' @source This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +#' @source This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. #' @author Edward Lavender #' @keywords internal #' @@ -96,7 +96,7 @@ check_value <- function(arg = deparse(substitute(input)), input, supp, warn = TR #' @param coerce_input A function used to coerce \code{input} to the correct object type, if \code{type = "warning"}. #' @return The function checks the class of the input. If the class is not the same as required by the parent function (i.e., as specified by \code{to_class}), the function returns a helpful error message, or a warning and an object whose class has been coerced to the correct class. #' -#' @source This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +#' @source This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. #' @author Edward Lavender #' @keywords internal #' @@ -149,7 +149,7 @@ check_class <- #' @param type A function which defines the failure criteria. For example, if \code{type = all}, the function will return an error unless all the names in \code{req} are contained within \code{input}. This is the default. If \code{type = any}, the function will return an error only if none of the names in \code{req} are contained within \code{input}. #' @return If the input fails the check, the function returns a helpful error message. Otherwise, nothing is returned. #' -#' @source This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +#' @source This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. #' @author Edward Lavender #' @keywords internal #' @@ -176,7 +176,7 @@ check_names <- function(arg = deparse(substitute(input)), input, req, extract_na #' @param input An object. #' @return An object as inputted in which, if the object is of class Date or POSIXct and a time zone is absent, time zone "UTC" is forced. #' -#' @source This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +#' @source This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. #' @author Edward Lavender #' @keywords internal @@ -204,7 +204,7 @@ check_tz <- #' @param ignore_empty A logical input which defines whether or not to ignore empty lists. #' @return The function returns a helpful error message for unnamed lists (ignoring empty lists if requested) or the inputted list unchanged. #' -#' @source This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +#' @source This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. #' @author Edward Lavender #' @keywords internal @@ -232,7 +232,7 @@ check_named_list <- function(arg = deparse(substitute(input)), input, ignore_emp #' @param check_slash A logical input that defines whether or not to check the end of the directory string for '/'. If \code{TRUE} and a '/' is lacking, this is added to the returned directory. #' @return The function checks whether or not a directory exists. If so, the function returns either the directory as inputted, or the directory with a '/' added to the end. If not, the function returns an informative error message. #' -#' @source This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +#' @source This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. #' @author Edward Lavender #' @keywords internal #' diff --git a/man/acdc-class.Rd b/man/acdc-class.Rd index fe2f32b..10f149f 100644 --- a/man/acdc-class.Rd +++ b/man/acdc-class.Rd @@ -5,15 +5,15 @@ \alias{acdc-class} \title{"acdc" class} \value{ -An \code{\link[flapper]{acdc-class}} object is a named list that contains the output of a call to \code{\link[flapper]{acdc}}. This contains the following elements: ‘.acdc’, ‘ts_by_chunk’, ‘time’ and ‘args’. +An \code{\link[flapper]{acdc-class}} object is a named list that contains the output of a call to \code{\link[flapper]{acdc}}. This contains the following elements: `.acdc', `ts_by_chunk', `time' and `args'. -The main output is the ‘.acdc’ element. This contains a list of arguments returned by the call(s) to the \code{\link[flapper]{.acdc}} function, which is the workhorse that actually implements the algorithm. If the algorithm is implemented step-wise, this contains a single \code{\link[flapper]{.acdc-class}} object as returned by \code{\link[flapper]{.acdc}}. If the algorithm is implemented chunk-wise, this is a list, with one element for each chunk, each element containing a \code{\link[flapper]{.acdc-class}} object with results of the call to \code{\link[flapper]{.acdc}} for that chunk. The results across chunks can be aggregated using \code{\link[flapper]{acdc_simplify}}. +The main output is the `.acdc' element. This contains a list of arguments returned by the call(s) to the \code{\link[flapper]{.acdc}} function, which is the workhorse that actually implements the algorithm. If the algorithm is implemented step-wise, this contains a single \code{\link[flapper]{.acdc-class}} object as returned by \code{\link[flapper]{.acdc}}. If the algorithm is implemented chunk-wise, this is a list, with one element for each chunk, each element containing a \code{\link[flapper]{.acdc-class}} object with results of the call to \code{\link[flapper]{.acdc}} for that chunk. The results across chunks can be aggregated using \code{\link[flapper]{acdc_simplify}}. -The 'ts_by_chunk' element is a list, with one element for each chunk, that contains the acoustic and archival time series that were used in that chunk. If there is more than one chunk, the last observation of each acoustic chunk is the same as the first acoustic observation for the next chunk. This results from splitting chunks at acoustic observations, which enables the results of chunks that are computed independently to be simply aggregated without the loss of any information. +The `ts_by_chunk' element is a list, with one element for each chunk, that contains the acoustic and archival time series that were used in that chunk. If there is more than one chunk, the last observation of each acoustic chunk is the same as the first acoustic observation for the next chunk. This results from splitting chunks at acoustic observations, which enables the results of chunks that are computed independently to be simply aggregated without the loss of any information. -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 `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 records the parameters used to generate the outputs. +The `args' element is a named list of user inputs that records the parameters used to generate the outputs. } \description{ An S3 class that defines the object returned by the \code{\link[flapper]{acdc}} algorithm. diff --git a/man/acdc.Rd b/man/acdc.Rd index 406c4b8..cf88af6 100644 --- a/man/acdc.Rd +++ b/man/acdc.Rd @@ -24,9 +24,9 @@ acdc( ) } \arguments{ -\item{acoustics}{A dataframe, or a list of dataframes, that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a single individual. Each dataframe should contain the following columns: an integer vector of receiver IDs, named 'receiver_id'; a POSIXct vector of time stamps when detections were made, named 'timestamp'; and a numeric vector of those time stamps, named 'timestamp_num'. If a list of dataframes is supplied, dataframes must be refer to the detections of a single individual and be ordered by time (e.g., in hourly chunks). The algorithm will be implemented on each dataframe, termed 'chunk', either in sequence or parallel. Any empty or NULL elements will be removed automatically.} +\item{acoustics}{A dataframe, or a list of dataframes, that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a single individual. Each dataframe should contain the following columns: an integer vector of receiver IDs, named `receiver_id'; a POSIXct vector of time stamps when detections were made, named `timestamp'; and a numeric vector of those time stamps, named `timestamp_num'. If a list of dataframes is supplied, dataframes must be refer to the detections of a single individual and be ordered by time (e.g., in hourly chunks). The algorithm will be implemented on each dataframe, termed `chunk', either in sequence or parallel. Any empty or NULL elements will be removed automatically.} -\item{archival}{A dataframe that contains depth time series (see \code{\link[flapper]{dat_archival}} for an example). This should contain the following columns: a numeric vector of observed depths, named 'depth'; a POSIXct vector of time stamps when observations were made, named 'timestamp'; and a numeric vector of those time stamps, named 'timestamp_num'. Depths should be recorded in the same units and with the same sign as the bathymetry data (see \code{bathy}). Absolute depths (m) are suggested. Unlike the detection time series, archival time stamps are assumed to have occurred at regular intervals. Two-minute intervals are currently assumed.} +\item{archival}{A dataframe that contains depth time series (see \code{\link[flapper]{dat_archival}} for an example). This should contain the following columns: a numeric vector of observed depths, named `depth'; a POSIXct vector of time stamps when observations were made, named `timestamp'; and a numeric vector of those time stamps, named `timestamp_num'. Depths should be recorded in the same units and with the same sign as the bathymetry data (see \code{bathy}). Absolute depths (m) are suggested. Unlike the detection time series, archival time stamps are assumed to have occurred at regular intervals. Two-minute intervals are currently assumed.} \item{bathy}{A \code{\link[raster]{raster}} that defines the bathymetry across the area within which the individual could have moved. This must be recorded in the same units and with the same sign as the depth observations (see \code{archival}). The coordinate reference system should be the Universal Transverse Mercator system, with distances in metres (see also \code{\link[flapper]{acdc_setup_centroids}}).} @@ -71,9 +71,9 @@ The acoustic-centroid depth-contour (ACDC) algorithm is an approach which integr In outline, the crux of the approach is the recognition that acoustic detections typically occur irregularly, while archival observations occur at regular intervals. Each detection anchors our knowledge of the location of an individual around a particular receiver (assuming that all detections are true detections). As time passes between acoustic detections, our uncertainty about the geographical location of an individual expands around the receiver at which it was detected before shrinking towards the receiver at which it was next detected. During this time, regular depth observations restrict the number of possible locations in which the individual could have been located at each time step. -More specifically, when an individual is detected, it must be within some radius – say 800 m – of that receiver. This is the starting acoustic centroid. With a more-refined model of detection probability, it may be possible to predict more precisely where the individual is likely to have been within this centroid (but this approach is not yet implemented). The observed depth at this time further restricts the positions in which the individual could have been, assuming a benthic/demersal lifestyle and a non-homogenous bathymetric landscape. Moving forward in time, a number of depth records may be made before another acoustic detection. During this time, our uncertainty about where the individual could have been gets larger, because it could have moved further away from the receiver, so the acoustic centroids that define this uncertainty expand to a maximum size at the halfway point between acoustic detections. After that, the individual must have started to move towards the receiver at which it was next detected, so these acoustic centroids start to shrink towards that receiver. If the individual was detected by different receivers, the overlap between the centroids of these two receivers at the halfway point defines the set of positions in which the individual could have been at this time. Thereafter, our uncertainty in the individual’s location is given by the overlap between the expansion of this centroid region and the contraction of the centroid around the receiver at which it was next detected. Thus, when the individual is detected again, our uncertainty about where it could have been collapses to the detection radius around the next receiver, possibly weighted by a model of detection probability around this receiver (although that is not yet implemented). The rate of change in centroid size depends a movement parameter that describes an average swimming speed, which will depend on some underlying estimated behavioural state (although that is not yet implemented). +More specifically, when an individual is detected, it must be within some radius – say 800 m – of that receiver. This is the starting acoustic centroid. With a more-refined model of detection probability, it may be possible to predict more precisely where the individual is likely to have been within this centroid (but this approach is not yet implemented). The observed depth at this time further restricts the positions in which the individual could have been, assuming a benthic/demersal lifestyle and a non-homogenous bathymetric landscape. Moving forward in time, a number of depth records may be made before another acoustic detection. During this time, our uncertainty about where the individual could have been gets larger, because it could have moved further away from the receiver, so the acoustic centroids that define this uncertainty expand to a maximum size at the halfway point between acoustic detections. After that, the individual must have started to move towards the receiver at which it was next detected, so these acoustic centroids start to shrink towards that receiver. If the individual was detected by different receivers, the overlap between the centroids of these two receivers at the halfway point defines the set of positions in which the individual could have been at this time. Thereafter, our uncertainty in the individual's location is given by the overlap between the expansion of this centroid region and the contraction of the centroid around the receiver at which it was next detected. Thus, when the individual is detected again, our uncertainty about where it could have been collapses to the detection radius around the next receiver, possibly weighted by a model of detection probability around this receiver (although that is not yet implemented). The rate of change in centroid size depends a movement parameter that describes an average swimming speed, which will depend on some underlying estimated behavioural state (although that is not yet implemented). -The result is a map that shows where the individual could have spent more or less (or no) time over the time interval under construction. The main limitation of this approach is that reconstructs where the individual could have been, but not where it was. In reality, the individual’s current position constrains where it can go next. The ACDCPF/MP algorithms are extensions of this approach that incorporate a movement model for this reason. +The result is a map that shows where the individual could have spent more or less (or no) time over the time interval under construction. The main limitation of this approach is that reconstructs where the individual could have been, but not where it was. In reality, the individual's current position constrains where it can go next. The ACDCPF/MP algorithms are extensions of this approach that incorporate a movement model for this reason. } \examples{ #### Step (1) Implement setup_acdc_*() steps @@ -273,7 +273,7 @@ summary(acdc_out_by_id) } \seealso{ -The 'depth-contour' component of the algorithm can be implemented via \code{\link[flapper]{dc}}. For more information on the ACDC algorithm, see \code{\link[flapper]{acdc_setup_n_centroids}} and \code{\link[flapper]{acdc_setup_centroids}} which defined the acoustic centroids required by this function and \code{\link[flapper]{acdc_setup_mobility}} which examines the assumption of a constant 'mobility' parameter; \code{\link[flapper]{.acdc}}, the back-end workhorse of this function; \code{\link[flapper]{acdc_simplify}} which simplifies the outputs of the \code{\link[flapper]{acdc}} function; and \code{\link[flapper]{acdc_plot}} and \code{\link[flapper]{acdc_animate}}, which visualise the results. +The `depth-contour' component of the algorithm can be implemented via \code{\link[flapper]{dc}}. For more information on the ACDC algorithm, see \code{\link[flapper]{acdc_setup_n_centroids}} and \code{\link[flapper]{acdc_setup_centroids}} which defined the acoustic centroids required by this function and \code{\link[flapper]{acdc_setup_mobility}} which examines the assumption of a constant `mobility' parameter; \code{\link[flapper]{.acdc}}, the back-end workhorse of this function; \code{\link[flapper]{acdc_simplify}} which simplifies the outputs of the \code{\link[flapper]{acdc}} function; and \code{\link[flapper]{acdc_plot}} and \code{\link[flapper]{acdc_animate}}, which visualise the results. } \author{ Edward Lavender diff --git a/man/acdc_animate.Rd b/man/acdc_animate.Rd index 71cc45f..207487d 100644 --- a/man/acdc_animate.Rd +++ b/man/acdc_animate.Rd @@ -22,27 +22,27 @@ acdc_animate( \arguments{ \item{expr_param}{A named list of arguments, passed to \code{\link[flapper]{acdc_plot}}, to create plots.} -\item{html_name}{A string that defines the name of the html file (see 'htmlfile' argument in \code{\link[animation]{saveHTML}}).} +\item{html_name}{A string that defines the name of the html file (see `htmlfile' argument in \code{\link[animation]{saveHTML}}).} -\item{image_name}{A string that defines the names of the individual .png files creates (see 'img.name' argument in \code{\link[animation]{saveHTML}}).} +\item{image_name}{A string that defines the names of the individual .png files creates (see `img.name' argument in \code{\link[animation]{saveHTML}}).} -\item{html_title, html_description}{Character strings that provide a title and a description that are displayed within the html animation (see 'title' and 'description' arguments in \code{\link[animation]{saveHTML}}).} +\item{html_title, html_description}{Character strings that provide a title and a description that are displayed within the html animation (see `title' and `description' arguments in \code{\link[animation]{saveHTML}}).} -\item{navigator}{A logical variable that defines whether or not to add a navigator panel to the animation (see 'navigator' argument in \code{\link[animation]{saveHTML}}).} +\item{navigator}{A logical variable that defines whether or not to add a navigator panel to the animation (see `navigator' argument in \code{\link[animation]{saveHTML}}).} -\item{ani_height, ani_width, ani_res}{Numbers that define the size and the resolution of the animation (see 'ani.height' 'ani.width' and 'ani.res' arguments in \code{\link[animation]{ani.options}}).} +\item{ani_height, ani_width, ani_res}{Numbers that define the size and the resolution of the animation (see `ani.height' `ani.width' and `ani.res' arguments in \code{\link[animation]{ani.options}}).} -\item{interval}{A number that defines the time interval between sequential frames (see 'interval' argument in \code{\link[animation]{ani.options}}).} +\item{interval}{A number that defines the time interval between sequential frames (see `interval' argument in \code{\link[animation]{ani.options}}).} -\item{verbose}{A logical or character variable that defines whether or not, or what, to write as a footer to the html animation (see 'verbose' argument in \code{\link[animation]{ani.options}}).} +\item{verbose}{A logical or character variable that defines whether or not, or what, to write as a footer to the html animation (see `verbose' argument in \code{\link[animation]{ani.options}}).} \item{...}{Additional arguments passed to \code{\link[animation]{ani.options}}.} } \value{ -The function produces an animation in .html format in the working directory (or a sub-directory of this). A folder named 'images' is also produced which contains the images for each time step. The 'css' and 'js' folders are also produced by \code{\link[animation]{saveHTML}} which creates the animation. +The function produces an animation in .html format in the working directory (or a sub-directory of this). A folder named `images' is also produced which contains the images for each time step. The `css' and `js' folders are also produced by \code{\link[animation]{saveHTML}} which creates the animation. } \description{ -This function is a simple wrapper for \code{\link[flapper]{acdc_plot}} and \code{\link[animation]{saveHTML}} which creates an animation of the ACDC algorithm over time. To implement this function, a named list of arguments for \code{\link[flapper]{acdc_plot}}, which creates the plots, must be supplied. This is embedded within \code{\link[animation]{saveHTML}}, which creates a folder in the working directory named 'images' that contains a .png file for each time step and an animation as a .html file. +This function is a simple wrapper for \code{\link[flapper]{acdc_plot}} and \code{\link[animation]{saveHTML}} which creates an animation of the ACDC algorithm over time. To implement this function, a named list of arguments for \code{\link[flapper]{acdc_plot}}, which creates the plots, must be supplied. This is embedded within \code{\link[animation]{saveHTML}}, which creates a folder in the working directory named `images' that contains a .png file for each time step and an animation as a .html file. } \details{ This function requires the \code{\link[animation]{animation}} package. diff --git a/man/acdc_plot.Rd b/man/acdc_plot.Rd index 0156b9d..2b0e21c 100644 --- a/man/acdc_plot.Rd +++ b/man/acdc_plot.Rd @@ -32,9 +32,9 @@ acdc_plot( \item{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{acdc}.} -\item{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).} +\item{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).} -\item{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).} +\item{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).} \item{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{acdc}.} @@ -48,7 +48,7 @@ acdc_plot( \item{par_param}{(optional) A named list of arguments, passed to \code{\link[graphics]{par}}, to control the plotting window. This is executed before plotting is initiated and therefore affects all plots.} -\item{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.} +\item{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.} \item{cl}{A cluster object created by \code{\link[parallel]{makeCluster}}. If supplied, the function loops over specified time steps in parallel to make plots. This is only implemented if plots are saved to file (i.e., \code{png_param} is supplied). If supplied, the connection to the cluster is closed within the function.} diff --git a/man/acdc_setup_mobility.Rd b/man/acdc_setup_mobility.Rd index 869b08f..2184e25 100644 --- a/man/acdc_setup_mobility.Rd +++ b/man/acdc_setup_mobility.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/acdc.R \name{acdc_setup_mobility} \alias{acdc_setup_mobility} -\title{Examine the constant 'mobility' assumption of the ACDC algorithm} +\title{Examine the constant `mobility' assumption of the ACDC algorithm} \usage{ acdc_setup_mobility( depth, @@ -31,7 +31,7 @@ acdc_setup_mobility( The function returns a numeric vector of distances and, if \code{plot = TRUE}, a histogram of those distances. } \description{ -In the simplest and fastest (and only) version of the ACDC algorithm currently implemented by \code{\link[flapper]{flapper}}, the rate at which acoustic centroids expand and contract depends on a single 'mobility' parameter that describes how the uncertainty in an individual's location changes through time according to the passive acoustic telemetry data. These changes essentially reflect the maximum horizontal distance that an individual can move in the time period between archival observations. However, in some situations, a fixed parameter for horizontal movement may not be well supported by archival data, particularly for animals that change dramatically in depth and for which changes in depth are likely to curtail the extent of horizontal movement*. Thus, this function investigates the extent to which the horizontal distance an animal could travel changes through time if the mobility parameter is instead conceptualised as the diagonal distance between sequential depth observations. +In the simplest and fastest (and only) version of the ACDC algorithm currently implemented by \code{\link[flapper]{flapper}}, the rate at which acoustic centroids expand and contract depends on a single `mobility' parameter that describes how the uncertainty in an individual's location changes through time according to the passive acoustic telemetry data. These changes essentially reflect the maximum horizontal distance that an individual can move in the time period between archival observations. However, in some situations, a fixed parameter for horizontal movement may not be well supported by archival data, particularly for animals that change dramatically in depth and for which changes in depth are likely to curtail the extent of horizontal movement*. Thus, this function investigates the extent to which the horizontal distance an animal could travel changes through time if the mobility parameter is instead conceptualised as the diagonal distance between sequential depth observations. } \details{ The function uses a Pythagorean approximation to estimate the \eqn{distance} that an individual could travel in each time step (\eqn{t}), given the maximum horizontal distance that the individual could move (\eqn{mobility}) and sequential changes in \eqn{depth}, according to the equation: diff --git a/man/acdc_setup_n_centroids.Rd b/man/acdc_setup_n_centroids.Rd index 2d7bb15..3b03fbd 100644 --- a/man/acdc_setup_n_centroids.Rd +++ b/man/acdc_setup_n_centroids.Rd @@ -16,7 +16,7 @@ acdc_setup_n_centroids( \arguments{ \item{detections}{A POSIXct vector of time stamps when detections were made (for a particular individual).} -\item{moorings}{A dataframe that defines passive acoustic telemetry receiver locations and deployment periods. This must contain the following columns: 'receiver_id', a unique identifier of each receiver; 'receiver_lat' and 'receiver_long', the latitude and longitude of each receiver in decimal degrees; and 'receiver_start_date' and 'receiver_end_date', the start and end time of each receiver's deployment period (see \code{\link[flapper]{dat_moorings}} for an example).} +\item{moorings}{A dataframe that defines passive acoustic telemetry receiver locations and deployment periods. This must contain the following columns: `receiver_id', a unique identifier of each receiver; `receiver_lat' and `receiver_long', the latitude and longitude of each receiver in decimal degrees; and `receiver_start_date' and `receiver_end_date', the start and end time of each receiver's deployment period (see \code{\link[flapper]{dat_moorings}} for an example).} \item{mobility}{A number that defines the distance (m) that an individual could move in the time period between archival observations (see also \code{\link[flapper]{acdc_setup_centroids}}).} @@ -27,7 +27,7 @@ acdc_setup_n_centroids( \item{...}{Additional arguments passed to \code{\link[prettyGraphics]{pretty_hist}}.} } \value{ -The function returns an integer vector with the upper and lower suggested value for the number of centroids from methods (1) and (2). The parameters used to generate these suggestions (i.e., \code{detections}, \code{moorings}, \code{mobility} and \code{double}) are also included in a 'param' attribute. +The function returns an integer vector with the upper and lower suggested value for the number of centroids from methods (1) and (2). The parameters used to generate these suggestions (i.e., \code{detections}, \code{moorings}, \code{mobility} and \code{double}) are also included in a `param' attribute. } \description{ The ACDC algorithm requires a list of acoustic centroids from \code{\link[flapper]{acdc_setup_centroids}}. The number of centroids that is required depends on (a) the duration between detections; (b) the distances among receivers; (c) the area of interest; and (d) other considerations such as the spatial extent and resolution of the bathymetry data that is required by the ACDC algorithm and presence or absence of a long tail of archival observations after the final acoustic detection. This function implements two approaches to facilitate a sensible choice of the number of centroids for the ACDC algorithm (see Details). This ensures that the number of centroids is sufficient to cover requirements but not so large that the centroids become slow to compute and unwieldy. The function requires a time series of detections, the deployment details of passive acoustic telemetry receivers and a mobility parameter. Given these inputs, the function returns a suggested upper and lower bound for the number of centroids. @@ -49,7 +49,7 @@ utils::str(n_timesteps) } \seealso{ -This function is designed to facilitate an informed choice for the 'n_timesteps' argument in \code{\link[flapper]{acdc_setup_centroids}}. \code{\link[flapper]{acdc_setup_mobility}} can also guide the implementation of this function. This underpins the ACDC algorithm, which is implemented by \code{\link[flapper]{acdc}}. +This function is designed to facilitate an informed choice for the `n_timesteps' argument in \code{\link[flapper]{acdc_setup_centroids}}. \code{\link[flapper]{acdc_setup_mobility}} can also guide the implementation of this function. This underpins the ACDC algorithm, which is implemented by \code{\link[flapper]{acdc}}. } \author{ Edward Lavender diff --git a/man/assemble_sentinel_counts.Rd b/man/assemble_sentinel_counts.Rd index 65eadd2..90dac12 100644 --- a/man/assemble_sentinel_counts.Rd +++ b/man/assemble_sentinel_counts.Rd @@ -15,9 +15,9 @@ assemble_sentinel_counts( ) } \arguments{ -\item{sentinel}{A dataframe that includes all sentinel tag transmissions and detections. This should include the following columns: 'timestamp', the time of each observation; 'type', the type of each observation ("transmission" or "detection"); 'sink_id', a unique identifier of the receivers which received the transmissions; and 'source_id', a unique identifier of the receivers from which the transmission was released (by the built-in sentinel tag). (When the 'source_id' is the same as the 'sink_id', the observation is of type "transmission"; otherwise, the observation must be of type "detection"). See \code{\link[flapper]{dat_sentinel}} for an example.} +\item{sentinel}{A dataframe that includes all sentinel tag transmissions and detections. This should include the following columns: `timestamp', the time of each observation; `type', the type of each observation ("transmission" or "detection"); `sink_id', a unique identifier of the receivers which received the transmissions; and `source_id', a unique identifier of the receivers from which the transmission was released (by the built-in sentinel tag). (When the `source_id' is the same as the `sink_id', the observation is of type "transmission"; otherwise, the observation must be of type "detection"). See \code{\link[flapper]{dat_sentinel}} for an example.} -\item{moorings}{A dataframe that includes receiver identifiers, deployment times and locations. This information is necessary so that, for each time window, only receivers that could have detected transmissions (i.e., were nearby to the transmitter and active at the time of transmission) are included in the processed dataframe. This should include the following columns: 'receiver_id', a unique identifier for each receiver; 'receiver_start_date', the deployment date for each receiver; 'receiver_end_date', the deployment end date for each receiver; 'receiver_long', the receiver longitude (decimal degrees); and 'receiver_lat', the receiver latitude (decimal degrees). See \code{\link[flapper]{dat_moorings}} for an example.} +\item{moorings}{A dataframe that includes receiver identifiers, deployment times and locations. This information is necessary so that, for each time window, only receivers that could have detected transmissions (i.e., were nearby to the transmitter and active at the time of transmission) are included in the processed dataframe. This should include the following columns: `receiver_id', a unique identifier for each receiver; `receiver_start_date', the deployment date for each receiver; `receiver_end_date', the deployment end date for each receiver; `receiver_long', the receiver longitude (decimal degrees); and `receiver_lat', the receiver latitude (decimal degrees). See \code{\link[flapper]{dat_moorings}} for an example.} \item{breaks}{The time interval over which transmissions/detections are counted (e.g. \code{"hours"}). This is passed to the \code{breaks} argument of \code{\link[base]{cut.POSIXt}}.} @@ -25,12 +25,12 @@ assemble_sentinel_counts( \item{detection_range}{A number that defines the maximum distance (m) between a transmitting receiver and other receivers within with detections may plausibly be received. For each transmission, all detections at active receivers within this distance are counted; other receivers are not considered.} -\item{dist_btw_receivers}{(optional) A dataframe that specifies the distances between all combinations of receivers. If not provided, this is computed internally by \code{\link[flapper]{dist_btw_receivers}}, which assumes Euclidean distances are appropriate. If provided, the dataframe should contain columns: 'r1', 'r2', 'dist' (see \code{\link[flapper]{dist_btw_receivers}}). Note that, if provided, the 'dist' column should be in m, not km, as returned by default by \code{\link[flapper]{dist_btw_receivers}}, to match the units of \code{detection_range}.} +\item{dist_btw_receivers}{(optional) A dataframe that specifies the distances between all combinations of receivers. If not provided, this is computed internally by \code{\link[flapper]{dist_btw_receivers}}, which assumes Euclidean distances are appropriate. If provided, the dataframe should contain columns: `r1', `r2', `dist' (see \code{\link[flapper]{dist_btw_receivers}}). Note that, if provided, the `dist' column should be in m, not km, as returned by default by \code{\link[flapper]{dist_btw_receivers}}, to match the units of \code{detection_range}.} \item{...}{Additional arguments (none implemented).} } \value{ -The function returns a dataframe that, for each source receiver (i.e., sentinel tag), specifies the number of transmissions from that receiver and the number of detections at each nearby receiver over the specified time window. The dataframe has the following columns: 'timestamp_bin', the time window; 'source_id', the identifier of the source of transmission; 'sink_id', the identifer of each potential recipient of each transmission; 'n_trms', the number of transmissions from the source over each time window; 'n_dets', the number of detections of each transmission at each potential recipient receiver; 'dist_btw_receivers', the distance between the source and the sink receiver. Rows are ordered by 'source_id', then 'timestamp' and finally 'sink_id'. +The function returns a dataframe that, for each source receiver (i.e., sentinel tag), specifies the number of transmissions from that receiver and the number of detections at each nearby receiver over the specified time window. The dataframe has the following columns: `timestamp_bin', the time window; `source_id', the identifier of the source of transmission; `sink_id', the identifer of each potential recipient of each transmission; `n_trms', the number of transmissions from the source over each time window; `n_dets', the number of detections of each transmission at each potential recipient receiver; `dist_btw_receivers', the distance between the source and the sink receiver. Rows are ordered by `source_id', then `timestamp' and finally `sink_id'. } \description{ This function assembles a dataframe of counts of transmissions/detections from sentinel tags over user-defined time windows. For each sentinel tag, in each time window, the function counts the number of transmissions of that tag (i.e., the expected number of detections at nearby receivers). At the same time, the function determines the number of detections at all nearby receivers (defined as those within a user-specified distance) that were active at the same time as the sentinel tag. The result is a dataframe which comprises, for each tag and each time window, the number of transmissions (i.e., the expected number of detections) and the observed number of detections at each nearby receiver, arranged in long format. diff --git a/man/check....Rd b/man/check....Rd index 12f3c4f..f3f7998 100644 --- a/man/check....Rd +++ b/man/check....Rd @@ -4,7 +4,7 @@ \alias{check...} \title{Check that arguments supplied via \code{...} are allowed} \source{ -This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. } \usage{ check...(not_allowed, ...) diff --git a/man/check_class.Rd b/man/check_class.Rd index 9bbdcd9..c26cffa 100644 --- a/man/check_class.Rd +++ b/man/check_class.Rd @@ -4,7 +4,7 @@ \alias{check_class} \title{Check the class of a function input to a parent function} \source{ -This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. } \usage{ check_class( diff --git a/man/check_dir.Rd b/man/check_dir.Rd index 0c4e22c..a9a3efd 100644 --- a/man/check_dir.Rd +++ b/man/check_dir.Rd @@ -4,7 +4,7 @@ \alias{check_dir} \title{Check a directory exists} \source{ -This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. } \usage{ check_dir(arg = deparse(substitute(input)), input, check_slash = FALSE) diff --git a/man/check_named_list.Rd b/man/check_named_list.Rd index f1bd7c4..234b333 100644 --- a/man/check_named_list.Rd +++ b/man/check_named_list.Rd @@ -4,7 +4,7 @@ \alias{check_named_list} \title{Check that a list is named} \source{ -This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. } \usage{ check_named_list(arg = deparse(substitute(input)), input, ignore_empty = TRUE) diff --git a/man/check_names.Rd b/man/check_names.Rd index 38e6569..e3b2257 100644 --- a/man/check_names.Rd +++ b/man/check_names.Rd @@ -4,7 +4,7 @@ \alias{check_names} \title{Check the names of an object contain required names} \source{ -This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. } \usage{ check_names( diff --git a/man/check_tz.Rd b/man/check_tz.Rd index 19a668e..0c31693 100644 --- a/man/check_tz.Rd +++ b/man/check_tz.Rd @@ -4,7 +4,7 @@ \alias{check_tz} \title{Check the time zone of an object and force UTC if absent} \source{ -This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. } \usage{ check_tz(arg = deparse(substitute(input)), input) diff --git a/man/check_value.Rd b/man/check_value.Rd index db66b27..b412925 100644 --- a/man/check_value.Rd +++ b/man/check_value.Rd @@ -4,7 +4,7 @@ \alias{check_value} \title{Check the input value to a parent function argument} \source{ -This function is taken from the 'utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +This function is taken from the `utils.add' package (https://github.com/edwardlavender/utils.add). It is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. } \usage{ check_value( diff --git a/man/coa.Rd b/man/coa.Rd index 0c12872..07d018d 100644 --- a/man/coa.Rd +++ b/man/coa.Rd @@ -28,7 +28,7 @@ coa( \item{...}{Additional arguments (none implemented).} } \value{ -The function returns a matrix or a dataframe, depending on the \code{output} argument, that represents a time series of COAs. If \code{na_omit = TRUE}, the time series may have 'gaps' over which COAs could not be calculated due to the absence of detections. +The function returns a matrix or a dataframe, depending on the \code{output} argument, that represents a time series of COAs. If \code{na_omit = TRUE}, the time series may have `gaps' over which COAs could not be calculated due to the absence of detections. } \description{ This function implements the arithmetic mean-position algorithm to calculate an individual's centres of activity (COAs) though time from detections at passive acoustic telemetry receivers, as described by Simpfendorfer et al (2002). Under this approach, each COA is calculated as the arithmetic mean of the locations of receivers at which an individual was detected over a specified time interval, weighted by the frequency of detections at each of those receivers. To implement the function, a detection matrix that defines the number of detections of an individual along sequence of time steps at each receiver (e.g., from \code{\link[flapper]{make_matrix_detections}}) needs to be supplied, along a matrix of receiver locations in a planar coordinate system. For each time interval, the function calculates the centre of activity and returns a matrix or dataframe with this information. @@ -94,7 +94,7 @@ coa_mat <- coa(mat = detection_matrix_by_id[[1]], Simpfendorfer, C. A., M. R. Heupel, and R. E. Hueter. 2002. Estimation of short-term centers of activity from an array of omnidirectional hydrophones and its use in studying animal movements. Canadian Journal of Fisheries and Aquatic Sciences 59:23-32. } \seealso{ -\code{\link[flapper]{coa_setup_delta_t}} suggests suitable time intervals over which to calculate COAs. \code{\link[flapper]{make_matrix_detections}} makes the detection matrices from detection time series data required by this function. For data in the VEMCO Vue export format, the 'COA' function in the VTrack package (https://github.com/RossDwyer/VTrack) can also be used to calculate centres of activity. +\code{\link[flapper]{coa_setup_delta_t}} suggests suitable time intervals over which to calculate COAs. \code{\link[flapper]{make_matrix_detections}} makes the detection matrices from detection time series data required by this function. For data in the VEMCO Vue export format, the `COA' function in the VTrack package (https://github.com/RossDwyer/VTrack) can also be used to calculate centres of activity. } \author{ Edward Lavender diff --git a/man/coa_setup_delta_t.Rd b/man/coa_setup_delta_t.Rd index 5f9b649..85538ee 100644 --- a/man/coa_setup_delta_t.Rd +++ b/man/coa_setup_delta_t.Rd @@ -22,15 +22,15 @@ coa_setup_delta_t( ) } \arguments{ -\item{acoustics}{A dataframe with passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a specific individual. This should contain the following columns: a vector of receiver IDs, named 'receiver_id'; and a POSIXct vector of time stamps, named 'timestamp'.} +\item{acoustics}{A dataframe with passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a specific individual. This should contain the following columns: a vector of receiver IDs, named `receiver_id'; and a POSIXct vector of time stamps, named `timestamp'.} -\item{delta_t}{A number or character, passed to the 'breaks' argument of \code{\link[base]{cut.POSIXt}}, that defines the time interval to be evaluated.} +\item{delta_t}{A number or character, passed to the `breaks' argument of \code{\link[base]{cut.POSIXt}}, that defines the time interval to be evaluated.} \item{method}{An integer (\code{1L}, \code{2L} or \code{1:2L}) that defines the method(s) used to evaluate the time intervals (see Description).} \item{implementation}{An integer (\code{1L} or \code{2L}) that defines the metric(s) used in the evaluation: \code{1}, the total number of receivers/detections; or \code{2}, the percent of receivers/number of detections per receiver (see Description). If \code{implementation = 2L} and the total number of receivers is constant through time, the function reverts to \code{implementation = 1L}, the results of which are more interpretable.} -\item{moorings}{(optional) If \code{implementation = 2L}, \code{moorings} is a dataframe that defines, for each receiver, the deployment period. This is required to calculate the number of operational receivers over time (via \code{\link[flapper]{get_n_operational_ts}}). This must contain the following columns: a vector of receiver IDs that includes all receivers in \code{acoustics}, named 'receiver_id'; and the times of receiver deployment and retrieval, named 'receiver_start_date' and 'receiver_end_date' respectively. These are coerced to POSIXct vectors, if required, to match \code{acoustics$timestamp}.} +\item{moorings}{(optional) If \code{implementation = 2L}, \code{moorings} is a dataframe that defines, for each receiver, the deployment period. This is required to calculate the number of operational receivers over time (via \code{\link[flapper]{get_n_operational_ts}}). This must contain the following columns: a vector of receiver IDs that includes all receivers in \code{acoustics}, named `receiver_id'; and the times of receiver deployment and retrieval, named `receiver_start_date' and `receiver_end_date' respectively. These are coerced to POSIXct vectors, if required, to match \code{acoustics$timestamp}.} \item{xlab, ylab, main}{Character strings that define the x and y axis labels and the plot title. If \code{method = 1:2L}, a single input will label both plots identically, whereas a list with one element for each method will label the plots differently.} @@ -43,7 +43,7 @@ coa_setup_delta_t( \item{verbose}{A logical variable that defines whether or not to print messages to the console to relay function progress.} } \value{ -The function returns a named list and a plot for each \code{method}. The list contains a 'data' element that is a named list of dataframes for each method ('m1', 'm2') and implementation ('i1', 'i2'). For 'm1_i1', the dataframe contains the number of receivers with detections ('n_receiver_with_detections') and the percent of the time series for which that number of receivers made detections ('pc_of_ts'). For 'm1_i2', the percentage of receivers with detections ('pc_receiver_with_detections') is given instead. For 'm2_i1', the number of detections ('n_detections') is given; for 'm2_i2', it is the number of detections per receiver ('n_detections_per_receiver'). The list also contains an 'args' element that records the inputs to \code{acoustics} and \code{delta_t} for reference. +The function returns a named list and a plot for each \code{method}. The list contains a `data' element that is a named list of dataframes for each method (`m1', `m2') and implementation (`i1', `i2'). For `m1_i1', the dataframe contains the number of receivers with detections (`n_receiver_with_detections') and the percent of the time series for which that number of receivers made detections (`pc_of_ts'). For `m1_i2', the percentage of receivers with detections (`pc_receiver_with_detections') is given instead. For `m2_i1', the number of detections (`n_detections') is given; for `m2_i2', it is the number of detections per receiver (`n_detections_per_receiver'). The list also contains an `args' element that records the inputs to \code{acoustics} and \code{delta_t} for reference. } \description{ This function implements the two approaches introduced by Simpfendorfer et al. (2002) to suggest suitable time interval(s) over which to estimate centres of activity (COAs). Both approaches rely on prior specification of a candidate time interval (\code{delta_t}) and provide a qualitative assessment of its suitability. The manual iteration of this scheme over multiple intervals provides a measure of their relative suitability. diff --git a/man/dat_moorings.Rd b/man/dat_moorings.Rd index fa03306..3c4034d 100644 --- a/man/dat_moorings.Rd +++ b/man/dat_moorings.Rd @@ -9,7 +9,7 @@ A dataframe with 40 observations and 8 variables: \describe{ \item{receiver_id}{An integer which distinguishes each unique receiver deployment.} \item{receiver}{A character which defines each receiver.} - \item{sentinel_id}{A character which defines each receiver's built-in acoustic transmitter ('sentinel tag'). Some receivers did not have sentinel tags; their \code{sentinel_id} is \code{NA}.} + \item{sentinel_id}{A character which defines each receiver's built-in acoustic transmitter (`sentinel tag'). Some receivers did not have sentinel tags; their \code{sentinel_id} is \code{NA}.} \item{receiver_start_date}{A date which defines the start date of each receiver's deployment.} \item{receiver_end_date}{A date which defines the end date of each receiver's deployment.} \item{receiver_long}{A number which defines the longitude (decimal degrees) of each receiver.} diff --git a/man/dc.Rd b/man/dc.Rd index f7aa4f8..27b565d 100644 --- a/man/dc.Rd +++ b/man/dc.Rd @@ -20,7 +20,7 @@ dc( ) } \arguments{ -\item{archival_ls}{A list of dataframes, with one element for each time unit (e.g., month), which contain depth time series to be related to the local bathymetry. Each dataframe should contain a column of depths ('depth') and a column that defines the time unit ('time_unit'). Depth should be recorded using absolute values in the same units as the bathymetry (see below).} +\item{archival_ls}{A list of dataframes, with one element for each time unit (e.g., month), which contain depth time series to be related to the local bathymetry. Each dataframe should contain a column of depths (`depth') and a column that defines the time unit (`time_unit'). Depth should be recorded using absolute values in the same units as the bathymetry (see below).} \item{bathy}{A \code{\link[raster]{raster}} of the bathymetry in an area within which the animal is likely to have been located over the study. Bathymetry values should be recorded as absolute values and in the same units as for depths (see \code{archival_ls}).} diff --git a/man/dist_btw_receivers.Rd b/man/dist_btw_receivers.Rd index cb50fa7..448d449 100644 --- a/man/dist_btw_receivers.Rd +++ b/man/dist_btw_receivers.Rd @@ -7,12 +7,12 @@ dist_btw_receivers(moorings, f = NULL) } \arguments{ -\item{moorings}{A dataframe which defines each unique receiver deployment. This should contain the columns: 'receiver_id', a unique identifier of each receiver, 'receiver_lat', the latitude of that receiver in decimal degrees; and 'receiver_long', the longitude of that receiver in decimal degrees (see \code{\link[flapper]{dat_moorings}}).} +\item{moorings}{A dataframe which defines each unique receiver deployment. This should contain the columns: `receiver_id', a unique identifier of each receiver, `receiver_lat', the latitude of that receiver in decimal degrees; and `receiver_long', the longitude of that receiver in decimal degrees (see \code{\link[flapper]{dat_moorings}}).} \item{f}{(optional) A function which is used to process distances before these are returned. For example, it may be useful to round distances to nearest km with \code{f = function(x) round(x, digits = 0)}.} } \value{ -The function returns a dataframe with columns 'r1', 'r2' and 'dist'. These define the IDs of each combination of receivers and the associated distance between them, in km. Note that the dataframe contains duplicate combinations of receivers (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). +The function returns a dataframe with columns `r1', `r2' and `dist'. These define the IDs of each combination of receivers and the associated distance between them, in km. Note that the dataframe contains duplicate combinations of receivers (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). } \description{ This function computes Euclidean distances (km) between all combinations of receivers. diff --git a/man/dot-acdc-class.Rd b/man/dot-acdc-class.Rd index e8c811c..d003079 100644 --- a/man/dot-acdc-class.Rd +++ b/man/dot-acdc-class.Rd @@ -5,15 +5,15 @@ \alias{.acdc-class} \title{".acdc" class} \value{ -\subsection{A named list}{An ".acdc" 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{plot} 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{keep_args = TRUE}, otherwise the 'args' element is \code{NULL}). The 'chunks' element is a list with chunk-specific information that is generated if the \code{\link[flapper]{acdc}} 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]{acdc}} and \code{\link[flapper]{acdc_simplify}} or \code{\link[flapper]{.acdc}}. Below, more detail about the ‘map’ and ‘record’ elements is provided.} +\subsection{A named list}{An ".acdc" 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{plot} 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{keep_args = TRUE}, otherwise the `args' element is \code{NULL}). The `chunks' element is a list with chunk-specific information that is generated if the \code{\link[flapper]{acdc}} 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]{acdc}} and \code{\link[flapper]{acdc_simplify}} or \code{\link[flapper]{.acdc}}. 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 acoustic and archival data. Each cell is a count of the number of times when the acoustic and archival data were compatible with the individual having been in that cell, given the ACDC model. 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 acoustic and archival data. Each cell is a count of the number of times when the acoustic and archival data were compatible with the individual having been in that cell, given the ACDC model. 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{(B) ‘record’}{This is a temporal record of the possible locations of each individual, with one element for each acoustic detection. Each element contains (a) a dataframe that defines the details of each pair of detections (the ‘current’ detection and the ‘next’ detection) and all of the archival observations in-between these detections and (b) a named list of spatial objects, one for each archival time step between the pair of acoustic detections, that records the spatial parameters of the algorithm (e.g., the acoustic centroid) at each time step and the possible location(s) of the individual at that time step based on these parameters.} +\subsection{(B) `record'}{This is a temporal record of the possible locations of each individual, with one element for each acoustic detection. Each element contains (a) a dataframe that defines the details of each pair of detections (the `current' detection and the `next' detection) and all of the archival observations in-between these detections and (b) a named list of spatial objects, one for each archival time step between the pair of acoustic detections, that records the spatial parameters of the algorithm (e.g., the acoustic centroid) at each time step and the possible location(s) of the individual at that time step based on these parameters.} -\subsection{(i) record$dat}{‘dat’ contains the following columns: ‘timestep_cumulative’ is a cumulative vector that defines the time step of each observation (across all acoustic and archival time steps up to the current time step); ‘timestep_detection’ defines the time step of the detection time series; ‘timestep_archival’ defines the time step of the archival observations between the current and next acoustic detection; ‘receiver_1_id’ and ‘receiver_2_id’ define the receiver at which the individual was detected at the current and next acoustic time steps; ‘receiver_1_timestamp’ and ‘receiver_2_timestamp’ define the time stamps of these detections; ‘time_btw_dets’ provides the time, in minutes, between these acoustic detections, to the nearest two minutes (the assumed duration between archival records); ‘archival_timestamp’ defines the time stamp of these archival observations; ‘archival_depth’ defines the depth (m) of the individual each archival time step; and ‘centroid_radius’ refers to the size of radius (m) of the acoustic centroid at that time (which depends principally on the time since the last acoustic detection and the time until the next acoustic detection and is a metric of centroid size, bearing-in-mind that the actual centroids can be non-circular).} +\subsection{(i) record$dat}{`dat' contains the following columns: `timestep_cumulative' is a cumulative vector that defines the time step of each observation (across all acoustic and archival time steps up to the current time step); `timestep_detection' defines the time step of the detection time series; `timestep_archival' defines the time step of the archival observations between the current and next acoustic detection; `receiver_1_id' and `receiver_2_id' define the receiver at which the individual was detected at the current and next acoustic time steps; `receiver_1_timestamp' and `receiver_2_timestamp' define the time stamps of these detections; `time_btw_dets' provides the time, in minutes, between these acoustic detections, to the nearest two minutes (the assumed duration between archival records); `archival_timestamp' defines the time stamp of these archival observations; `archival_depth' defines the depth (m) of the individual each archival time step; and `centroid_radius' refers to the size of radius (m) of the acoustic centroid at that time (which depends principally on the time since the last acoustic detection and the time until the next acoustic detection and is a metric of centroid size, bearing-in-mind that the actual centroids can be non-circular).} -\subsection{(ii) record$spatial}{If \code{plot > 0}, then for those time steps specified by \code{plot}, each element in ‘record’ contains a 'spatial' element that is a list, with one element for each archival time stamp between the current and next acoustic detection (defined in ‘record$dat’, see above) that records spatial information pertaining to the possible locations of the individual at that time step. This includes the following elements: ‘centroid’ is a SpatialPolygonsDataFrame that defines the acoustic contour at that time step, which depends on the time since the previous detection, the time until the next detection, the mobility parameter and any spatial masks (i.e., the coastline and specified boundaries); ‘map_timestep’ is a RasterLayer of all the positions that the individual could (cells = 1) or could not (cells = 0) have occupied within that acoustic contour, given its depth and the depth_error, assuming it is on the seabed; and ‘map_cumulative’ is a RasterLayer of the cumulative of the number of times when the acoustic and archival data were compatible with the individual having been in that cell, under the ACDC model, 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). If the receiver at which the individual was detected at the current and next time step differs, after halfway between the archival time steps between these points, the ‘spatial’ list will also contain the following elements: ‘centroid_previous’ is a SpatialPolygonsDataFrame that defines the previous acoustic centroid (i.e., at the ‘current’ receiver); ‘centroid_next’ is a SpatialPolygonsDataFrame that defines the acoustic centroid from the perspective of the ‘next’ receiver at which the individual is detected; 'centroid_overlap' is the overlap between the centroids around the current and next receiver, within which the individual must have been located at the halfway point between detections; and 'centroid_overlap_expanded’ is the expanded version of the centroid overlap that is intersected with the acoustic centroid around the next receiver to determine the individual’s plausible location(s). For \code{plot = 0L} or elements outside of the specified input to \code{plot}, ‘spatial’ is simply an empty list.} +\subsection{(ii) record$spatial}{If \code{plot > 0}, then for those time steps specified by \code{plot}, each element in `record' contains a `spatial' element that is a list, with one element for each archival time stamp between the current and next acoustic detection (defined in `record$dat', see above) that records spatial information pertaining to the possible locations of the individual at that time step. This includes the following elements: `centroid' is a SpatialPolygonsDataFrame that defines the acoustic contour at that time step, which depends on the time since the previous detection, the time until the next detection, the mobility parameter and any spatial masks (i.e., the coastline and specified boundaries); `map_timestep' is a RasterLayer of all the positions that the individual could (cells = 1) or could not (cells = 0) have occupied within that acoustic contour, given its depth and the depth_error, assuming it is on the seabed; and `map_cumulative' is a RasterLayer of the cumulative of the number of times when the acoustic and archival data were compatible with the individual having been in that cell, under the ACDC model, 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). If the receiver at which the individual was detected at the current and next time step differs, after halfway between the archival time steps between these points, the `spatial' list will also contain the following elements: `centroid_previous' is a SpatialPolygonsDataFrame that defines the previous acoustic centroid (i.e., at the `current' receiver); `centroid_next' is a SpatialPolygonsDataFrame that defines the acoustic centroid from the perspective of the `next' receiver at which the individual is detected; `centroid_overlap' is the overlap between the centroids around the current and next receiver, within which the individual must have been located at the halfway point between detections; and `centroid_overlap_expanded' is the expanded version of the centroid overlap that is intersected with the acoustic centroid around the next receiver to determine the individual's plausible location(s). For \code{plot = 0L} or elements outside of the specified input to \code{plot}, `spatial' is simply an empty list.} } \description{ An S3 class that defines the object returned by the \code{\link[flapper]{acdc}} algorithm, after simplification via \code{\link[flapper]{acdc_simplify}}, or directly from the back-end \code{\link[flapper]{.acdc}} function. diff --git a/man/dot-acdc.Rd b/man/dot-acdc.Rd index 3d72581..880b4b9 100644 --- a/man/dot-acdc.Rd +++ b/man/dot-acdc.Rd @@ -24,9 +24,9 @@ ) } \arguments{ -\item{acoustics}{A dataframe that contains passive acoustic telemetry detection time series for a specific individual (see \code{\link[flapper]{dat_acoustics}} for an example). This should contain the following columns: an integer vector of receiver IDs, named 'receiver_id' (that must match that inputted to the \code{rs} argument of \code{\link[flapper]{acdc_setup_centroids}}); a POSIXct vector of time stamps when detections were made, named 'timestamp'; and a numeric vector of those time stamps, named 'timestamp_num'.} +\item{acoustics}{A dataframe that contains passive acoustic telemetry detection time series for a specific individual (see \code{\link[flapper]{dat_acoustics}} for an example). This should contain the following columns: an integer vector of receiver IDs, named `receiver_id' (that must match that inputted to the \code{rs} argument of \code{\link[flapper]{acdc_setup_centroids}}); a POSIXct vector of time stamps when detections were made, named `timestamp'; and a numeric vector of those time stamps, named `timestamp_num'.} -\item{archival}{A dataframe that contains depth time series for the same individual (see \code{\link[flapper]{dat_archival}} for an example). This should contain the following columns: a numeric vector of observed depths, named 'depth'; a POSIXct vector of time stamps when observations were made, named 'timestamp'; and a numeric vector of those time stamps, named 'timestamp_num'. Depths should be recorded in the same units and with the same sign as the bathymetry data (see \code{bathy}). Absolute depths (m) are suggested. Unlike the detection time series, archival time stamps are assumed to have occurred at regular intervals. Two-minute intervals are currently assumed.} +\item{archival}{A dataframe that contains depth time series for the same individual (see \code{\link[flapper]{dat_archival}} for an example). This should contain the following columns: a numeric vector of observed depths, named `depth'; a POSIXct vector of time stamps when observations were made, named `timestamp'; and a numeric vector of those time stamps, named `timestamp_num'. Depths should be recorded in the same units and with the same sign as the bathymetry data (see \code{bathy}). Absolute depths (m) are suggested. Unlike the detection time series, archival time stamps are assumed to have occurred at regular intervals. Two-minute intervals are currently assumed.} \item{bathy}{A \code{\link[raster]{raster}} that defines the bathymetry across the area within which the individual could have moved. This must be recorded in the same units and with the same sign as the depth observations (see \code{archival}). The coordinate reference system should be the Universal Transverse Mercator system, with distances in metres (see also \code{\link[flapper]{acdc_setup_centroids}}).} @@ -57,7 +57,7 @@ \item{...}{Additional arguments (none implemented).} } \value{ -The function returns a \code{\link[flapper]{.acdc-class}} object 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 information on 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 \code{plot}). 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{keep_args = TRUE}, otherwise the 'args' element is \code{NULL}). +The function returns a \code{\link[flapper]{.acdc-class}} object 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 information on 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 \code{plot}). 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{keep_args = TRUE}, otherwise the `args' element is \code{NULL}). } \description{ This function is the back-end of the ACDC algorithm. @@ -133,7 +133,7 @@ out_acdc <- .acdc(acoustics = acc, } \seealso{ -\code{\link[flapper]{acdc_setup_centroids}} defines the acoustic centroids required by this function, aided by \code{\link[flapper]{acdc_setup_centroids}}. \code{\link[flapper]{acdc_setup_mobility}} is used to examine the assumption of the constant 'mobility' parameter. \code{\link[flapper]{acdc}} is the front-end of the algorithm. \code{\link[flapper]{acdc_plot}} and \code{\link[flapper]{acdc_animate}} visualise the results. +\code{\link[flapper]{acdc_setup_centroids}} defines the acoustic centroids required by this function, aided by \code{\link[flapper]{acdc_setup_centroids}}. \code{\link[flapper]{acdc_setup_mobility}} is used to examine the assumption of the constant `mobility' parameter. \code{\link[flapper]{acdc}} is the front-end of the algorithm. \code{\link[flapper]{acdc_plot}} and \code{\link[flapper]{acdc_animate}} visualise the results. } \author{ Edward Lavender diff --git a/man/eval_by_kud.Rd b/man/eval_by_kud.Rd index 4df983c..6dd1c71 100644 --- a/man/eval_by_kud.Rd +++ b/man/eval_by_kud.Rd @@ -40,9 +40,9 @@ eval_by_kud( \item{plot}{An integer vector (\code{1:4L}) that defines which plots to produce. \code{1} and \code{2} plot the receiver array and the simulated or estimated path respectively. In contrast, \code{3} and \code{4} plot the receiver array and the kernel utilisation distribution based on the simulated or estimated path respectively.} -\item{array}{A named list that defines the properties of an array (e.g., the 'array' element of \code{\link[flapper]{sim_array}}). At a minimum, this must contain an 'area' element that defines the area as a \code{\link[sp]{SpatialPolygons-class}} object. To add receivers, land and sea to the plot(s), 'xy', 'land' and 'sea' elements are also required (see \code{\link[flapper]{sim_array}}).} +\item{array}{A named list that defines the properties of an array (e.g., the `array' element of \code{\link[flapper]{sim_array}}). At a minimum, this must contain an `area' element that defines the area as a \code{\link[sp]{SpatialPolygons-class}} object. To add receivers, land and sea to the plot(s), `xy', `land' and `sea' elements are also required (see \code{\link[flapper]{sim_array}}).} -\item{add_land, add_sea, add_receivers, add_path_sim, add_path_est, add_vol_sim, add_vol_est}{(optional) Named lists of arguments that customise the appearance of the land and sea, receivers, the simulated and estimated paths and the kernel volumes for the simulated and estimated paths respectively. An empty list (\code{list()}) will implement default graphical options. If \code{add_receivers}, \code{add_land} and \code{add_sea} are specified, then \code{array} must contain 'xy', 'land' and 'sea' elements as described above. Alternatively, \code{add_receivers}, \code{add_land} and \code{add_sea} can be \code{NULL} to suppress their addition to plots, but the other arguments cannot be \code{NULL}.} +\item{add_land, add_sea, add_receivers, add_path_sim, add_path_est, add_vol_sim, add_vol_est}{(optional) Named lists of arguments that customise the appearance of the land and sea, receivers, the simulated and estimated paths and the kernel volumes for the simulated and estimated paths respectively. An empty list (\code{list()}) will implement default graphical options. If \code{add_receivers}, \code{add_land} and \code{add_sea} are specified, then \code{array} must contain `xy', `land' and `sea' elements as described above. Alternatively, \code{add_receivers}, \code{add_land} and \code{add_sea} can be \code{NULL} to suppress their addition to plots, but the other arguments cannot be \code{NULL}.} \item{one_page}{A logical variable that defines whether or not to produce all plots on a single page.} diff --git a/man/flapper.Rd b/man/flapper.Rd index 9342c0b..ab0f182 100644 --- a/man/flapper.Rd +++ b/man/flapper.Rd @@ -38,8 +38,8 @@ Some functions facilitate spatial operations that support ecological investigati \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{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; - \item \link{invert_poly} inverts a polygon (e.g, to define the ‘sea’ from a polygon of the ‘land’); - \item \link{mask_io} masks values in a raster that lie inside or outside of a spatial mask (e.g., to mask the ‘land’ from the ‘sea’); + \item \link{invert_poly} inverts a polygon (e.g, to define the `sea' from a polygon of the `land'); + \item \link{mask_io} masks values in a raster that lie inside or outside of a spatial mask (e.g., to mask the `land' from the `sea'); \item \link{sim_surface} populates a raster with simulated values; \item \link{split_raster_equally} splits a raster into equal pieces (using code from the greenbrown (http://greenbrown.r-forge.r-project.org) package); \item \link{update_extent} shrinks or inflates an extent object; @@ -89,7 +89,7 @@ The main thrust of flapper is the implementation of existing and new algorithms } \item The acoustic-centroid depth-contour (ACDC) algorithm \itemize{ - \item \link{acdc_setup_mobility} examines the assumption of a constant 'mobility' parameter; + \item \link{acdc_setup_mobility} examines the assumption of a constant `mobility' parameter; \item \link{acdc_setup_n_centroids} suggests the number of acoustic centroids for the algorithm; \item \link{acdc_setup_centroids} defines the acoustic centroids for the algorithm; \item \link{acdc} implements the algorithm, via the back-end function \link{.acdc}; diff --git a/man/get_detection_area_ts.Rd b/man/get_detection_area_ts.Rd index 65cbfb4..fea9ca5 100644 --- a/man/get_detection_area_ts.Rd +++ b/man/get_detection_area_ts.Rd @@ -17,7 +17,7 @@ get_detection_area_ts( ) } \arguments{ -\item{xy, detection_range, coastline, scale}{Arguments required to calculate the total area surveyed by receivers (at each time point) via \code{\link[flapper]{get_detection_area_sum}}. For this function, \code{xy} should be a \code{\link[sp]{SpatialPolygonsDataFrame-class}} object that includes both receiver locations and corresponding deployment times (in columns named 'receiver_start_date' and 'receiver_end_date' respectively).} +\item{xy, detection_range, coastline, scale}{Arguments required to calculate the total area surveyed by receivers (at each time point) via \code{\link[flapper]{get_detection_area_sum}}. For this function, \code{xy} should be a \code{\link[sp]{SpatialPolygonsDataFrame-class}} object that includes both receiver locations and corresponding deployment times (in columns named `receiver_start_date' and `receiver_end_date' respectively).} \item{plot}{A logical input that defines whether or not to plot a time series of the total area sampled by receivers.} @@ -30,7 +30,7 @@ get_detection_area_ts( \item{...}{Additional arguments, passed to \code{\link[prettyGraphics]{pretty_plot}}, to customise the plot produced.} } \value{ -The function returns a dataframe with, for each date ('date') from the time of the first receiver's deployment to the time of the last receiver's retrieval, the number of receivers operational on that date ('n') and the total area sampled ('receiver_area'). If \code{plot = TRUE}, the function also returns a plot of the area sampled by receivers through time. +The function returns a dataframe with, for each date (`date') from the time of the first receiver's deployment to the time of the last receiver's retrieval, the number of receivers operational on that date (`n') and the total area sampled (`receiver_area'). If \code{plot = TRUE}, the function also returns a plot of the area sampled by receivers through time. } \description{ This function extends \code{\link[flapper]{get_detection_area_sum}} to calculate how the total area sampled by receivers changes through time. diff --git a/man/get_detection_centroids.Rd b/man/get_detection_centroids.Rd index 1ca52ed..b8c7854 100644 --- a/man/get_detection_centroids.Rd +++ b/man/get_detection_centroids.Rd @@ -27,7 +27,7 @@ get_detection_centroids( The function returns a \code{\link[sp]{SpatialPolygons-class}} object of the detection centroids around receivers that represents the area they survey under the assumption of a constant detection range, accounting for any barriers to detection. By default, this will contain a single feature, which is suitable for the calculation of the total area surveyed by receivers (see \code{\link[flapper]{get_detection_area_sum}}) because it accounts for the overlap in the detection ranges of receivers. However, if \code{byid = TRUE} is passed via \code{...} to \code{\link[rgeos]{gBuffer}}, the returned object will have a feature for each pair of coordinates in \code{xy} (i.e., receiver). This is less appropriate for calculating the area surveyed by receivers, since areas surveyed by multiple receivers will be over-counted, but it is suitable when the centroids for particular receivers are required (e.g., to extract environmental conditions within a specific receiver's detection range) (see \code{\link[flapper]{get_detection_centroids_envir}}). } \description{ -This function defines the areas surveyed by receivers (termed 'detection centroids') as a spatial object, based on an estimate of the detection range (m) and any barriers to detection. To implement the function, receiver locations must be supplied as a SpatialPoints or SpatialPointsDataFrame object with the Universe Transverse Mercator coordinate reference system. The function defines a spatial buffer around each receiver according to the estimated detection range, cuts out any barriers to detection, such as the coastline, and returns a SpatialPolygons object that defines the combined detection centroid across all receivers or receiver-specific detection centroids. +This function defines the areas surveyed by receivers (termed `detection centroids') as a spatial object, based on an estimate of the detection range (m) and any barriers to detection. To implement the function, receiver locations must be supplied as a SpatialPoints or SpatialPointsDataFrame object with the Universe Transverse Mercator coordinate reference system. The function defines a spatial buffer around each receiver according to the estimated detection range, cuts out any barriers to detection, such as the coastline, and returns a SpatialPolygons object that defines the combined detection centroid across all receivers or receiver-specific detection centroids. } \examples{ #### Define receiver locations as a SpatialPoints object with a UTM CRS diff --git a/man/get_detection_centroids_envir.Rd b/man/get_detection_centroids_envir.Rd index 401d7d5..d027b9b 100644 --- a/man/get_detection_centroids_envir.Rd +++ b/man/get_detection_centroids_envir.Rd @@ -24,9 +24,9 @@ get_detection_centroids_envir( \item{envir}{A \code{\link[raster]{raster}} that defines the values of an environmental variable across the study area. The coordinate reference system should be the Universal Transverse Mercator system.} -\item{sample_size}{(optional) An integer that defines the number of samples of the environmental variable to draw from the area around each receiver (see the 'size' argument of \code{\link[base]{sample}}). If this is provided, \code{sample_size} samples are taken from this area; otherwise, all values are extracted.} +\item{sample_size}{(optional) An integer that defines the number of samples of the environmental variable to draw from the area around each receiver (see the `size' argument of \code{\link[base]{sample}}). If this is provided, \code{sample_size} samples are taken from this area; otherwise, all values are extracted.} -\item{sample_replace}{(optional) If \code{sample_size} is specified, \code{sample_replace} is a logical input that defines whether to implement sampling with (\code{sample_replace = TRUE}, the default) or without (\code{sample_replace = FALSE}) replacement (see the 'replace' argument of \code{\link[base]{sample}}).} +\item{sample_replace}{(optional) If \code{sample_size} is specified, \code{sample_replace} is a logical input that defines whether to implement sampling with (\code{sample_replace = TRUE}, the default) or without (\code{sample_replace = FALSE}) replacement (see the `replace' argument of \code{\link[base]{sample}}).} \item{sample_probs}{(optional) If \code{sample_size} is specified, \code{sample_probs} is a function that calculates the detection probability given the distance (m) between a cell and a receiver.} @@ -37,7 +37,7 @@ get_detection_centroids_envir( \item{verbose}{A logical variable that defines whether or not relay messages to the console to monitor function progress.} } \value{ -The function returns a list of dataframes (one for each element in \code{xy}; i.e., each receiver), each of which includes the cell IDs of \code{envir} from which values were extracted ('cell'), the value of the environmental variable in that cell ('envir') and, if applicable, the distance between that cell and the receiver ('dist', m) and the detection probability in that cell ('prob'). +The function returns a list of dataframes (one for each element in \code{xy}; i.e., each receiver), each of which includes the cell IDs of \code{envir} from which values were extracted (`cell'), the value of the environmental variable in that cell (`envir') and, if applicable, the distance between that cell and the receiver (`dist', m) and the detection probability in that cell (`prob'). } \description{ This function is used to sample environmental conditions from within the detection centroids of receivers. To implement the function, a SpatialPoints object that defines receiver locations (\code{xy}) must be provided, along with the detection range (\code{detection_range}) of receivers. This information is used to define detection centroids, via \code{\link[flapper]{get_detection_centroids}}. Within each receiver's centroid, all values of an environmental variable, or a random sample of values, are extracted from a user-defined \code{\link[raster]{raster}} (\code{envir}). Under random sampling, values can be sampled according to a detection probability function (\code{sample_probs}). The function returns a list of dataframes, one for each receiver, that include the sampled values. diff --git a/man/get_detection_days.Rd b/man/get_detection_days.Rd index 9617ad7..82ba258 100644 --- a/man/get_detection_days.Rd +++ b/man/get_detection_days.Rd @@ -14,7 +14,7 @@ get_detection_days( ) } \arguments{ -\item{acoustics}{A dataframe that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example). This should contain the following columns: a vector of individual IDs, named 'individual_id'; a vector of receiver IDs, named 'receiver_id'; and a POSIXct vector of time stamps when detections were made, named 'timestamp'.} +\item{acoustics}{A dataframe that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example). This should contain the following columns: a vector of individual IDs, named `individual_id'; a vector of receiver IDs, named `receiver_id'; and a POSIXct vector of time stamps when detections were made, named `timestamp'.} \item{individual_id}{(optional) A vector of individuals for which to calculate detection days.} @@ -22,7 +22,7 @@ get_detection_days( \item{type}{If both \code{individual_id} and \code{receiver_id} are specified, then \code{type} is an integer that defines whether or not to calculate detection days for (a) each individual/receiver pair (\code{type = 1L}) or (b) all combinations of individuals/receivers.} -\item{match_to}{(optional) A dataframe against which to match detection days. This must contain the 'individual_id' and 'receiver_id' column, as in \code{acoustics}. If supplied, an integer vector of detection days for individual/receiver combinations, matched against the individuals/receivers in \code{match_to}, is returned (see also Value).} +\item{match_to}{(optional) A dataframe against which to match detection days. This must contain the `individual_id' and `receiver_id' column, as in \code{acoustics}. If supplied, an integer vector of detection days for individual/receiver combinations, matched against the individuals/receivers in \code{match_to}, is returned (see also Value).} \item{...}{Additional arguments passed to \code{\link[pbapply]{pblapply}}.} } @@ -30,7 +30,7 @@ get_detection_days( The function returns a dataframe with the detection days for all, or specified, combinations of individuals and receivers. Note that if \code{acoustics} only contains individuals/receivers that made detections, then this will only contain individuals/receivers for/at which detections were made. Alternatively, if \code{match_to} is supplied, a vector of detection days, matched against each individual/receiver observation in that dataframe, is returned. } \description{ -The function calculates the total number of days (termed 'detection days') during which individuals were detected at passive acoustic telemetry receivers. To implement the function, a dataframe with passive acoustic telemetry detections of individuals at receivers must be supplied. Detection days can be calculated for all combinations of individuals/receivers in this dataframe, for all combinations of specified individuals and receivers, or for specific individual/receiver pairs. The function returns a dataframe of detection days for these individual/receiver combinations or a vector of detection days that is matched against another dataframe. +The function calculates the total number of days (termed `detection days') during which individuals were detected at passive acoustic telemetry receivers. To implement the function, a dataframe with passive acoustic telemetry detections of individuals at receivers must be supplied. Detection days can be calculated for all combinations of individuals/receivers in this dataframe, for all combinations of specified individuals and receivers, or for specific individual/receiver pairs. The function returns a dataframe of detection days for these individual/receiver combinations or a vector of detection days that is matched against another dataframe. } \examples{ #### Example (1): Detection days between all combinations diff --git a/man/get_detection_pr.Rd b/man/get_detection_pr.Rd index 25d701b..0a75e47 100644 --- a/man/get_detection_pr.Rd +++ b/man/get_detection_pr.Rd @@ -25,7 +25,7 @@ get_detection_pr( \item{...}{Additional arguments, passed to \code{\link[prettyGraphics]{pretty_plot}}, to customise the plot. These are only implemented if \code{output = 1L} or \code{output = 3L}.} } \value{ -The function calculates detection probability at each specified distance and returns a plot, a vector of detection probabilities, or both, depending on the value of the \code{output} argument. If a vector of detection probabilities is returned, this contains the following attributes: 'X', the model matrix; 'beta', the regression coefficients; and 'inv_link', the inverse link function. +The function calculates detection probability at each specified distance and returns a plot, a vector of detection probabilities, or both, depending on the value of the \code{output} argument. If a vector of detection probabilities is returned, this contains the following attributes: `X', the model matrix; `beta', the regression coefficients; and `inv_link', the inverse link function. } \description{ This function calculates detection probability (e.g., of an acoustic detection) at specified distances from the sampling device (e.g., a passive acoustic telemetry receiver) using user-defined parameters (i.e., a model intercept, a coefficient for the effect of distance and an inverse link function). The function returns a plot of detection probability with distance and/or a vector of detection probabilities. diff --git a/man/get_id_rec_overlap.Rd b/man/get_id_rec_overlap.Rd index 264cd55..52f79e9 100644 --- a/man/get_id_rec_overlap.Rd +++ b/man/get_id_rec_overlap.Rd @@ -15,9 +15,9 @@ get_id_rec_overlap( ) } \arguments{ -\item{ids}{A dataframe that defines individual deployment periods. This must contain a column that defines individual IDs (named 'individual_id') and the time of tagging (named 'tag_start_date') and time of tag retrieval ('tag_end_date') (see \code{\link[flapper]{dat_ids}} for an example).} +\item{ids}{A dataframe that defines individual deployment periods. This must contain a column that defines individual IDs (named `individual_id') and the time of tagging (named `tag_start_date') and time of tag retrieval (`tag_end_date') (see \code{\link[flapper]{dat_ids}} for an example).} -\item{moorings}{A dataframe that defines receiver deployment periods. This must contain a column that defines receiver IDs (named 'receiver_id') and the time of receiver deployment (named 'receiver_start_date') and retrieval (named 'receiver_end_date') (see \code{\link[flapper]{dat_moorings}} for an example).} +\item{moorings}{A dataframe that defines receiver deployment periods. This must contain a column that defines receiver IDs (named `receiver_id') and the time of receiver deployment (named `receiver_start_date') and retrieval (named `receiver_end_date') (see \code{\link[flapper]{dat_moorings}} for an example).} \item{individual_id}{(optional) A vector of individuals for which to calculate overlap duration.} @@ -25,12 +25,12 @@ get_id_rec_overlap( \item{type}{If both \code{individual_id} and \code{receiver_id} are specified, then \code{type} is an integer that defines whether or not to calculate overlap duration for (a) each individual/receiver pair (\code{type = 1L}) or (b) all combinations of specified individuals/receivers (\code{type = 2L}).} -\item{match_to}{(optional) A dataframe against which to match the calculated overlap duration(s). This must contain an 'individual_id' and 'receiver_id' column, as in \code{ids} and \code{moorings} respectively. If supplied, an integer vector of overlap durations for individual/receiver combinations, matched against the individuals/receivers in this dataframe, is returned (see also Value).} +\item{match_to}{(optional) A dataframe against which to match the calculated overlap duration(s). This must contain an `individual_id' and `receiver_id' column, as in \code{ids} and \code{moorings} respectively. If supplied, an integer vector of overlap durations for individual/receiver combinations, matched against the individuals/receivers in this dataframe, is returned (see also Value).} \item{...}{Additional arguments (none implemented).} } \value{ -The function returns a dataframe with the deployment overlap duration for specific or all combinations of individuals and receivers, with the 'individual_id', 'receiver_id', 'tag_start_date', 'tag_end_date', 'receiver_start_date' and 'receiver_end_date' columns retained, plus 'tag_interval' and 'receiver_interval' columns that define individual and receiver deployment periods as \code{\link[lubridate]{Interval-class}} objects. The 'id_rec_overlap' column defines the temporal overlap (days). Alternatively, if \code{match_to} is supplied, a vector of overlap durations that matches each individual/receiver observation in that dataframe is returned. +The function returns a dataframe with the deployment overlap duration for specific or all combinations of individuals and receivers, with the `individual_id', `receiver_id', `tag_start_date', `tag_end_date', `receiver_start_date' and `receiver_end_date' columns retained, plus `tag_interval' and `receiver_interval' columns that define individual and receiver deployment periods as \code{\link[lubridate]{Interval-class}} objects. The `id_rec_overlap' column defines the temporal overlap (days). Alternatively, if \code{match_to} is supplied, a vector of overlap durations that matches each individual/receiver observation in that dataframe is returned. } \description{ This function calculates the duration of the overlap (in days) between individuals' time at liberty and receivers' operational periods. To implement this function, a dataframe with individual deployment periods and another with receiver deployment periods must be specified. The duration of the overlap between these intervals can be calculated for all combinations of individuals and receivers within these two dataframes, for all combinations of specified individuals and receivers, or for specific individual/receiver pairs. The function returns a dataframe of the overlap duration for these individual/receiver combinations or a vector of values that is matched against another dataframe. diff --git a/man/get_n_operational_ts.Rd b/man/get_n_operational_ts.Rd index 12b3b94..6411cf1 100644 --- a/man/get_n_operational_ts.Rd +++ b/man/get_n_operational_ts.Rd @@ -20,7 +20,7 @@ get_n_operational_ts(data, start, stop, times = NULL, plot = TRUE, ...) \item{...}{Additional arguments, passed to \code{\link[prettyGraphics]{pretty_plot}}, to customise the plot.} } \value{ -The function returns a dataframe that, for each time step ('time'), defines the number of operational units at that time ('n'). If \code{plot = TRUE}, the function also plots a time series of the number of operational units. +The function returns a dataframe that, for each time step (`time'), defines the number of operational units at that time (`n'). If \code{plot = TRUE}, the function also plots a time series of the number of operational units. } \description{ This function calculates the number of operational units through time (e.g., the number of individuals at liberty or the number of active acoustic receivers over the course of a study). To implement the function, a dataframe (\code{data}) must be supplied that defines the start and end time of each unit's operational period. Then, for each time step in a user-specified sequence of times, or an automatically generated sequence of times from the earliest start time to the latest end time in \code{data}, the function counts the number of units that were operational on each time step and returns a dataframe (and, if specified, a plot) with this information. diff --git a/man/invert_poly.Rd b/man/invert_poly.Rd index f88dfa7..a93b679 100644 --- a/man/invert_poly.Rd +++ b/man/invert_poly.Rd @@ -17,7 +17,7 @@ invert_poly(x, boundaries = raster::extent(x), ...) The function returns a \code{\link[sp]{SpatialPolygons-class}} object. } \description{ -This function inverts a (spatial) polygon so that the 'inside' of the original polygon becomes the 'outside' and vice-versa. The function was motivated by marine applications in which polygons that define the coastline 'contain' land and need to be inverted to define the sea. +This function inverts a (spatial) polygon so that the `inside' of the original polygon becomes the `outside' and vice-versa. The function was motivated by marine applications in which polygons that define the coastline `contain' land and need to be inverted to define the sea. } \examples{ #### Example (1): Compare original and inverted polygon diff --git a/man/kud_around_coastline.Rd b/man/kud_around_coastline.Rd index d93af2e..c7b0dc1 100644 --- a/man/kud_around_coastline.Rd +++ b/man/kud_around_coastline.Rd @@ -17,13 +17,13 @@ kud_around_coastline(xy, grid, ...) \item{...}{Additional arguments passed to \code{\link[adehabitatHR]{kernelUD}}.} } \value{ -The function returns an object of class 'estUDm'. This is a list, with one component per animal, of \code{\link[adehabitatHR]{estUD-class}} objects. The 'h' slot of the output (\code{output@h}) has been modified so that the method ('meth') is given as 'specified'. +The function returns an object of class `estUDm'. This is a list, with one component per animal, of \code{\link[adehabitatHR]{estUD-class}} objects. The `h' slot of the output (\code{output@h}) has been modified so that the method (`meth') is given as `specified'. } \description{ -Given an animal movement path over a gridded surface, this function estimates a 'raw' kernel utilisation distribution (from \code{\link[adehabitatHR]{kernelUD}}) and then processes the distribution to account for barriers to movement, such as coastline. To implement the function, the movement path(s) should be supplied as a SpatialPointsDataFrame and the grid over which estimation is implemented as a SpatialPixelsDataFrame with values 0 and 1 defining unsuitable and suitable habitat respectively. +Given an animal movement path over a gridded surface, this function estimates a `raw' kernel utilisation distribution (from \code{\link[adehabitatHR]{kernelUD}}) and then processes the distribution to account for barriers to movement, such as coastline. To implement the function, the movement path(s) should be supplied as a SpatialPointsDataFrame and the grid over which estimation is implemented as a SpatialPixelsDataFrame with values 0 and 1 defining unsuitable and suitable habitat respectively. } \details{ -Utilisation distributions (UDs) are bivariate probability distributions that describe the probability (density) of locating an individual in any given area at a randomly chosen time. These can be estimated using the \code{\link[adehabitatHR]{kernelUD}} function. The algorithms implemented by this function can incorporate simple barriers, but restrictions on the shapes of barriers mean that in many real-world settings (e.g., in areas with complex coastline) barriers cannot be implemented. As a result, a pragmatic (if somewhat unsatisfactory) approach is to post-process the raw utilisation distribution by removing areas in which movement is impossible and then re-normalise the distribution (so that probabilities sum to one). This function achieves this by implementing the estimation over a grid, which defines whether (1) or not (0) an area is 'habitat'. After the estimation of the raw UD across the grid, probability density scores are combined (multipled) with the habitat suitability score (0, 1) and then renormalised (by dividing by the total score across suitable areas). +Utilisation distributions (UDs) are bivariate probability distributions that describe the probability (density) of locating an individual in any given area at a randomly chosen time. These can be estimated using the \code{\link[adehabitatHR]{kernelUD}} function. The algorithms implemented by this function can incorporate simple barriers, but restrictions on the shapes of barriers mean that in many real-world settings (e.g., in areas with complex coastline) barriers cannot be implemented. As a result, a pragmatic (if somewhat unsatisfactory) approach is to post-process the raw utilisation distribution by removing areas in which movement is impossible and then re-normalise the distribution (so that probabilities sum to one). This function achieves this by implementing the estimation over a grid, which defines whether (1) or not (0) an area is `habitat'. After the estimation of the raw UD across the grid, probability density scores are combined (multipled) with the habitat suitability score (0, 1) and then renormalised (by dividing by the total score across suitable areas). } \examples{ #### Set up diff --git a/man/lcp_over_surface.Rd b/man/lcp_over_surface.Rd index ffb96f1..57d8343 100644 --- a/man/lcp_over_surface.Rd +++ b/man/lcp_over_surface.Rd @@ -31,7 +31,7 @@ lcp_over_surface( \item{destination}{A matrix which defines the coordinates (x, y) of the finishing location(s). Coordinates should lie on a plane (i.e., Universal Transverse Mercator projection).} -\item{surface}{A \code{\link[raster]{raster}} over which the object (e.g., individual) must move from \code{origin} to \code{destination}. The \code{surface} must be planar (i.e., Universal Transverse Mercator projection) with units of metres in x, y and z directions (m). The \code{surface}'s \code{\link[raster]{resolution}} is taken to define the distance between horizontally and vertically connected cells and must be the same in both x and y directions (for \code{surface}'s with unequal horizontal resolution, \code{\link[raster]{resample}} can be used to equalise resolution: see Examples). Any cells with NA values (e.g., due to missing data) are treated as 'impossible' to move though by the algorithm. In this case, the \code{surface} might need to be pre-processed so that NAs are replaced/removed before implementing the function, depending on their source.} +\item{surface}{A \code{\link[raster]{raster}} over which the object (e.g., individual) must move from \code{origin} to \code{destination}. The \code{surface} must be planar (i.e., Universal Transverse Mercator projection) with units of metres in x, y and z directions (m). The \code{surface}'s \code{\link[raster]{resolution}} is taken to define the distance between horizontally and vertically connected cells and must be the same in both x and y directions (for \code{surface}'s with unequal horizontal resolution, \code{\link[raster]{resample}} can be used to equalise resolution: see Examples). Any cells with NA values (e.g., due to missing data) are treated as `impossible' to move though by the algorithm. In this case, the \code{surface} might need to be pre-processed so that NAs are replaced/removed before implementing the function, depending on their source.} \item{crop}{(optional) An \code{\link[raster]{extent}} object that is used to \code{\link[raster]{crop}} the extent of the \code{surface}, before the least-cost algorithms are implemented. This may be useful for large rasters to reduce memory requirements/computation time.} @@ -39,7 +39,7 @@ lcp_over_surface( \item{aggregate}{(optional) A named list of arguments, passed to \code{\link[raster]{aggregate}}, to aggregate raster cells before the least-cost algorithms are implemented. This may be useful for large rasters to reduce memory requirements and/or computation time.} -\item{mask}{(optional) A Raster or Spatial \code{\link[raster]{mask}} that is used to prevent movement over 'impossible' areas on the \code{surface}. This must also lie on a planar surface (i.e., Universal Transverse Mercator projection). For example, for marine animals, \code{mask} might be a \code{\link[sp]{SpatialPolygonsDataFrame}} which defines the coastline. The effect of the \code{mask} depends on \code{mask_inside} (see below).} +\item{mask}{(optional) A Raster or Spatial \code{\link[raster]{mask}} that is used to prevent movement over `impossible' areas on the \code{surface}. This must also lie on a planar surface (i.e., Universal Transverse Mercator projection). For example, for marine animals, \code{mask} might be a \code{\link[sp]{SpatialPolygonsDataFrame}} which defines the coastline. The effect of the \code{mask} depends on \code{mask_inside} (see below).} \item{mask_inside}{A logical input that defines whether or not to mask the \code{surface} inside (\code{TRUE}) or outside (\code{FALSE}) of the \code{mask} (see \code{\link[flapper]{mask_io}}).} @@ -62,32 +62,32 @@ lcp_over_surface( \item{...}{Additional arguments (none implemented).} } \value{ -\subsection{A named list}{The function returns a named list. The most important element(s) of this list are 'path_lcp' and/or 'dist_lcp', the shortest path(s) and/or distance(s) (m) between \code{origin} and \code{destination} coordinate pairs/combinations. 'path_lcp' is returned if \code{goal = 2} or \code{goal = 3} and 'dist_lcp' is returned if \code{goal = 1} or \code{goal = 3}. 'path_lcp' contains (a) a dataframe with the cells comprising each path ('cells'), (b) a named list containing a \code{\link[sp]{SpatialLines}} object for each path ('SpatialLines') and (c) a named list of matrices of the coordinates of each path ('coordinates'). 'dist_lcp' is a (a) numeric vector or (b) matrix with the distances (m) between each pair or combination of coordinates respectively. If 'dist_lcp' is computed, 'dist_euclid', the Euclidean distances (m) between the \code{origin} and \code{destination}, is also returned for comparison. +\subsection{A named list}{The function returns a named list. The most important element(s) of this list are `path_lcp' and/or `dist_lcp', the shortest path(s) and/or distance(s) (m) between \code{origin} and \code{destination} coordinate pairs/combinations. `path_lcp' is returned if \code{goal = 2} or \code{goal = 3} and `dist_lcp' is returned if \code{goal = 1} or \code{goal = 3}. `path_lcp' contains (a) a dataframe with the cells comprising each path (`cells'), (b) a named list containing a \code{\link[sp]{SpatialLines}} object for each path (`SpatialLines') and (c) a named list of matrices of the coordinates of each path (`coordinates'). `dist_lcp' is a (a) numeric vector or (b) matrix with the distances (m) between each pair or combination of coordinates respectively. If `dist_lcp' is computed, `dist_euclid', the Euclidean distances (m) between the \code{origin} and \code{destination}, is also returned for comparison. } -\subsection{Common elements}{Other elements of the list record important outputs at sequential stages of the algorithm's progression. These include the following elements: 'args', a named list of user inputs; 'time', a dataframe that defines the times of sequential stages in the algorithm's progression; 'surface', the surface over which shortest distances are computed (this may differ from the inputted surface if any of the processing options, such as \code{crop}, have been implemented); 'surface_param', a named list that defines the cell IDs, the number of rows, the number of columns, the coordinates of the implemented surface and the cell IDs of the \code{origin} and \code{destination} nodes; 'cost', a named list of arguments that defines the distances (m) between connected cells under a rook's or bishop's movement ('dist_rook' and 'dist_bishop'), the planar and vertical distances between connected cells ('dist_planar' and 'dist_vertical') and the total distance between connected cells ('dist_total'); and 'cppRouting_param' or 'gdistance_param', a named list of arguments used to compute shortest paths/distances via \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} (see below). +\subsection{Common elements}{Other elements of the list record important outputs at sequential stages of the algorithm's progression. These include the following elements: `args', a named list of user inputs; `time', a dataframe that defines the times of sequential stages in the algorithm's progression; `surface', the surface over which shortest distances are computed (this may differ from the inputted surface if any of the processing options, such as \code{crop}, have been implemented); `surface_param', a named list that defines the cell IDs, the number of rows, the number of columns, the coordinates of the implemented surface and the cell IDs of the \code{origin} and \code{destination} nodes; `cost', a named list of arguments that defines the distances (m) between connected cells under a rook's or bishop's movement (`dist_rook' and `dist_bishop'), the planar and vertical distances between connected cells (`dist_planar' and `dist_vertical') and the total distance between connected cells (`dist_total'); and `cppRouting_param' or `gdistance_param', a named list of arguments used to compute shortest paths/distances via \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} (see below). } -\subsection{Method-specific elements}{If \code{method = "cppRouting"}, the 'cppRouting_param' list contains a named list of arguments passed to \code{\link[cppRouting]{makegraph}} ('makegraph_param') as well as \code{\link[cppRouting]{get_path_pair}} ('get_path_pair_param') or \code{\link[cppRouting]{get_multi_paths}} ('get_multi_paths_param') and/or \code{\link[cppRouting]{get_distance_pair}} ('get_distance_pair_param') or \code{\link[cppRouting]{get_distance_matrix}} ('get_distance_matrix_param'), depending on whether or not shortest paths and/or distances have been computed (see \code{goal}) and whether or not shortest paths/distances have been computed for each pair of coordinates or all combinations of coordinates. If \code{method = "gdistance"}, this list contains a named list of arguments passed iteratively, for each pair/combination of coordinates, to \code{\link[gdistance]{shortestPath}} ('shortestPath_param') or \code{\link[gdistance]{costDistance}} ('costDistance_param'). This includes an object of class TransitionLayer (see \code{\link[gdistance]{Transition-classes}}), in which the \code{transitionMatrix} slot contains a (sparse) matrix that defines the ease of moving between connected cells (the reciprocal of the 'dist_total' matrix). +\subsection{Method-specific elements}{If \code{method = "cppRouting"}, the `cppRouting_param' list contains a named list of arguments passed to \code{\link[cppRouting]{makegraph}} (`makegraph_param') as well as \code{\link[cppRouting]{get_path_pair}} (`get_path_pair_param') or \code{\link[cppRouting]{get_multi_paths}} (`get_multi_paths_param') and/or \code{\link[cppRouting]{get_distance_pair}} (`get_distance_pair_param') or \code{\link[cppRouting]{get_distance_matrix}} (`get_distance_matrix_param'), depending on whether or not shortest paths and/or distances have been computed (see \code{goal}) and whether or not shortest paths/distances have been computed for each pair of coordinates or all combinations of coordinates. If \code{method = "gdistance"}, this list contains a named list of arguments passed iteratively, for each pair/combination of coordinates, to \code{\link[gdistance]{shortestPath}} (`shortestPath_param') or \code{\link[gdistance]{costDistance}} (`costDistance_param'). This includes an object of class TransitionLayer (see \code{\link[gdistance]{Transition-classes}}), in which the \code{transitionMatrix} slot contains a (sparse) matrix that defines the ease of moving between connected cells (the reciprocal of the `dist_total' matrix). } \subsection{Plot}{If \code{plot = TRUE}, a plot is also produced of the inputted and processed surfaces that are used in the calculations, along with the shortest path(s) (if and once computed). } } \description{ -This function computes the shortest path(s) and/or distance(s) over a \code{surface} between \code{origin} and \code{destination} coordinates. To implement this function, \code{origin} and \code{destination} coordinates need to be specified as matrices and the surface over which movement occurs should be supplied as a \code{\link[raster]{raster}}. Since determining shortest paths can be computationally and memory-intensive, the \code{surface} can be reduced in size and/or resolution before these are computed, by (a) cropping the surface within user-defined extents; (b) focusing on a buffer zone along a Euclidean transect connecting \code{origin} and \code{destination} coordinates; (c) aggregating the surface to reduce the resolution; and/or (d) masking out areas over which movement is impossible (e.g., land for marine animals). Then, the function computes distances between connected cells, given (a) the planar distances between connected cells and (b) their difference in elevation. These distances are taken as a measure of 'cost'. For each pair of \code{origin} and \code{destination} coordinates, or for all combinations of coordinates, these distances are used to compute the least-cost (i.e., shortest) path and/or the distance of this path, using functions in the \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} package. The function returns the shortest path(s) and/or their distance(s) (m) along with a plot and a list of objects involved in the calculations. +This function computes the shortest path(s) and/or distance(s) over a \code{surface} between \code{origin} and \code{destination} coordinates. To implement this function, \code{origin} and \code{destination} coordinates need to be specified as matrices and the surface over which movement occurs should be supplied as a \code{\link[raster]{raster}}. Since determining shortest paths can be computationally and memory-intensive, the \code{surface} can be reduced in size and/or resolution before these are computed, by (a) cropping the surface within user-defined extents; (b) focusing on a buffer zone along a Euclidean transect connecting \code{origin} and \code{destination} coordinates; (c) aggregating the surface to reduce the resolution; and/or (d) masking out areas over which movement is impossible (e.g., land for marine animals). Then, the function computes distances between connected cells, given (a) the planar distances between connected cells and (b) their difference in elevation. These distances are taken as a measure of `cost'. For each pair of \code{origin} and \code{destination} coordinates, or for all combinations of coordinates, these distances are used to compute the least-cost (i.e., shortest) path and/or the distance of this path, using functions in the \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} package. The function returns the shortest path(s) and/or their distance(s) (m) along with a plot and a list of objects involved in the calculations. } \details{ \subsection{Methods}{ This function was motivated by the need to determine the shortest paths and their distances between points for benthic animals, which must move over the seabed to navigate from A to B. For these animals, especially in areas with heterogeneous bathymetric landscapes and/or coastline, the shortest path that an individual must travel to move from A and B may differ substantially from the Euclidean path that is often used as a proxy for distance in biological studies. However, this function can still be used in situations where the surface over which an individual must move is irrelevant (e.g., for a pelagic animal), by supplying a flat surface; then shortest paths/distances simply depend on the planar distances between locations and any barriers (e.g., the coastline). (However, this process will be somewhat inefficient.) -The function conceptualises an object moving across a landscape as a queen on a chessboard which can move, in eight directions around its current position, across this surface. Given the potentially large number of possible paths between an \code{origin} and \code{destination}, the surface may be reduced in extent or size before the game begins. To determine shortest path/distance over the surface between each \code{origin} and \code{destination} pair/combination, the function first considers the distance that an object must travel between pairs of connected cells. This depends on the planar distances between cells and their differences in elevation. Planar distances (\eqn{d_p}, m) depend on the movement type: under a rook's movement (i.e., horizontally or vertically), the distance (\eqn{d_{p,r}}) between connected cells is extracted from the raster's resolution (which is assumed to be identical in the x and y directions); under a bishop's movement (i.e., diagonally), the distance between connected cells \eqn{d_{p,b}} is given by Pythagoras' Theorem: \eqn{d_{p,b} = \sqrt{(d_{p, r}^2 + d_{p, r}^2)}}. Vertical distances (\eqn{d_v}, m) are simply the differences in height between cells. The total distance (\eqn{d_t}) between any two connected cells is a combination of these distances given by Pythagoras' Theorem: \eqn{d_t = \sqrt{(d_p^2 + d_v^2)}}. These distances are taken to define the 'cost' of movement between connected cells. Thus, 'costs' are symmetric (i.e., the cost of moving from A to B equals the cost of moving from B to A). +The function conceptualises an object moving across a landscape as a queen on a chessboard which can move, in eight directions around its current position, across this surface. Given the potentially large number of possible paths between an \code{origin} and \code{destination}, the surface may be reduced in extent or size before the game begins. To determine shortest path/distance over the surface between each \code{origin} and \code{destination} pair/combination, the function first considers the distance that an object must travel between pairs of connected cells. This depends on the planar distances between cells and their differences in elevation. Planar distances (\eqn{d_p}, m) depend on the movement type: under a rook's movement (i.e., horizontally or vertically), the distance (\eqn{d_{p,r}}) between connected cells is extracted from the raster's resolution (which is assumed to be identical in the x and y directions); under a bishop's movement (i.e., diagonally), the distance between connected cells \eqn{d_{p,b}} is given by Pythagoras' Theorem: \eqn{d_{p,b} = \sqrt{(d_{p, r}^2 + d_{p, r}^2)}}. Vertical distances (\eqn{d_v}, m) are simply the differences in height between cells. The total distance (\eqn{d_t}) between any two connected cells is a combination of these distances given by Pythagoras' Theorem: \eqn{d_t = \sqrt{(d_p^2 + d_v^2)}}. These distances are taken to define the `cost' of movement between connected cells. Thus, `costs' are symmetric (i.e., the cost of moving from A to B equals the cost of moving from B to A). This cost surface is then used to compute the shortest path and/or distance of the shortest path between each \code{origin} and \code{destination} pair/combination using functions in the \code{\link[cppRouting]{cppRouting}} or \code{\link[gdistance]{gdistance}} package. The functions implemented depend on the \code{goal} (i.e., whether the aim is to compute shortest paths, shortest distances or both) and, if there is more than one \code{origin}/\code{destination}, the \code{combination} type (i.e., whether to compute shortest paths/distances for each sequential pair of coordinates or all possible combinations of coordinates). } \subsection{Warnings}{ -The function returns a warning produced by \code{\link[gdistance]{transition}} which is implemented to facilitate the definition of the cost surface, before shortest paths/distances are computed by either method: 'In .TfromR(x, transitionFunction, directions, symm) : transition function gives negative values'. This warning arises because the height differences between connecting cells can be negative. It can be safely ignored. +The function returns a warning produced by \code{\link[gdistance]{transition}} which is implemented to facilitate the definition of the cost surface, before shortest paths/distances are computed by either method: `In .TfromR(x, transitionFunction, directions, symm) : transition function gives negative values'. This warning arises because the height differences between connecting cells can be negative. It can be safely ignored. } } \examples{ diff --git a/man/make_df_detections.Rd b/man/make_df_detections.Rd index e4e8800..66f2123 100644 --- a/man/make_df_detections.Rd +++ b/man/make_df_detections.Rd @@ -12,7 +12,7 @@ make_df_detections( ) } \arguments{ -\item{acoustics}{A detection matrix (time stamps x receivers) in which the cells define whether (1) or not (0) a detection was made at each time stamp/receiver combination. 'Meaningful' time stamps and receiver IDs can be taken from the row and column names of this matrix, if specified (see \code{set_names}).} +\item{acoustics}{A detection matrix (time stamps x receivers) in which the cells define whether (1) or not (0) a detection was made at each time stamp/receiver combination. `Meaningful' time stamps and receiver IDs can be taken from the row and column names of this matrix, if specified (see \code{set_names}).} \item{only_keep_detections}{A logical variable that defines whether or not to retain only observations that correspond to detections. (If \code{only_keep_detections = FALSE}, the returned dataframe includes time stamps without detections.)} @@ -21,7 +21,7 @@ make_df_detections( \item{as_POSIXct}{If \code{set_names = TRUE}, \code{as_POSIXct} is a function that converts the row names of \code{acoustics} into POSIXct time stamps.} } \value{ -The function returns a dataframe with time stamps ('timestamp') and receivers ('receiver_id'). If \code{set_names = FALSE}, these are integer vectors that match the dimensions of \code{acoustics}. Otherwise they are are taken from row and column names of \code{acoustics}. In this case, if \code{as_POSIXct} is defined, time stamps are returned in POSIXct format and receivers are returned as a factor. If \code{only_keep_detections = FALSE}, the dataframe also includes a 'detection' column that defines whether (1) or not (0) a detection was made for each observation; otherwise, this column is dropped (mirroring real-world data). +The function returns a dataframe with time stamps (`timestamp') and receivers (`receiver_id'). If \code{set_names = FALSE}, these are integer vectors that match the dimensions of \code{acoustics}. Otherwise they are are taken from row and column names of \code{acoustics}. In this case, if \code{as_POSIXct} is defined, time stamps are returned in POSIXct format and receivers are returned as a factor. If \code{only_keep_detections = FALSE}, the dataframe also includes a `detection' column that defines whether (1) or not (0) a detection was made for each observation; otherwise, this column is dropped (mirroring real-world data). } \description{ This function converts a matrix of detections (0, 1) by time stamp and receiver into a dataframe. diff --git a/man/make_matrix_cooccurence.Rd b/man/make_matrix_cooccurence.Rd index cf6534c..bf909f0 100644 --- a/man/make_matrix_cooccurence.Rd +++ b/man/make_matrix_cooccurence.Rd @@ -15,7 +15,7 @@ make_matrix_cooccurence( ) } \arguments{ -\item{acoustics_ls}{A list of dataframes, with one element for each individual, which contains each individual's detection time series. Each dataframe must include the following columns: 'individual_id', a factor which specifies unique individuals; 'timestamp', a POSIXct object which specifies the time of each detection; 'receiver_long', the longitude (decimal degrees) of the receiver(s) at the individual was detected; and 'receiver_lat', the latitude (decimal degrees) of the receiver(s) at which individual was detected. Each dataframe should be ordered by 'individual_id' and then by 'timestamp'. Careful ordering of 'individual_id' factor levels (e.g. perhaps by population group, then by the number of detections of each individual) can aid visualisation of similarity matrices, in which the order or rows/columns corresponds directly to the order of individuals in \code{acoustics_ls}. Sequential elements in \code{acoustics_ls} should correspond to sequential factor levels for 'individual_id', which should be the same across all dataframes.} +\item{acoustics_ls}{A list of dataframes, with one element for each individual, which contains each individual's detection time series. Each dataframe must include the following columns: `individual_id', a factor which specifies unique individuals; `timestamp', a POSIXct object which specifies the time of each detection; `receiver_long', the longitude (decimal degrees) of the receiver(s) at the individual was detected; and `receiver_lat', the latitude (decimal degrees) of the receiver(s) at which individual was detected. Each dataframe should be ordered by `individual_id' and then by `timestamp'. Careful ordering of `individual_id' factor levels (e.g. perhaps by population group, then by the number of detections of each individual) can aid visualisation of similarity matrices, in which the order or rows/columns corresponds directly to the order of individuals in \code{acoustics_ls}. Sequential elements in \code{acoustics_ls} should correspond to sequential factor levels for `individual_id', which should be the same across all dataframes.} \item{thresh_time}{A number which specifies the time, in minutes, after which detections at nearby receivers are excluded.} @@ -25,7 +25,7 @@ make_matrix_cooccurence( \item{varlist}{(optional) A character vector of names of objects to export, to be passed to the \code{varlist} argument of \code{\link[parallel]{clusterExport}}. This may be required if \code{cl} is supplied. Exported objects must be located in the global environment.} -\item{output}{A number which specifies the output type. If \code{output = 1}, the function returns a (usually) symmetric similarity matrix in which each number represents the number of detections nearby in space and time for each pair of individuals. Row and column names are assigned from the 'individual_id' column in \code{acoustics_ls} dataframes. This matrix is usually symmetric, but this is not necessarily the case for data collected from tags which transmit at random intervals around a nominal delay: under this scenario, the tag for a given individual (i) may transmit multiple signals in the space of time that the tag for another individual (j) only releases a single transmission. In this case, the pairing i,j will comprise all unique transmissions for individual i, paired with the nearest observations for individual j, some of which will be duplicate observations. Therefore, this pairing will contain more 'shared observations' than the pairing j,i. However, even under random transmission, the matrix will usually be either symmetric or very nearly symmetric, with only small differences between identical pairs. If \code{output = 2}, the function returns a list with the following elements: (1) 'mat_sim', the symmetric similarity matrix (see above); 'mat_nobs', a matrix with the same dimensions as 'mat_sim' which specifies the number of observations for each individual (by row, used to calculate 'mat_pc', see later); 'mat_pc', a non-symmetric matrix in which each cell represents the percent of observations of the individual in the i'th row that are shared with the individual in the j'th column; and 'dat', a nested list, with one element for each individual which comprises a list of dataframes, one for each other individual, each one of which contains the subset of observations that are shared between the two individuals. Each dataframe contains the same columns as in the \code{acoustics_ls} dataframes with the following columns added: 'pos_in_acc2', 'timestamp_acc2', 'receiver_lat_acc2' and 'receiver_long_acc2', which represent the positions, time stamps and locations of corresponding observations in the second individual's dataframe to the first individual's dataframe, and 'difftime_abs' and 'dist_btw_receivers' which represent the duration (minutes) and distances (m) between corresponding observations. When there are no shared observations between a pair of individuals, the element simply contains \code{NULL}. Note that 'mat_pc' is computed by (mat_sim/mat_nobs)*100. The matrix is therefore non-symmetric (if individuals have differing numbers of observations); i.e., mat_pc[i, j] is the percent of individual i's observations that are shared with individual j; while mat_pc[j, i] is the percent of individual j's observations that are shared with individual i. NaN elements are possible in 'mat_pc' for levels of the factor 'individual_id' without observations.} +\item{output}{A number which specifies the output type. If \code{output = 1}, the function returns a (usually) symmetric similarity matrix in which each number represents the number of detections nearby in space and time for each pair of individuals. Row and column names are assigned from the `individual_id' column in \code{acoustics_ls} dataframes. This matrix is usually symmetric, but this is not necessarily the case for data collected from tags which transmit at random intervals around a nominal delay: under this scenario, the tag for a given individual (i) may transmit multiple signals in the space of time that the tag for another individual (j) only releases a single transmission. In this case, the pairing i,j will comprise all unique transmissions for individual i, paired with the nearest observations for individual j, some of which will be duplicate observations. Therefore, this pairing will contain more `shared observations' than the pairing j,i. However, even under random transmission, the matrix will usually be either symmetric or very nearly symmetric, with only small differences between identical pairs. If \code{output = 2}, the function returns a list with the following elements: (1) `mat_sim', the symmetric similarity matrix (see above); `mat_nobs', a matrix with the same dimensions as `mat_sim' which specifies the number of observations for each individual (by row, used to calculate `mat_pc', see later); `mat_pc', a non-symmetric matrix in which each cell represents the percent of observations of the individual in the i'th row that are shared with the individual in the j'th column; and `dat', a nested list, with one element for each individual which comprises a list of dataframes, one for each other individual, each one of which contains the subset of observations that are shared between the two individuals. Each dataframe contains the same columns as in the \code{acoustics_ls} dataframes with the following columns added: `pos_in_acc2', `timestamp_acc2', `receiver_lat_acc2' and `receiver_long_acc2', which represent the positions, time stamps and locations of corresponding observations in the second individual's dataframe to the first individual's dataframe, and `difftime_abs' and `dist_btw_receivers' which represent the duration (minutes) and distances (m) between corresponding observations. When there are no shared observations between a pair of individuals, the element simply contains \code{NULL}. Note that `mat_pc' is computed by (mat_sim/mat_nobs)*100. The matrix is therefore non-symmetric (if individuals have differing numbers of observations); i.e., mat_pc[i, j] is the percent of individual i's observations that are shared with individual j; while mat_pc[j, i] is the percent of individual j's observations that are shared with individual i. NaN elements are possible in `mat_pc' for levels of the factor `individual_id' without observations.} \item{verbose}{A logical input which specifies whether or not to print messages to the console which relay function progress. This is ignored if \code{cl} is supplied.} } @@ -33,7 +33,7 @@ make_matrix_cooccurence( The function returns a matrix or a list, depending on the input to \code{output} (see above). } \description{ -The function computes a detection history similarity matrix. For all combinations of individuals, this shows the total number (or percentage) of detections 'nearby' in space and time, which can help to elucidate possible interactions among individuals that affect space use (see Details). To compute this matrix, the function pairs detections for each individual with the detections nearest in time for each other individual. The function computes the time (minutes) between paired detection time series, and the distance (m) between the receiver(s) at which paired detections occurred, dropping any detection pairs that are further apart in time or space than user-defined thresholds (which depend on the mobility of the species under investigation). For each combination of individuals, the function returns total number (or percentage) of detections that are closely associated in time and space. For very large combinations of individuals, especially those with long, overlapping time series, the function may take some time to run; therefore, testing the function on a small subset of individuals first is advisable. Parallelisation can be used to improve computation time. Similarity matrices can be visualised with \code{\link[prettyGraphics]{pretty_mat}}. +The function computes a detection history similarity matrix. For all combinations of individuals, this shows the total number (or percentage) of detections `nearby' in space and time, which can help to elucidate possible interactions among individuals that affect space use (see Details). To compute this matrix, the function pairs detections for each individual with the detections nearest in time for each other individual. The function computes the time (minutes) between paired detection time series, and the distance (m) between the receiver(s) at which paired detections occurred, dropping any detection pairs that are further apart in time or space than user-defined thresholds (which depend on the mobility of the species under investigation). For each combination of individuals, the function returns total number (or percentage) of detections that are closely associated in time and space. For very large combinations of individuals, especially those with long, overlapping time series, the function may take some time to run; therefore, testing the function on a small subset of individuals first is advisable. Parallelisation can be used to improve computation time. Similarity matrices can be visualised with \code{\link[prettyGraphics]{pretty_mat}}. } \details{ \subsection{Background}{ diff --git a/man/make_matrix_detections.Rd b/man/make_matrix_detections.Rd index 74fcff2..32a3b4d 100644 --- a/man/make_matrix_detections.Rd +++ b/man/make_matrix_detections.Rd @@ -19,13 +19,13 @@ make_matrix_detections( ) } \arguments{ -\item{acoustics}{A dataframe that defines passive acoustic telemetry detection time series. This should contain the following columns: a vector of individual IDs, named 'individual_id'; a (factor) vector of receiver IDs, named 'receiver_id'. If \code{set_outside} is specified, this should also contain POSIXct vectors of the start and end time of each individual's time at liberty, named 'tag_start_date' and 'tag_end_date' respectively.} +\item{acoustics}{A dataframe that defines passive acoustic telemetry detection time series. This should contain the following columns: a vector of individual IDs, named `individual_id'; a (factor) vector of receiver IDs, named `receiver_id'. If \code{set_outside} is specified, this should also contain POSIXct vectors of the start and end time of each individual's time at liberty, named `tag_start_date' and `tag_end_date' respectively.} -\item{moorings}{(optional) If \code{set_outside} is specified, \code{moorings} is dataframe that defines passive acoustic telemetry receiver metadata. This should contain the following columns: a vector of receiver IDs, named 'receiver_id (as in \code{acoustics}); and POSIXct vectors of the start and end times of each receiver's deployment time, named 'receiver_start_date' and 'receiver_end_date' respectively.} +\item{moorings}{(optional) If \code{set_outside} is specified, \code{moorings} is dataframe that defines passive acoustic telemetry receiver metadata. This should contain the following columns: a vector of receiver IDs, named `receiver_id (as in \code{acoustics}); and POSIXct vectors of the start and end times of each receiver's deployment time, named `receiver_start_date' and `receiver_end_date' respectively.} \item{start, end}{POSIXct objects that define the start and end time. If unspecified, these are taken from the range of detection times in \code{acoustics}.} -\item{delta_t}{A number or character that defines the time interval between successive time steps. This is passed to the 'by' argument of \code{\link[base]{seq.POSIXt}}.} +\item{delta_t}{A number or character that defines the time interval between successive time steps. This is passed to the `by' argument of \code{\link[base]{seq.POSIXt}}.} \item{simplify}{(optional) A function that simplifies detection matrices, such as \code{function(x) (x > 0) + 0} to convert counts into a boolean outcomes that define whether or a detection was made.} @@ -43,7 +43,7 @@ make_matrix_detections( A matrix, or a list of matrices (one for each individual in \code{acoustics} if there is more than one individual) with one column for each time step and one column for each receiver. Each cell defines whether (1) or not (0) the individual was detected (or, if \code{set_outside} is supplied, it could not have been detected) during that time step. All matrices are expressed across the same sequence of time steps and receivers. } \description{ -This function creates a list of matrices that, for each individual (list element), defines the number of detections of that individual in each time interval (matrix row) at each receiver (matrix column). To implement the function, a dataframe with acoustic detection time series must be provided via \code{acoustics}. The time intervals over which to count detections are provided by optionally defining a \code{start} and \code{end} date (these can be taken from the range of times in \code{acoustics} if unspecified) and the interval (\code{delta_t}) between time steps. By default, matrix elements that are 'outside' individual or receiver deployment periods are defined as 0 (not detected) but can be changed to another value (e.g., NA) via \code{set_outside}. In this case, the \code{acoustics} dataframe also needs to include the deployment times for each individual and an additional dataframe must be supplied with the same information for receivers via \code{moorings}. +This function creates a list of matrices that, for each individual (list element), defines the number of detections of that individual in each time interval (matrix row) at each receiver (matrix column). To implement the function, a dataframe with acoustic detection time series must be provided via \code{acoustics}. The time intervals over which to count detections are provided by optionally defining a \code{start} and \code{end} date (these can be taken from the range of times in \code{acoustics} if unspecified) and the interval (\code{delta_t}) between time steps. By default, matrix elements that are `outside' individual or receiver deployment periods are defined as 0 (not detected) but can be changed to another value (e.g., NA) via \code{set_outside}. In this case, the \code{acoustics} dataframe also needs to include the deployment times for each individual and an additional dataframe must be supplied with the same information for receivers via \code{moorings}. } \examples{ #### Example (1) Construct matrix from detected individuals using detection time series diff --git a/man/make_matrix_ids.Rd b/man/make_matrix_ids.Rd index 1d4f7d5..b7eb0bb 100644 --- a/man/make_matrix_ids.Rd +++ b/man/make_matrix_ids.Rd @@ -15,11 +15,11 @@ make_matrix_ids( ) } \arguments{ -\item{ids}{A dataframe that defines individual IDs and deployment times. This must contain the following columns: an identifier for individuals (named 'individual_id'), the start time of individuals' deployment periods ('tag_start_date') and the end time of individuals' deployment periods ('tag_end_date'). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see \code{as_POSIXct}).} +\item{ids}{A dataframe that defines individual IDs and deployment times. This must contain the following columns: an identifier for individuals (named `individual_id'), the start time of individuals' deployment periods (`tag_start_date') and the end time of individuals' deployment periods (`tag_end_date'). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see \code{as_POSIXct}).} \item{start, end}{Date or POSIXct objects that define the start and end time. If unspecified, these are taken from the range of deployment times in \code{ids}.} -\item{delta_t}{A number or character that defines the time interval between successive time steps. This is passed to the 'by' argument of \code{\link[base]{seq.POSIXt}}.} +\item{delta_t}{A number or character that defines the time interval between successive time steps. This is passed to the `by' argument of \code{\link[base]{seq.POSIXt}}.} \item{as_POSIXct}{A function that coerces any supplied times (\code{ids$tag_start_date}, \code{ids$tag_end_date}, \code{start} and \code{end}) that are not POSIXct objects to POSIXct objects.} diff --git a/man/make_matrix_receivers.Rd b/man/make_matrix_receivers.Rd index eff10e7..67c8141 100644 --- a/man/make_matrix_receivers.Rd +++ b/man/make_matrix_receivers.Rd @@ -15,11 +15,11 @@ make_matrix_receivers( ) } \arguments{ -\item{moorings}{A dataframe that defines receiver IDs and deployment times. This must contain the following columns: an identifier for receivers (named 'receiver_id'), the start time of receiver' deployment periods ('receiver_start_date') and the end time of receivers' deployment periods ('receiver_end_date') (see \code{\link[flapper]{dat_moorings}} for an example). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see \code{as_POSIXct}).} +\item{moorings}{A dataframe that defines receiver IDs and deployment times. This must contain the following columns: an identifier for receivers (named `receiver_id'), the start time of receiver' deployment periods (`receiver_start_date') and the end time of receivers' deployment periods (`receiver_end_date') (see \code{\link[flapper]{dat_moorings}} for an example). Deployment times can be recorded as Date or POSIXct objects but, if the former is provided, they need to be coerced to POSIXct objects. This can be done automatically (see \code{as_POSIXct}).} \item{start, end}{Date or POSIXct objects that define the start and end time. If unspecified, these are taken from the range of deployment times in \code{moorings}.} -\item{delta_t}{A number or character that defines the time interval between successive time steps. This is passed to the 'by' argument of \code{\link[base]{seq.POSIXt}}.} +\item{delta_t}{A number or character that defines the time interval between successive time steps. This is passed to the `by' argument of \code{\link[base]{seq.POSIXt}}.} \item{as_POSIXct}{A function that coerces supplied any supplied times (\code{moorings$receiver_start_date}, \code{moorings$receiver_end_date}, \code{start} and \code{end}) that are not POSIXct objects to POSIXct objects.} diff --git a/man/process_false_detections_sf.Rd b/man/process_false_detections_sf.Rd index 7af91ec..464a85f 100644 --- a/man/process_false_detections_sf.Rd +++ b/man/process_false_detections_sf.Rd @@ -7,16 +7,16 @@ process_false_detections_sf(det, tf, sf, dist_btw_receivers) } \arguments{ -\item{det}{A dataframe containing detection time series. Following \code{\link[glatos]{false_detections}}, this should contain the following columns: 'detection_timestamp_utc', 'transmitter_codespace', 'transmitter_id' and 'receiver_sn', as well as 'passed_filter' (see \code{\link[glatos]{false_detections}}).} +\item{det}{A dataframe containing detection time series. Following \code{\link[glatos]{false_detections}}, this should contain the following columns: `detection_timestamp_utc', `transmitter_codespace', `transmitter_id' and `receiver_sn', as well as `passed_filter' (see \code{\link[glatos]{false_detections}}).} \item{tf}{A number that defines the time threshold (s) used to flag false detections (see \code{\link[glatos]{false_detections}}).} \item{sf}{A number that defines the threshold Euclidean distance between receivers beyond which, even if a false detection is accompanied by detections at other receivers, it is likely to be a true false detection, because the individual could not have moved between receivers separated by more than this threshold over the specified time interval. \code{sf} should be defined in the same units as the distances provided in \code{dist_btw_receivers} (see below).} -\item{dist_btw_receivers}{A dataframe that defines the distances between receiver pairs. This should contain the columns: 'r1', 'r2' and 'dist', whereby 'r1' and 'r2' contain the unique receiver serial number for all combinations of receivers and 'dist' contains the distance between them. This dataframe should include duplicate combinations (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). This can be created with \code{\link[flapper]{dist_btw_receivers}}.} +\item{dist_btw_receivers}{A dataframe that defines the distances between receiver pairs. This should contain the columns: `r1', `r2' and `dist', whereby `r1' and `r2' contain the unique receiver serial number for all combinations of receivers and `dist' contains the distance between them. This dataframe should include duplicate combinations (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). This can be created with \code{\link[flapper]{dist_btw_receivers}}.} } \value{ -The function returns a vector, of the same length as \code{det} with three possible values: NA, which identifies detections which have not been flagged as false detections (i.e., \code{passed_filter = 0}, see \code{\link[glatos]{false_detections}}) and are therefore not passed through the spatial filter; 1, which identifies detections which 'passed' the spatial filter (i.e., false detections which are accompanied by detections at nearby receivers within the defined spatial and temporal thresholds); or 0, which defines detections which 'failed' the spatial filter (i.e., false detections which are not accompanied by detections at nearby receivers within the defined spatial and temporal thresholds). This vector has one attribute, 'details', a dataframe with the same number of rows as \code{det} with the following columns: 'passed_filter_sf', 'n_wn_sf', 'detection_timestamp_utc_sf' and 'receiver_sn_sf'. 'passed_filter_sf' takes a value of NA, 0 or 1 depending on whether or not the detection was flagged as a false detection (if not, NA) and whether each false detection passed the spatial filter (no, 0; yes, 1). If the detection did pass the spatial filter, 'n_wn_sf' provides the number of detections at nearby receivers within \code{tf} and \code{sf}; and 'detection_timestamp_utc_sf', 'receiver_sn_sf' and 'dist_sf' define the timestamp of the detection at the nearest receiver, the receiver at which the detection was made and the distance between the two receivers respectively. +The function returns a vector, of the same length as \code{det} with three possible values: NA, which identifies detections which have not been flagged as false detections (i.e., \code{passed_filter = 0}, see \code{\link[glatos]{false_detections}}) and are therefore not passed through the spatial filter; 1, which identifies detections which `passed' the spatial filter (i.e., false detections which are accompanied by detections at nearby receivers within the defined spatial and temporal thresholds); or 0, which defines detections which `failed' the spatial filter (i.e., false detections which are not accompanied by detections at nearby receivers within the defined spatial and temporal thresholds). This vector has one attribute, `details', a dataframe with the same number of rows as \code{det} with the following columns: `passed_filter_sf', `n_wn_sf', `detection_timestamp_utc_sf' and `receiver_sn_sf'. `passed_filter_sf' takes a value of NA, 0 or 1 depending on whether or not the detection was flagged as a false detection (if not, NA) and whether each false detection passed the spatial filter (no, 0; yes, 1). If the detection did pass the spatial filter, `n_wn_sf' provides the number of detections at nearby receivers within \code{tf} and \code{sf}; and `detection_timestamp_utc_sf', `receiver_sn_sf' and `dist_sf' define the timestamp of the detection at the nearest receiver, the receiver at which the detection was made and the distance between the two receivers respectively. } \description{ The identification of false detections in acoustic telemetry data is an important aspect of processing and/or modelling these data. False detections can be identified using the short interval criterion, whereby any detection of an individual at a receiver which is not accompanied by other detections at the same receiver in a specified time window (depending on the nominal acoustic transmission delay) are flagged. This approach can be implemented using the \code{\link[glatos]{false_detections}} function in the \code{\link[glatos]{glatos}} package. Flag detections can then be examined, or passed through other filters, to examine their plausibility. diff --git a/man/process_quality_check.Rd b/man/process_quality_check.Rd index cb09cab..93dcb63 100644 --- a/man/process_quality_check.Rd +++ b/man/process_quality_check.Rd @@ -7,17 +7,17 @@ process_quality_check(acoustics, moorings, ids) } \arguments{ -\item{acoustics}{A dataframe which comprises passive acoustic telemetry detection time series. This must contain the following named columns: 'timestamp', a POSIXct vector which defines the time of each detection; 'receiver_id', a unique identifier of each receiver; and 'individual_id', a unique identifier of each individual (see \code{\link[flapper]{dat_acoustics}} for an example).} +\item{acoustics}{A dataframe which comprises passive acoustic telemetry detection time series. This must contain the following named columns: `timestamp', a POSIXct vector which defines the time of each detection; `receiver_id', a unique identifier of each receiver; and `individual_id', a unique identifier of each individual (see \code{\link[flapper]{dat_acoustics}} for an example).} -\item{moorings}{A dataframe which contains passive acoustic telemetry receiver metadata. This must contain the following named columns: 'receiver_id', a unique identifier for each receiver deployment; 'receiver_start_date', a POSIXct vector which defines the time of each receiver's deployment; and 'receiver_end_date', a POSIXct vector which defines the end of each receiver's deployment (see \code{\link[flapper]{dat_moorings}} for an example). If objects of class Date are provided for 'receiver_start_date' and 'receiver_end_date', these are coerced to POSIXct objects with a warning.} +\item{moorings}{A dataframe which contains passive acoustic telemetry receiver metadata. This must contain the following named columns: `receiver_id', a unique identifier for each receiver deployment; `receiver_start_date', a POSIXct vector which defines the time of each receiver's deployment; and `receiver_end_date', a POSIXct vector which defines the end of each receiver's deployment (see \code{\link[flapper]{dat_moorings}} for an example). If objects of class Date are provided for `receiver_start_date' and `receiver_end_date', these are coerced to POSIXct objects with a warning.} -\item{ids}{A dataframe which contains the passive acoustic telemetry individual metadata. This must contain the following named columns: 'individual_id', a unique identifier for each individual; 'tag_start_date', a POSIXct vector which defines the time of each tag's deployment; and 'tag_end_date', a POSIXct vector which defines the end of each tag's deployment (see \code{\link[flapper]{dat_ids}} for an example). If objects of class Date are provided for 'tag_start_date' and 'tag_end_date', these are coerced to POSIXct objects with a warning.} +\item{ids}{A dataframe which contains the passive acoustic telemetry individual metadata. This must contain the following named columns: `individual_id', a unique identifier for each individual; `tag_start_date', a POSIXct vector which defines the time of each tag's deployment; and `tag_end_date', a POSIXct vector which defines the end of each tag's deployment (see \code{\link[flapper]{dat_ids}} for an example). If objects of class Date are provided for `tag_start_date' and `tag_end_date', these are coerced to POSIXct objects with a warning.} } \value{ For each check, the function returns a message or a warning with relevant details. } \description{ -This function passes through passive acoustic telemetry datasets through some basic quality checks (see Details). Following data processing, these provide a useful 'final check' prior to analysis. +This function passes through passive acoustic telemetry datasets through some basic quality checks (see Details). Following data processing, these provide a useful `final check' prior to analysis. } \details{ The function implements the following checks: @@ -29,7 +29,7 @@ The function implements the following checks: \item False detections. False detections should be flagged. } -\code{\link[flapper]{process_quality_check}} is mainly designed to be implemented after data-processing has already taken place as a basic 'final check' for common issues in passive acoustic telemetry datasets. For each check, the function returns a message or warning depending on the outcome; subsequently, the most appropriate course of action (e.g., retention versus removal of flagged observations in \code{acoustics} will depend on the context). Other important checks -- such as checking for receivers which were lost and later recovered, excluding observations during receiver servicing dates, excluding observations during tag capture events and further investigation of false detections -- may be required. +\code{\link[flapper]{process_quality_check}} is mainly designed to be implemented after data-processing has already taken place as a basic `final check' for common issues in passive acoustic telemetry datasets. For each check, the function returns a message or warning depending on the outcome; subsequently, the most appropriate course of action (e.g., retention versus removal of flagged observations in \code{acoustics} will depend on the context). Other important checks -- such as checking for receivers which were lost and later recovered, excluding observations during receiver servicing dates, excluding observations during tag capture events and further investigation of false detections -- may be required. } \examples{ #### Prepare data diff --git a/man/process_receiver_id.Rd b/man/process_receiver_id.Rd index cebf880..2ce45c0 100644 --- a/man/process_receiver_id.Rd +++ b/man/process_receiver_id.Rd @@ -7,9 +7,9 @@ process_receiver_id(acoustics, moorings) } \arguments{ -\item{acoustics}{A dataframe which comprises passive acoustic telemetry detection time series. This must contain two named columns: 'timestamp', a POSIXct vector which defines the time of each detection; and 'receiver', a vector which defines the receiver at which each detection was made. The column 'receiver' should also be found in \code{moorings} (see below).} +\item{acoustics}{A dataframe which comprises passive acoustic telemetry detection time series. This must contain two named columns: `timestamp', a POSIXct vector which defines the time of each detection; and `receiver', a vector which defines the receiver at which each detection was made. The column `receiver' should also be found in \code{moorings} (see below).} -\item{moorings}{A dataframe which contains passive acoustic telemetry receiver metadata. This must contain four named columns: 'receiver', as above for \code{acoustics}; 'receiver_id', a unique identifier for each receiver deployment; 'receiver_start_date', a POSIXct vector which defines the time of each receiver deployment; and 'receiver_end_date', a POSIXct vector which defines the end of each receiver deployment. If objects of class Date are provided for 'receiver_start_date' and 'receiver_end_date', these are coerced to POSIXct objects with a warning so that the timing of receiver detections and deployment is comparable (i.e., of the same object type).} +\item{moorings}{A dataframe which contains passive acoustic telemetry receiver metadata. This must contain four named columns: `receiver', as above for \code{acoustics}; `receiver_id', a unique identifier for each receiver deployment; `receiver_start_date', a POSIXct vector which defines the time of each receiver deployment; and `receiver_end_date', a POSIXct vector which defines the end of each receiver deployment. If objects of class Date are provided for `receiver_start_date' and `receiver_end_date', these are coerced to POSIXct objects with a warning so that the timing of receiver detections and deployment is comparable (i.e., of the same object type).} } \value{ The function returns a vector of receiver IDs, as defined in the \code{moorings$receiver_id} column, which correspond to each detection in the \code{acoustics} dataframe. diff --git a/man/query_open_topo.Rd b/man/query_open_topo.Rd index b678723..731ccc4 100644 --- a/man/query_open_topo.Rd +++ b/man/query_open_topo.Rd @@ -27,7 +27,7 @@ query_open_topo( \item{...}{Additional arguments passed to \code{\link[raster]{raster}} if \code{x} is an \code{\link[raster]{Extent}} object, such as the \code{resolution}.} } \value{ -The function returns elevation ('z') values from the specified database as a matrix, if code \code{x} is a matrix, or a \code{\link[raster]{raster}}, if code \code{x} is a \code{\link[raster]{raster}} or an \code{\link[raster]{Extent}} object. Coordinates/areas without data are returned as NAs. +The function returns elevation (`z') values from the specified database as a matrix, if code \code{x} is a matrix, or a \code{\link[raster]{raster}}, if code \code{x} is a \code{\link[raster]{raster}} or an \code{\link[raster]{Extent}} object. Coordinates/areas without data are returned as NAs. } \description{ This function queries the Open Topo Data elevation Application Programming Interface (API) to extract elevation data for inputted coordinates, rasters, or areas. diff --git a/man/sim_array.Rd b/man/sim_array.Rd index f8c1f0b..d9348cd 100644 --- a/man/sim_array.Rd +++ b/man/sim_array.Rd @@ -26,7 +26,7 @@ sim_array( \item{coastline}{(optional) This argument is used to incorporate the presence of barriers, such as coastline, in the area. There are three options. If \code{coastline = NULL}, no barriers are incorporated. If \code{coastline = "simple_random"}, then a triangular island is simulated in the study area. Alternatively, a spatial object, such as a SpatialPolygonsDataFrame, that defines the coastline in an area can be incorporated into the array design by passing this \code{coastline}.} -\item{land_inside_coastline}{A logical variable that defines whether or not the land is 'inside' the polygon(s) defined by \code{coastline} (\code{land_inside_coastline = TRUE}) or the sea is 'inside' the polygon(s) (\code{land_inside_coastline = FALSE}).} +\item{land_inside_coastline}{A logical variable that defines whether or not the land is `inside' the polygon(s) defined by \code{coastline} (\code{land_inside_coastline = TRUE}) or the sea is `inside' the polygon(s) (\code{land_inside_coastline = FALSE}).} \item{n_receivers}{An integer that defines the number of receivers in the array. This is ignored if receiver locations are specified via \code{arrangement}.} @@ -43,7 +43,7 @@ sim_array( \item{verbose}{A logical variable that defines whether or not to print messages to the console to relay function progress.} } \value{ -The function returns a named list of (a) the spatial objects that define the simulated array ('array') and (b) the arguments used to generate this array ('args'). The 'array' element is a named list contains the following elements: 'boundaries', an \code{\link[raster]{Extent-class}} object that defines the boundaries of the area (as inputted); 'area', a \code{\link[sp]{SpatialPolygons-class}} object that defines the boundaries of the area; 'land' and 'sea', \code{\link[sp]{SpatialPolygons-class}} or \code{\link[sp]{SpatialPolygonsDataFrame-class}} objects that define the land and sea respectively; and 'xy', a \code{\link[sp]{SpatialPoints-class}} object that defines receiver locations. If \code{plot = TRUE}, the function also returns a plot of the array. +The function returns a named list of (a) the spatial objects that define the simulated array (`array') and (b) the arguments used to generate this array (`args'). The `array' element is a named list contains the following elements: `boundaries', an \code{\link[raster]{Extent-class}} object that defines the boundaries of the area (as inputted); `area', a \code{\link[sp]{SpatialPolygons-class}} object that defines the boundaries of the area; `land' and `sea', \code{\link[sp]{SpatialPolygons-class}} or \code{\link[sp]{SpatialPolygonsDataFrame-class}} objects that define the land and sea respectively; and `xy', a \code{\link[sp]{SpatialPoints-class}} object that defines receiver locations. If \code{plot = TRUE}, the function also returns a plot of the array. } \description{ This function is designed to simulate different kinds of array designs for monitoring stations. The function has been particularly inspired by the need to simulate passive acoustic telemetry array designs, which comprise networks of acoustic hydrophones that listen for acoustic transmissions from tagged marine animals. To implement the function, it is necessary to define the boundaries of the area (\code{boundaries}). Barriers to movement, such as coastline, within this area can be simulated or included from real datasets. The area is populated with a specified number of receivers (\code{n_receivers}) that are simulated under different array designs (namely, regular, random, stratified, non-aligned, hexagonal and clustered arrangements) or incorporated from real data. The function returns a list of spatial objects that define the array and, if requested, a plot of the area. diff --git a/man/sim_detections.Rd b/man/sim_detections.Rd index 93de63d..ad7317d 100644 --- a/man/sim_detections.Rd +++ b/man/sim_detections.Rd @@ -39,7 +39,7 @@ sim_detections( \item{verbose}{A logical variable that defines whether or not to print messages to the console to relay function progress.} } \value{ -If \code{delta_t = NULL}, then function returns a named list with three matrices that define, for each path position (rows) and each receiver (columns), (a) the distance of that position from each receiver ('dist_mat'), (b) the probability of detection at that receiver ('prob_mat') and (c) the simulated outcome (0, no detection; 1, detection) ('det_mat'). If \code{delta_t} is specified, then the function returns a list with a 'raw' and an 'agg' element. The raw elements contains the matrices described above; the 'agg' element contains the aggregated versions of these matrices, with detections summed over each \code{delta_t} interval and distances and probabilities averaged (using the arithmetic mean) over each interval. If \code{plot = TRUE}, the function also returns a plot of the (raw) detections (0, 1) and, if specified, the corresponding probabilities. +If \code{delta_t = NULL}, then function returns a named list with three matrices that define, for each path position (rows) and each receiver (columns), (a) the distance of that position from each receiver (`dist_mat'), (b) the probability of detection at that receiver (`prob_mat') and (c) the simulated outcome (0, no detection; 1, detection) (`det_mat'). If \code{delta_t} is specified, then the function returns a list with a `raw' and an `agg' element. The raw elements contains the matrices described above; the `agg' element contains the aggregated versions of these matrices, with detections summed over each \code{delta_t} interval and distances and probabilities averaged (using the arithmetic mean) over each interval. If \code{plot = TRUE}, the function also returns a plot of the (raw) detections (0, 1) and, if specified, the corresponding probabilities. } \description{ This function simulates detections at passive acoustic telemetry receivers under a detection model that depends on distance. To implement the function, the underlying movement path that gives rise to detections (or not) must be supplied (via \code{path}) along with the locations of receivers (\code{xy}) at which detections can be made. At each point along the movement path (i.e., time step), the function calculates the distances from that point to all of the receivers and evaluates a user-supplied detection probability function, based on distance, to determine detection probability at each receiver. The function then simulates binary detection outcomes from a binomial distribution conditional on this probability, and returns these in a matrix with one simulated outcome for each time step and receiver. diff --git a/man/sim_path_ou_1.Rd b/man/sim_path_ou_1.Rd index 44d73be..11fabc0 100644 --- a/man/sim_path_ou_1.Rd +++ b/man/sim_path_ou_1.Rd @@ -23,9 +23,9 @@ sim_path_ou_1( \item{r_1}{(optional) A matrix with one row and two columns that defines the starting location (x, y). If \code{r_1 = NULL}, then a random location is simulated from a uniform distribution with a minimum and maximum value of 0 and 1 respectively.} -\item{r_h}{A matrix with one row and two columns that defines the 'home range' centre location (x, y).} +\item{r_h}{A matrix with one row and two columns that defines the `home range' centre location (x, y).} -\item{k}{A number that defines the strength of the 'central harmonic force' that pulls an individual back towards its home range centre.} +\item{k}{A number that defines the strength of the `central harmonic force' that pulls an individual back towards its home range centre.} \item{delta_t}{A number that defines the number of time units between each time step.} @@ -46,7 +46,7 @@ The function returns an n-row, two-column matrix that defines the simulated loca This function simulates movement paths under a discrete-time Ornstein-Uhlenbeck process in which the parameters of the movement model are assumed to remain constant through time. } \details{ -Ornstein-Uhlenbeck processes are convenient models for animal movement around a 'home range' centre. In the model, a parameter (\code{k}) 'pulls' the location of the individual (\eqn{\vec{r}}) back towards the centre of its home range (\eqn{\vec{r}^H}) as it moves away from this centre. This function implements the discretised form of the Ornstein-Uhlenbeck model in which the parameters of the movement model remain constant through time, and in which movement is not constrained by barriers, described by Alós et al. (2016) (see equations (8) and (9) in particular). Under this model, the position \eqn{\vec{r}} of the animal at time \eqn{n + 1} is given by: +Ornstein-Uhlenbeck processes are convenient models for animal movement around a `home range' centre. In the model, a parameter (\code{k}) `pulls' the location of the individual (\eqn{\vec{r}}) back towards the centre of its home range (\eqn{\vec{r}^H}) as it moves away from this centre. This function implements the discretised form of the Ornstein-Uhlenbeck model in which the parameters of the movement model remain constant through time, and in which movement is not constrained by barriers, described by Alós et al. (2016) (see equations (8) and (9) in particular). Under this model, the position \eqn{\vec{r}} of the animal at time \eqn{n + 1} is given by: \deqn{\vec{r}_{n + 1} = \vec{r}^H + e^{-k \Delta t} (\vec{r}_n - \vec{r}^H) + \vec{R}_n,} diff --git a/man/sim_path_sa.Rd b/man/sim_path_sa.Rd index a159fba..1c66f0b 100644 --- a/man/sim_path_sa.Rd +++ b/man/sim_path_sa.Rd @@ -49,7 +49,7 @@ sim_angles(...) \item{...}{Additional arguments. For \code{\link[flapper]{sim_path_sa}}, these are passed to \code{\link[prettyGraphics]{pretty_map}} to customise the map. For the default \code{\link[flapper]{sim_angles}} and \code{\link[flapper]{sim_steps}} functions, \code{...} is required but additional parameters are ignored.} } \value{ -The function returns a named list of arguments that defines the simulated path ('xy_mat', 'angle_mat', 'step_mat' and 'path') and a named list of arguments that were used to generate the path ('args'). 'xy_mat' is an n-row, two-column matrix that defines the simulated position (x, y) at each time step; 'angle_mat' and 'step_mat' are n-row, one-column matrices that define the simulated turning angle (degrees) and step length (in map units) at each time step; and 'path' is a \code{\link[sp]{SpatialLines}} representation of the movement path. +The function returns a named list of arguments that defines the simulated path (`xy_mat', `angle_mat', `step_mat' and `path') and a named list of arguments that were used to generate the path (`args'). `xy_mat' is an n-row, two-column matrix that defines the simulated position (x, y) at each time step; `angle_mat' and `step_mat' are n-row, one-column matrices that define the simulated turning angle (degrees) and step length (in map units) at each time step; and `path' is a \code{\link[sp]{SpatialLines}} representation of the movement path. } \description{ This function simulates movement paths from step lengths and turning angles. To implement the function, the number of time steps (\code{n}) needs to be specified and, if applicable, the area within which movement should occur. For example, in marine environments, the inclusion of the sea as a spatial layer would restrict movement within the sea*. The starting location (\code{p_1}) can be provided or simulated. At each time step, user-defined functions are used to simulate step lengths and turning angles, which can depend previous values of those variables via a \code{lag} parameter, from which the next position is calculated. This implementation enables movement paths to be simulated under a variety of movement models, including random walks and correlated random walks, providing that they are conceptualised in terms of step lengths and turning angles. The function returns a list of outputs that includes the simulated path and, if requested, produces a plot of the simulated path. diff --git a/man/split_raster_equally.Rd b/man/split_raster_equally.Rd index 71612b9..b3dd6d8 100644 --- a/man/split_raster_equally.Rd +++ b/man/split_raster_equally.Rd @@ -4,7 +4,7 @@ \alias{split_raster_equally} \title{Split a raster into equal-area parts} \source{ -The function taken and slightly modified from the 'greenbrown' package (see https://rdrr.io/rforge/greenbrown/src/R/SplitRasterEqually.R). The function is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. +The function taken and slightly modified from the `greenbrown' package (see https://rdrr.io/rforge/greenbrown/src/R/SplitRasterEqually.R). The function is defined separately in \code{\link[flapper]{flapper}} to reduce reliance on non-default packages. } \usage{ split_raster_equally(r, n)