fetch_len: Calculate the fetch length around a point

In pmarchand1/waver: Calculate Fetch and Wave Energy

Calculate the fetch length around a point

Description

Given a point, a shoreline layer and a vector of wind directions (bearings), fetch_len calculates the distance from point to shore for each bearing.

Usage

fetch_len(
  p,
  bearings,
  shoreline,
  dmax,
  spread = 0,
  projected = FALSE,
  check_inputs = TRUE
)

Arguments

p	Simple feature (sf or sfc) object representing a single point.
bearings	Vector of bearings, in degrees.
shoreline	Simple feature (sf or sfc) object representing the shoreline, in either line or polygon format.
dmax	Maximum value of fetch length, returned if there is no land within a distance of dmax from a given bearing.
spread	Vector of relative bearings (in degrees) for which to calculate fetch around each main bearing (see details).
projected	Deprecated argument, kept for backwards compatibility.
check_inputs	Should the validity of inputs be checked? It is recommended to keep this TRUE, unless this function is called repeatedly from another function that already checks inputs.

Details

The fetch length (or fetch) is the distance of open water over which the wind can blow in a specific direction. Note that bearings represent the direction from where the wind originates.

The optional spread argument defines relative directions that are added to each main bearing to produce a set of sub-bearings. The fetch lengths calculated for each sub-bearing are averaged with weights proportional to cos(spread). By default, spread = 0 and fetch length is calculated for the main bearings only.

The input data can be in either geographic (long, lat) or projected coordinates, but p and shoreline must share the same coordinate system. Distances are calculated using the st_distance function from the sf package and expressed in the units of the coordinate system used, or in meters if using geographic coordinates. For geographic coordinates, we recommend setting sf_use_s2(FALSE), which results in st_distance using the ellipsoid distance calculation (requires the lwgeom package), instead of the less precise spherical distance calculation. For projected coordinates, the Euclidean distance is calculated.

If the shoreline layer is composed of polygons rather than lines, the function verifies that the input point is outside all polygons (i.e. in water). If this is not the case, it issues a warning and returns a vector of NA.

Value

A named vector representing the fetch length for each direction given in bearings.

See Also

fetch_len_multi for an efficient alternative when computing fetch length for multiple points.

Examples

 pt <- st_sfc(st_point(c(0, 0)), crs = st_crs(4326))
 # Shoreline is a rectangle from (-0.2, 0.25) to (0.3, 0.5)
 rect <- st_polygon(list(cbind(c(rep(-0.2, 2), rep(0.3, 2), -0.2),
                               c(0.25, rep(0.3, 2), rep(0.25, 2)))))
 land <- st_sfc(rect, crs = st_crs(4326))
 fetch_len(pt, bearings = c(0, 45, 225, 315), land,
           dmax = 50000, spread = c(-10, 0, 10))

pmarchand1/waver documentation built on Oct. 3, 2023, 12:18 p.m.