Calculate Fetch for Lake Sampling Sites

Main entry point for fetch calculation. Takes sites and lake boundaries, calculates directional fetch using ray-casting, and returns results with exposure metrics.

Usage

fetch_calculate(
  sites,
  lake,
  depth_m = NULL,
  fetch_method = NULL,
  add_context = TRUE,
  find_max_fetch = FALSE
)

Arguments

sites

Data frame or sf object with site locations

lake

Lake boundary data from get_lake_boundary

depth_m

Water depth in meters for orbital velocity calculation. Can be a single value (applied to all sites), a vector (one per site), or NULL to use depth from sites data or default from options.

fetch_method

Method for calculating effective fetch. Options:

"top3": Mean of the 3 highest directional fetch values (default)
"max": Maximum directional fetch value
"cosine": SPM/CERC cosine-weighted average. Uses 9 radials centered on the direction of maximum fetch at 6-degree intervals, weighted by cosine of angle from center. Based on Shore Protection Manual (1984).

If NULL, uses the value from lakefetch_options.

add_context

Logical; add NHD context if available (default TRUE)

find_max_fetch

Logical; if TRUE, finds the location in each lake with the maximum possible fetch using a longest-internal-chord algorithm. The result is returned as a $max_fetch element in the output list. Default FALSE.

Value

A list with elements:

results: sf object with fetch results for each site
lakes: sf object with lake polygons used
angles: Vector of angles used for fetch calculation
max_fetch: (only if find_max_fetch = TRUE) sf object with one row per lake containing the maximum fetch location, chord length (meters), and chord bearing (degrees)

Details

For each site, the function:

Assigns the site to its containing lake polygon
Buffers the site inward from shore (GPS accuracy adjustment)
Casts rays in all directions at specified angle resolution
Measures distance to shore in each direction
Calculates summary metrics (mean, max, effective fetch)
Calculates orbital velocity using depth
Derives exposure category (Sheltered/Moderate/Exposed)

Exposure thresholds can be configured via lakefetch_options.

References

Shore Protection Manual (1984). U.S. Army Corps of Engineers, Coastal Engineering Research Center. 4th Edition.

Examples

# \donttest{
csv_path <- system.file("extdata", "sample_sites.csv", package = "lakefetch")
sites <- load_sites(csv_path)
#> Loading data from: /github/home/R/x86_64-pc-linux-gnu-library/4.6/lakefetch/extdata/sample_sites.csv
#>   Loaded 2 rows with columns: Site, latitude, longitude, lake.name
#>   Using columns: Latitude = latitude, Longitude = longitude
#>   Preserved lake name column: lake.name
#>   Final valid samples: 2
#>   Detected location from column 'lake.name': Blue Mountain Lake
lake <- get_lake_boundary(sites)
#> Converting to spatial format...
#> Spherical geometry (s2) switched off
#> Downloading lake boundaries from OpenStreetMap...
#>   Bounding box: [-74.4561, 43.8545, -74.4304, 43.8751]
#>     Trying name-filtered query for: Blue Mountain Lake
#>     Error: arguments imply differing number of rows: 1160, 0
#>     Server error, trying another server in 10s...
#>     Failed after 3 attempts: arguments imply differing number of rows: 1160, 0
#>     Querying natural=water...
#>     Error: arguments imply differing number of rows: 1160, 0
#>     Server error, trying another server in 6s...
#>     Failed after 3 attempts: HTTP 504 Gateway Timeout.
#>     Querying water=lake...
#>     Error: arguments imply differing number of rows: 1160, 0
#>     Server error, trying another server in 6s...
#>     Failed after 3 attempts: arguments imply differing number of rows: 1160, 0
#> Warning: No water bodies found in OpenStreetMap - creating approximate boundary
#> Spherical geometry (s2) switched on
results <- fetch_calculate(sites, lake)
#> Effective fetch method: top3
#> Using default depth: 10 m
#> Assigning sites to lakes...
#>   Checking direct intersections...
#>     2 sites matched directly
#>   Site assignment summary:
#>     Matched: 2/2
#>   Sites per lake:
#>     Approximate Boundary: 2 sites
#> Calculating fetch for multiple lakes...
#>   Buffering sites 10m inward
#>   Angle resolution: 5 degrees
#> Processing 1 lake(s)...
#> Using sequential processing
#>   Processing 2 samples in lake: Approximate Boundary
#> Fetch calculation complete.
#> Adding lake context (NHD integration)...
#>   Fetching NHD waterbodies...
#>     Found 68 NHD waterbodies
#>   Processing lake: fallback
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#>     Found 7 outlet(s) and 4 inlet(s)
#> Warning: st_centroid assumes attributes are constant over geometries
#> Lake context complete.

