get_mvt_mobility.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_movement.R
\name{get_mvt_mobility}
\alias{get_mvt_mobility}
\alias{get_mvt_mobility_from_acoustics}
\alias{get_mvt_mobility_from_archival}
\title{Estimate individual swimming speeds from acoustic and archival data}
\usage{
get_mvt_mobility_from_acoustics(
  data,
  fct = NULL,
  moorings,
  detection_range,
  calc_distance = c("euclid", "lcp"),
  bathy = NULL,
  transmission_interval,
  step = NULL
)

get_mvt_mobility_from_archival(data, fct = NULL, step_check = TRUE)
}
\arguments{
\item{data}{A dataframe of animal movement time series used to estimate swimming speeds. For \code{\link[flapper]{get_mvt_mobility_from_acoustics}}, \code{data} should contain passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example). This must contain a vector of receiver IDs, named `receiver_id', and a POSIXct vector of time stamps when detections were made, named `timestamp'. For \code{\link[flapper]{get_mvt_mobility_from_archival}}, \code{data} is a dataframe that contains depth time series (see \code{\link[flapper]{dat_archival}} for an example). This must contain a numeric vector of observed depths (m), named `depth', and a POSIXct (or Date) vector of regular time stamps when observations were made, named `timestamp'. In either case, an additional column can be included to distinguish time series for different individuals (see \code{fct}).}

\item{fct}{(optional) A character variable that defines the name of a column in \code{data} that distinguishes levels of a grouping variable (e.g., individuals).}

\item{moorings}{In \code{\link[flapper]{get_mvt_mobility_from_acoustics}}, \code{moorings} is \code{\link[sp]{SpatialPointsDataFrame}} that defines receiver locations (in the Universe Transverse Mercator coordinate reference system) and receiver IDs (in a column named `receiver_id').}

\item{detection_range}{In \code{\link[flapper]{get_mvt_mobility_from_acoustics}}, \code{detection_range} is a number that defines the detection range (m) of receivers.}

\item{calc_distance}{In \code{\link[flapper]{get_mvt_mobility_from_acoustics}}, \code{calc_distance} is a character that defines the method used to calculate distances between receivers. Currently supported options are Euclidean distances (\code{"euclid"}) or least-cost (shortest) path distances ("lcp") over a surface (see \code{bathy}).}

\item{bathy}{In \code{\link[flapper]{get_mvt_mobility_from_acoustics}}, if \code{calc_distance = "lcp"}, \code{bathy} is \code{\link[raster]{raster}} that defines the surface over which individual(s) moved. \code{bathy} must be planar (i.e., Universal Transverse Mercator projection) with units of metres in x, y and z directions (m). The surface's resolution is taken to define the distance between horizontally and vertically connected cells and must be the same in both x and y directions. Any cells with NA values (e.g., due to missing data) are treated as `impossible' to move though by the algorithm (see \code{\link[flapper]{lcp_over_surface}}).}

\item{transmission_interval}{(optional) In \code{\link[flapper]{get_mvt_mobility_from_acoustics}}, \code{transmission_interval} is the (maximum) time delay between sequential acoustic transmissions.}

\item{step}{(optional) In \code{\link[flapper]{get_mvt_mobility_from_acoustics}}, \code{step} is a number that defines the time (s) interval over which to represent speeds. By default, speeds are calculated in m/s. If \code{step} is supplied, speeds are also calculated in m/step s, which can be easier to interpret. For \code{\link[flapper]{get_mvt_mobility_from_archival}}, `step' is set automatically as the duration (s) between sequential depth observations, which is assumed to remain constant through time.}

\item{step_check}{For \code{\link[flapper]{get_mvt_mobility_from_archival}}, \code{step_check} is a logical variable that defines whether or not to check that the steps in \code{data} are regular (see \code{step}).}
}
\value{
Both functions print a statistical summary of the speed estimates to the console and return a dataframe with observations and the corresponding speed estimates invisibly.

For \code{\link[flapper]{get_mvt_mobility_from_acoustics}}, for each speed estimate, the minimum, mean and maximum speeds are printed, in units of m/s and, if specified, m/step. The returned dataframe defines all transitions between receivers and includes the following columns:
\itemize{
  \item \code{fct} is the grouping factor (if specified);
  \item \code{receiver_id_1} and \code{receiver_id_2} are the receiver IDs for each transition between receivers;
  \item \code{timestamp_1} and \code{timestamp_2} are the time stamps of detections for each transition between receivers;
  \item \code{time} is the duration (s) between \code{timestamp_1} and \code{timestamp_2};
  \item \code{dist_min}, \code{dist_avg} and \code{dist_max} are the estimates for the distance (m) travelled to transition between receivers;
  \item \code{speed_min_ms}, \code{speed_avg_ms} and \code{speed_min_ms} are the corresponding speed (m/s) estimates;
  \item \code{speed_min_mstep}, \code{speed_avg_mstep} and \code{speed_max_mstep} are the corresponding speed estimates, in m per step (if specified);
}

For \code{\link[flapper]{get_mvt_mobility_from_archival}}, the function prints a statistical summary of estimated speeds in m/s and m per `step', where `step' is the duration (s) between sequential depth observations. The function also invisibly returns dataframe of the estimates. This is as inputted, without any \code{fct} levels with fewer than two observations and with the following additional columns:
\itemize{
  \item \code{dist} is the distance (m) between sequential depth observations;
  \item \code{speed_ms} is the speed (m/s) of vertical movement between sequential depth observations;
  \item \code{speed_mstep} is the speed of vertical movement between sequential depth observations in units of m per step, where `step' is the duration (s) between sequential depth observations (this is identical to \code{dist} and only added for consistency with \code{\link[flapper]{get_mvt_mobility_from_acoustics}});
}
}
\description{
These functions are designed to provide `ballpark' estimates of individual swimming speeds from (a) acoustic detections at passive acoustic telemetry receivers (\code{\link[flapper]{get_mvt_mobility_from_acoustics}}) and archival (depth) time series (\code{\link[flapper]{get_mvt_mobility_from_archival}}).
}
\details{
\subsection{Acoustic estimates}{Speed estimates from passive acoustic telemetry time series are derived from examination of detection patterns via \code{\link[flapper]{get_mvt_mobility_from_acoustics}}. For each \code{fct} group (e.g., individual), the function identifies sequential detections, which exceeded the maximum transmission interval, at receivers with non-overlapping detection containers (areas within the detection range of each receiver). Assuming that all detections are true, these can only result from movement between receivers. For these movements, transition distances are calculated as Euclidean distances, via \code{\link[raster]{pointDistance}}, or shortest swimming distances, assuming movement over a surface, via \code{\link[flapper]{lcp_over_surface}}. Given that detections can arise from movement anywhere within the detection range of a receiver, three distances are calculated: an average distance, from receiver to receiver; a lower-bound distance, between the closest edges of receiver detection containers (i.e., the average distance minus two times the detection range); and an upper-bound distance from the furthest edges of receiver detection ranges (i.e., the average distance plus two times the detection range). These estimates assume a uniform detection ranges over space. For each transition, distances are converted into an average, lower and upper speed (m/s) estimate (termed `speed_avg_ms`, `speed_min_ms` and `speed_max_ms` respectively). If \code{step} is supplied, speeds are also expressed per step. On many occasions, individuals will take indirect routes between receivers, resulting in inappropriately low speed estimates. However, if receivers are sufficiently close together such that individuals sometimes effectively transition directly between receivers, the faster speed estimates derived via this method may be quite informative about actual swimming speeds.}

\subsection{Archival estimates}{Speed estimates from \code{archival} time series are derived from examination of changes in depth through time (vertical activity) via \code{\link[flapper]{get_mvt_mobility_from_archival}}. For each individual, speed is calculated from the vertical distances (m) between sequential, regular depth (m) observations over time (s). Speeds are also expressed per step, where `step' is the duration (s) between sequential observations. The assumption of regular steps may be relaxed in the future.}
}
\examples{
#### Estimate mobility from acoustic data using Euclidean distances
## (A) Define receiver coordinates as SPDF in UTM CRS
proj <- sp::CRS(SRS_string = "EPSG:4326")
proj_utm <- sp::CRS(SRS_string = "EPSG:32629")
moorings <- sp::SpatialPoints(dat_moorings[, c("receiver_long", "receiver_lat")], proj)
moorings <- sp::spTransform(moorings, proj_utm)
moorings <- sp::SpatialPointsDataFrame(moorings, data.frame(receiver_id = dat_moorings$receiver_id))
## (B) Implement algorithm using Euclidean distances
mob_1 <- get_mvt_mobility_from_acoustics(
  data = dat_acoustics,
  fct = "individual_id",
  moorings = moorings,
  detection_range = 750,
  transmission_interval = 120,
  step = 120
)

#### Estimate mobility from acoustic data using LCP distances
## (A) Define receiver coordinates
# ... (as above)
## (B) Define bathymetry surface for LCP calculations
# Requirements: mask land; planar UTM projection; equal resolution;
bathy <- raster::raster(ext = raster::extent(dat_gebco), resolution = 50)
bathy <- raster::resample(dat_gebco, bathy, method = "bilinear")
## (C) Implement algorithm using LCP distances
mob_2 <- get_mvt_mobility_from_acoustics(
  data = dat_acoustics,
  fct = "individual_id",
  moorings = moorings,
  detection_range = 750,
  calc_distance = "lcp",
  bathy = bathy,
  transmission_interval = 120,
  step = 120
)

#### Estimate mobility from archival data
# Note the use of 'individual_id' for 'fct' here is only appropriate
# ... when there are no breaks in the time series.
mob_3 <- get_mvt_mobility_from_archival(dat_archival, fct = "individual_id")

}
\author{
Edward Lavender
}