lcp_costs: Calculate the distances between connected cells in a Raster*

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

Calculate the distances between connected cells in a Raster*

Description

This function calculates distances between connected cells in a raster, given (a) the planar distances between connected cells and (b) differences in elevation.

Usage

lcp_costs(surface, verbose = TRUE)

Arguments

surface

A raster for which to calculate distances. The surface must be planar (i.e., Universal Transverse Mercator projection) with units of metres in the x, y and z directions. The surface's resolution is taken to define the distance between connected cells in the x and y directions and must be the same in both cases (for surface's with unequal horizontal resolution, resample can be used to equalise resolution).

verbose

A logical function that defines whether or not to print messages to the console to relay function progress.

Details

This function was motivated by the need to determine the shortest paths between locations over the seabed for benthic animals (see lcp_over_surface). An animal's movement can be conceptualised as that of a queen on a chessboard, which can move, in eight directions around its current position, across a surface. Movements in the x and y direction are termed ‘rook’s movement' and movements in the diagonal direction are termed ‘bishop’s movement'.

Under this framework, the distance that an entity must travel between connected cells depends on the planar distances between cells and their differences in elevation. Planar distances (d_p, m) depend on the movement type: under a rook's movement (i.e., horizontally or vertically), the distance (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 d_{p,b} is given by Pythagoras' Theorem: d_{p,b} = \sqrt{(d_{p, r}^2 + d_{p, r}^2)}. Vertical distances (d_v, m) are simply the differences in height between cells. The total distance (d_t) between any two connected cells is a combination of these distances given by Pythagoras' Theorem: d_t = \sqrt{(d_p^2 + d_v^2)}.

The function returns a warning produced by transition which is implemented to facilitate the definition of distances 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.

Value

The function returns a named list of sparse dsCMatrix-class matrices that define 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’).

Author(s)

Edward Lavender

See Also

This routine is implemented by the lcp_over_surface function to calculate the shortest path(s) and/or the distance(s) of the shortest paths(s) between origin and destination coordinates, and by the lcp_from_point function to calculate the shortest distances from a point on a raster to surrounding cells.

Examples

# In this example, consider the distances between connected cells in the example
# ... 'dat_gebco' raster. For speed, we will focus on a subset of the area.
# ... Within this area, we need to regularise the resolution:
boundaries <- raster::extent(707884.6, 709884.6, 6253404, 6255404)
blank <- raster::raster(boundaries, res = c(5, 5))
r <- raster::resample(dat_gebco, blank)
# Implement algorithm
costs <- lcp_costs(r)
# Examine outputs
utils::str(costs)

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