# With explicit depth
results <- fetch_calculate(sites, lake, depth_m = 5)
#> Effective fetch method: top3
#> Using provided depth: 5 m
#> Assigning sites to lakes...
#>   Checking direct intersections...
#>     2 sites matched directly
#>   Site assignment summary:
#>     Matched: 2/2
#>   Sites per lake:
#>     Approximate Boundary: 2 sites
#> Calculating fetch for multiple lakes...
#>   Buffering sites 10m inward
#>   Angle resolution: 5 degrees
#> Processing 1 lake(s)...
#> Using sequential processing
#>   Processing 2 samples in lake: Approximate Boundary
#> Fetch calculation complete.
#> Adding lake context (NHD integration)...
#>   Fetching NHD waterbodies...
#>     Found 68 NHD waterbodies
#>   Processing lake: fallback
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#>     Found 7 outlet(s) and 4 inlet(s)
#> Warning: st_centroid assumes attributes are constant over geometries
#> Lake context complete.

# Using cosine-weighted effective fetch (SPM method)
results <- fetch_calculate(sites, lake, fetch_method = "cosine")
#> Effective fetch method: cosine
#> Using default depth: 10 m
#> Assigning sites to lakes...
#>   Checking direct intersections...
#>     2 sites matched directly
#>   Site assignment summary:
#>     Matched: 2/2
#>   Sites per lake:
#>     Approximate Boundary: 2 sites
#> Calculating fetch for multiple lakes...
#>   Buffering sites 10m inward
#>   Angle resolution: 5 degrees
#> Processing 1 lake(s)...
#> Using sequential processing
#>   Processing 2 samples in lake: Approximate Boundary
#> Fetch calculation complete.
#> Adding lake context (NHD integration)...
#>   Fetching NHD waterbodies...
#>     Found 68 NHD waterbodies
#>   Processing lake: fallback
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#>     Found 7 outlet(s) and 4 inlet(s)
#> Warning: st_centroid assumes attributes are constant over geometries
#> Lake context complete.

