dist_btw_receivers.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dists.R
\name{dist_btw_receivers}
\alias{dist_btw_receivers}
\title{Compute Euclidean distances between receivers}
\usage{
dist_btw_receivers(moorings, f = NULL, return = c("data.frame", "matrix"))
}
\arguments{
\item{moorings}{A dataframe that defines each unique receiver deployment. This should contain the columns: `receiver_id', a unique identifier of each receiver; `receiver_long' or `receiver_easting', the longitude or easting of that receiver; and `receiver_lat' or `receiver_northing', the latitude or northing that receiver (see \code{\link[flapper]{dat_moorings}}).}

\item{f}{(optional) A function to process distances. For example, round distances to the nearest km with \code{f = function(x) round(x, digits = 0)} or simply \code{round}.}

\item{return}{A character that defines the class of the returned object (\code{"data.frame"} or \code{"matrix"}).}
}
\value{
The function returns a dataframe, with columns `r1', `r2' and `dist', or a matrix. Dataframe columns define the IDs of each combination of receivers and the associated distance between them, in km (or map units/1000). Note that the dataframe contains duplicate combinations of receivers (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). Alternatively, matrix rows and columns define receiver IDs and cell values give distances between each combination.
}
\description{
This function computes Euclidean distances (km) between all combinations of receivers.
}
\details{
Distances are calculated via \code{\link[raster]{pointDistance}}. If \code{moorings} contains `receiver_long' and `receiver_lat', \code{\link[raster]{pointDistance}} is implemented with \code{lonlat = TRUE} and distances are in km; otherwise \code{lonlat = FALSE} and distances are in map units over 1000 (i.e., km if map units are metres).

To calculate distances between specific receiver pairs, call \code{\link[raster]{pointDistance}} directly.
}
\examples{
#### Example (1): Implementation using lat/long coordinates
dat <- data.frame(
  receiver_id = dat_moorings$receiver_id,
  receiver_long = dat_moorings$receiver_long,
  receiver_lat = dat_moorings$receiver_lat
)
# Compute distances
dist_btw_receivers_km <- dist_btw_receivers(dat)
head(dist_btw_receivers_km)

#### Example (2): Implementation using planar coordinates
proj_wgs84 <- sp::CRS(SRS_string = "EPSG:4326")
proj_utm <- sp::CRS(SRS_string = "EPSG:32629")
xy <- sp::SpatialPoints(
  dat[, c("receiver_long", "receiver_lat")],
  proj_wgs84
)
xy <- sp::spTransform(xy, proj_utm)
xy <- sp::coordinates(xy)
dat <- data.frame(
  receiver_id = dat_moorings$receiver_id,
  receiver_easting = xy[, 1],
  receiver_northing = xy[, 2]
)
head(dist_btw_receivers(dat))

#### Example (3): Post-process distances via the f argument
dist_btw_receivers_km_round <- dist_btw_receivers(dat, f = round)
head(dist_btw_receivers_km_round)
# convert distances to m
dist_btw_receivers_m <- dist_btw_receivers(dat, f = function(x) x * 1000)
head(dist_btw_receivers_m)

#### Example (4) Return distances in a matrix
# Get distances
dist_btw_receivers(dat, return = "matrix")
# Compare sample to dataframe
dist_btw_receivers(dat)[1:5, ]
dist_btw_receivers(dat, return = "matrix")[1:5, 1:5]

}
\author{
Edward Lavender
}