dist_btw_receivers: Compute Euclidean distances between receivers

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

Compute Euclidean distances between receivers

Description

This function computes Euclidean distances (km) between all combinations of receivers.

Usage

dist_btw_receivers(moorings, f = NULL, return = c("data.frame", "matrix"))

Arguments

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 dat_moorings).
f	(optional) A function to process distances. For example, round distances to the nearest km with f = function(x) round(x, digits = 0) or simply round.
return	A character that defines the class of the returned object ("data.frame" or "matrix").

Details

Distances are calculated via pointDistance. If moorings contains ‘receiver_long’ and ‘receiver_lat’, pointDistance is implemented with lonlat = TRUE and distances are in km; otherwise 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 pointDistance directly.

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.

Author(s)

Edward Lavender

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]

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.