# Access results
results$results  # sf with all fetch data
#> Simple feature collection with 2 features and 99 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 544509 ymin: 4856976 xmax: 544967.4 ymax: 4857039
#> Projected CRS: WGS 84 / UTM zone 18N
#>     Site site_name          lake.name lake_osm_id            lake_name
#> 1 BML1_1      BML1 Blue Mountain Lake    fallback Approximate Boundary
#> 2 BML2_2      BML2 Blue Mountain Lake    fallback Approximate Boundary
#>   lake_area_km2 depth_m  fetch_0  fetch_5 fetch_10 fetch_15 fetch_20 fetch_25
#> 1       83.1317      10 5041.214 5005.441 4998.477 5000.000 4998.477 4998.477
#> 2       83.1317      10 5000.000 4998.477 5002.450 5034.868 5076.148 5114.969
#>   fetch_30 fetch_35 fetch_40 fetch_45 fetch_50 fetch_55 fetch_60 fetch_65
#> 1 5000.000 4998.477 4998.477 5000.000 4998.477 4998.477 5000.000 4998.477
#> 2 5154.192 5193.338 5229.671 5263.944 5296.987 5328.404 5356.646 5380.916
#>   fetch_70 fetch_75 fetch_80 fetch_85 fetch_90 fetch_95 fetch_100 fetch_105
#> 1 4998.477 5000.000 4998.477 4998.477 5000.000 4998.477  4998.477  5000.000
#> 2 5402.686 5421.692 5437.713 5449.734 5456.814 5460.546  5460.878  5457.806
#>   fetch_110 fetch_115 fetch_120 fetch_125 fetch_130 fetch_135 fetch_140
#> 1  4998.477  4998.477   5000.00  4998.477  4998.477  5000.000  4998.477
#> 2  5451.375  5439.671   5424.27  5405.857  5384.647  5360.898  5332.888
#>   fetch_145 fetch_150 fetch_155 fetch_160 fetch_165 fetch_170 fetch_175
#> 1  4998.477  5000.000  4998.477  4998.477  5000.000  4998.477  4998.477
#> 2  5301.920  5269.274  5235.342  5199.137  5160.236  5121.194  5082.489
#>   fetch_180 fetch_185 fetch_190 fetch_195 fetch_200 fetch_205 fetch_210
#> 1  5000.000  4998.477  5002.450  5034.868  5076.148  5114.969  5154.192
#> 2  5041.214  5005.441  4998.477  5000.000  4998.477  4998.477  5000.000
#>   fetch_215 fetch_220 fetch_225 fetch_230 fetch_235 fetch_240 fetch_245
#> 1  5193.338  5229.671  5263.944  5296.987  5328.404  5356.646  5380.916
#> 2  4998.477  4998.477  5000.000  4998.477  4998.477  5000.000  4998.477
#>   fetch_250 fetch_255 fetch_260 fetch_265 fetch_270 fetch_275 fetch_280
#> 1  5402.686  5421.692  5437.713  5449.734  5456.814  5460.546  5460.878
#> 2  4998.477  5000.000  4998.477  4998.477  5000.000  4998.477  4998.477
#>   fetch_285 fetch_290 fetch_295 fetch_300 fetch_305 fetch_310 fetch_315
#> 1  5457.806  5451.375  5439.671   5424.27  5405.857  5384.647  5360.898
#> 2  5000.000  4998.477  4998.477   5000.00  4998.477  4998.477  5000.000
#>   fetch_320 fetch_325 fetch_330 fetch_335 fetch_340 fetch_345 fetch_350
#> 1  5332.888  5301.920  5269.274  5235.342  5199.137  5160.236  5121.194
#> 2  4998.477  4998.477  5000.000  4998.477  4998.477  5000.000  4998.477
#>   fetch_355 fetch_mean fetch_max fetch_effective orbital_effective
#> 1  5082.489   5141.107  5460.878        5442.483         0.2453896
#> 2  4998.477   5141.107  5460.878        5442.483         0.2453896
#>   exposure_category lake_max_chord_m fetch_proportion exposure_relative
#> 1           Exposed         10462.78        0.5201757           Exposed
#> 2           Exposed         10462.78        0.5201757           Exposed
#>                   geometry nhd_permanent_id nhd_gnis_name nhd_areasqkm
#> 1 POINT (544967.4 4856976)             <NA>  Utowana Lake         6.88
#> 2   POINT (544509 4857039)             <NA>  Utowana Lake         6.88
#>   outlet_dist_m outlet_bearing inlet_nearest_dist_m inlet_nearest_bearing
#> 1      4039.902             NW             2254.594                     S
#> 2      3807.798              N             2313.997                     S
#>   inlet_count connectivity_class outlet_stream_order watershed_area_ha
#> 1           4           Drainage                   1          484.2227
#> 2           4           Drainage                   1          484.2227
#>   lake_watershed_ratio
#> 1             1.420834
#> 2             1.420834
results$lakes    # lake polygons
#> Simple feature collection with 1 feature and 3 fields
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 539509 ymin: 4851976 xmax: 549967.4 ymax: 4862039
#> Projected CRS: WGS 84 / UTM zone 18N
#>                   name   osm_id area_km2                       geometry
#> 1 Approximate Boundary fallback  83.1317 POLYGON ((544967.4 4851976,...

# Find the location with maximum fetch in each lake
results <- fetch_calculate(sites, lake, find_max_fetch = TRUE)
#> Effective fetch method: top3
#> Using default depth: 10 m
#> Assigning sites to lakes...
#>   Checking direct intersections...
#>     2 sites matched directly
#>   Site assignment summary:
#>     Matched: 2/2
#>   Sites per lake:
#>     Approximate Boundary: 2 sites
#> Calculating fetch for multiple lakes...
#>   Buffering sites 10m inward
#>   Angle resolution: 5 degrees
#> Processing 1 lake(s)...
#> Using sequential processing
#>   Processing 2 samples in lake: Approximate Boundary
#> Fetch calculation complete.
#> Adding lake context (NHD integration)...
#>   Fetching NHD waterbodies...
#>     Found 68 NHD waterbodies
#>   Processing lake: fallback
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#> Warning: attribute variables are assumed to be spatially constant throughout all geometries
#>     Found 7 outlet(s) and 4 inlet(s)
#> Warning: st_centroid assumes attributes are constant over geometries
#> Lake context complete.
#> Finding maximum fetch locations...
#>   Finding max fetch for: Approximate Boundary
results$max_fetch  # sf with max fetch location per lake
#> Simple feature collection with 1 feature and 7 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 544738.2 ymin: 4857007 xmax: 544738.2 ymax: 4857007
#> Projected CRS: WGS 84 / UTM zone 18N
#>              lake_name lake_osm_id max_chord_m chord_bearing_deg
#> 1 Approximate Boundary    fallback    10462.78          98.95099
#>   fetch_effective fetch_max fetch_mean                 geometry
#> 1        5229.622  5229.677   5143.555 POINT (544738.2 4857007)
# }

Usage

Arguments

Value

Details

References

Examples

About

Community

Resources