fetch: Calculate Wind Fetch
In fetchR: Calculate Wind Fetch

Description Usage Arguments Details Value Note See Also Examples

Wind fetch is the unobstructed length of water over which wind can blow, and it is commonly used as a measure of exposure to wind and waves at coastal sites. The fetch function automatically calculates the wind fetch for marine locations within the boundaries of the specified coastline layer. This allows wind fetch to be calculated anywhere around the globe.

1 2	fetch(polygon_layer, site_layer, max_dist = 300, n_directions = 9, site_names, quiet = FALSE)

`polygon_layer`	`SpatialPolygons`* object where the polygon geometries represent any obstructions to fetch calculations including the coastline, islands and/or exposed reefs.
`site_layer`	`SpatialPoints`* object where the point geometries represent the site locations.
`max_dist`	numeric. Maximum distance in kilometres (default 300). This will need to be scaled manually if the units for the CRS are not 'm'.
`n_directions`	numeric. The number of fetch vectors to calculate per quadrant (default 9).
`site_names`	character vector of the site names. If missing, the site names are taken from a column of the data associated with `site_layer` matching the regular expression `^[Nn]ames{0,1}`. If there is no such column, then default names are created ('Site 1', 'Site 2', ...).
`quiet`	logical. Suppress diagnostic messages? (Default `FALSE`).

The function takes a SpatialPolygons-class object (polygon_layer) that represents the coastline, surrounding islands, and any other obstructions, and calculates the wind fetch for every specified direction. This is calculated for all the user-defined sites, that are represented as the point geometries in a SpatialPoints-class object.

The directions for which the wind fetch are calculated for each site are determined by the number of directions per quadrant (n_directions). The default value of 9 calculates 9 fetch vectors per quadrant (90 degrees), or equivalently, one fetch vector every 10 degrees. The first fetch vector is always calculated for the northerly direction (0/360 degrees).

Returns a Fetch object.

At least one of the inputs to the polygon_layer or site_layer arguments must be projected. If one of the inputs are not projected, then it will be transformed to have the same projection as the other. If both are projected, but do not have identical coordinate reference systems (CRS) then site_layer will be transformed to the same CRS as polygon_layer.

spTransform for methods on transforming map projections and datum.

is.projected for checking whether a spatial object is projected.

fetchR for an overview of this package with an extensive, reproducible example.

summary,Fetch-method for summarising the fetch lengths.

# Create the polygon layer ----------------------------------------
#
# This is the layer that represents any obstacles that obstruct wind flow.

# Import map data for the Philippines.
philippines.df = ggplot2::map_data("world", region = "Philippines")

# Create a list for each separate polygon
philippines.list = split(philippines.df[, c("long", "lat")], 
                         philippines.df$group)
                         
library(sp)

philippines.Poly = lapply(philippines.list, Polygon)
philippines.Polys = list(Polygons(philippines.Poly, ID = "Philippines"))

# Include CRS information to make it a SpatialPolygons object
philippines.sp = SpatialPolygons(philippines.Polys, 
                                     proj4string = CRS("+init=epsg:4326"))

# Create the points layer ----------------------------------------
#
# The points layer represents the locations for which the wind fetch needs to
# be calculated.

# We need to calculate wind fetch for the following 3 sites:
sites.df = data.frame(lon = c(124.4824, 125.8473, 124.8416),
                      lat = c(9.167999, 9.751394, 11.478243),
                      site = c("Camiguin Island", "Bucas Grande Island",
                               "Talalora"))
                      
# Create the SpatialPoints object
sites.sp = SpatialPoints(sites.df[, 1:2], CRS("+init=epsg:4326"))

# Map projection -------------------------------------------------
#
# At least one of the polygon or points layers need to be projected to 
# calculate wind fetch.

# All these locations lie within the Philippines zone 5 / PRS92, that has
# WGS84 Bounds: 123.8000, 5.3000, 126.7000, 12.7500
# (http://spatialreference.org/ref/epsg/3125/)
# This suggests that this is a suitable map projection.
philippines.proj = spTransform(philippines.sp, "+init=epsg:3125")

# Calculate wind fetch -------------------------------------------
# 
# Calculate wind fetch at all the 3 locations for every 10 degrees on the
# compass rose, with a maximum distance for any fetch vector of 300 km.
my_fetch = fetch(philippines.proj, sites.sp, site_names = sites.df$site)
my_fetch

# Return only the summary data frame
summary(my_fetch)

# Transform the fetch vectors back to the original CRS
my_fetch_latlon = spTransform(my_fetch, proj4string(philippines.sp))

# Return the raw data in the original, lat/lon coordinates
my_fetch_latlon.df = as(my_fetch_latlon, "data.frame")
my_fetch_latlon.df

# Plot the wind fetch vectors ------------------------------------

# Plot the fetch vectors in the projected space...
plot(my_fetch, philippines.proj, axes = TRUE)

# ... or in the original coordinate reference system
plot(my_fetch, philippines.sp, axes = TRUE)

# Output to KML --------------------------------------------------
## Not run: 

# Save a KML file in the current working directory.
kml(my_fetch, colour = "white")

## End(Not run)