Package {lakefetch}

lakefetch: Calculate Fetch and Wave Exposure for Lake Sampling Points

Description

The lakefetch package provides tools for calculating fetch (open water distance) and wave exposure metrics for lake sampling points. It downloads lake boundaries from OpenStreetMap, calculates directional fetch using ray-casting, and optionally integrates with NHD for hydrological context.

Main Functions

fetch_calculate

Main entry point for fetch calculation

load_sites

Load and validate site data

get_lake_boundary

Get lake boundary from OSM or file

add_lake_context

Add NHD hydrological context

fetch_app

Launch interactive Shiny app

Visualization

plot_fetch_map

Map of sites colored by exposure

plot_fetch_bars

Bar chart of effective fetch

plot_fetch_rose

Rose diagram for single site

create_ray_geometries

Create ray lines for mapping

Configuration

lakefetch_options

Get/set package options

lakefetch_reset_options

Reset options to defaults

Author(s)

Maintainer: Jeremy Lynch Farrell farrej2@rpi.edu

See Also

Useful links:

• https://docs.ropensci.org/lakefetch/

• https://github.com/ropensci/lakefetch

• Report bugs at https://github.com/ropensci/lakefetch/issues

Add Lake Context from NHD

Description

Add hydrological context to fetch results using the National Hydrography Dataset (NHD). Includes outlet/inlet locations, watershed area, connectivity classification, and stream order.

Usage

add_lake_context(fetch_results, lake_polygons, utm_epsg)

Arguments

Details

Requires the hydrogeofetch package. If not available, returns the input with NA columns added for consistent output format.

Added columns include:

• nhd_permanent_id: NHD permanent identifier

• nhd_gnis_name: GNIS name from NHD

• nhd_areasqkm: Area in square kilometers from NHD

• outlet_dist_m: Distance to outlet in meters

• outlet_bearing: Compass direction to outlet

• inlet_nearest_dist_m: Distance to nearest inlet

• inlet_nearest_bearing: Compass direction to nearest inlet

• inlet_count: Number of inlets

• connectivity_class: Headwater/Drainage/Terminal/Isolated

• outlet_stream_order: Strahler stream order at outlet

• watershed_area_ha: Watershed area in hectares

• lake_watershed_ratio: Lake area / watershed area

Value

sf object with additional columns for NHD context

Examples

csv_path <- system.file("extdata", "sample_sites.csv", package = "lakefetch")
sites <- load_sites(csv_path)
lake <- get_lake_boundary(sites)
results <- fetch_calculate(sites, lake)
results_with_context <- add_lake_context(results$results, results$lakes, lake$utm_epsg)

Add Depth Information to Fetch Results

Description

Looks up or estimates depth for each lake in the fetch results and adds depth columns.

Usage

add_lake_depth(fetch_results, lakes, user_depths = NULL)

Arguments

Value

fetch_results with added depth columns

Examples

data(adirondack_sites)
sites <- load_sites(adirondack_sites)
lake <- get_lake_boundary(sites)
results <- fetch_calculate(sites, lake)

# Add depth estimates
results$results <- add_lake_depth(results$results, results$lakes)

# Or provide known depths using an actual lake_osm_id from results
lake_id <- results$lakes$osm_id[1]
depths <- setNames(15.5, lake_id)
results$results <- add_lake_depth(results$results, results$lakes, user_depths = depths)

Add Weather Context to Fetch Results

Description

Adds historical weather metrics and cumulative wave energy to fetch calculation results. For each site, the function queries the Open-Meteo historical-weather API for wind speed and direction in the days leading up to the sample's datetime, combines those winds with the site's directional fetch to estimate wave height (Sverdrup-Munk-Bretschneider equations), and integrates wave energy across the requested look-back window(s).

Usage

add_weather_context(
  fetch_results,
  datetime_col = "datetime",
  windows_hours = c(24, 72, 168),
  depth_m = NULL
)

Arguments

Details

The input data must have a datetime column in POSIXct format or a format that can be parsed (ISO 8601, or common date-time formats). Network access to the Open-Meteo API is required; sites are queried sequentially with a short pause between calls to respect the public API rate limit.

Value

sf object with additional weather columns

Examples

csv_path <- system.file("extdata", "sample_sites.csv", package = "lakefetch")
sites <- load_sites(csv_path)
lake <- get_lake_boundary(sites)
results <- fetch_calculate(sites, lake)

# Add datetime to results
results$results$datetime <- as.POSIXct("2024-07-15 14:00:00")

# Add weather context
results_with_weather <- add_weather_context(
  results$results,
  datetime_col = "datetime"
)

Adirondack Lake Sampling Sites

Description

A dataset containing example lake sampling sites from the Adirondack region of New York State. These synthetic but realistic coordinates demonstrate typical multi-lake sampling scenarios.

Usage

adirondack_sites

Format

A data frame with 12 rows and 5 variables:

Site

Unique site identifier

lake.name

Name of the lake

latitude

Latitude in decimal degrees (WGS84)

longitude

Longitude in decimal degrees (WGS84)

datetime

Date and time of sampling (POSIXct)

Details

The dataset includes sites from four Adirondack lakes:

• Blue Mountain Lake (3 sites)

• Raquette Lake (4 sites)

• Long Lake (2 sites)

• Tupper Lake (3 sites)

Source

Synthetic data for demonstration purposes

Examples

# Load the dataset
data(adirondack_sites)

# View structure
str(adirondack_sites)


# Use with lakefetch (requires internet connection)
sites <- load_sites(adirondack_sites)
lake_data <- get_lake_boundary(sites)
results <- fetch_calculate(sites, lake_data)

Assign Sites to Lakes

Description

Perform spatial join to assign each site to its containing lake polygon.

Usage

assign_sites_to_lakes(sites_sf, water_polygons, tolerance_m = NULL)

Arguments

Value

sf object with sites and added columns for lake_osm_id, lake_name, lake_area_km2

Examples

csv_path <- system.file("extdata", "sample_sites.csv", package = "lakefetch")
sites <- load_sites(csv_path)
lake_data <- get_lake_boundary(sites)

# Assign sites to their containing lakes. Default tolerance (50 m) is
# appropriate for sites with accurate coordinates that fall inside the
# lake polygon. If your sites are near the shoreline or your GPS error is
# larger, increase tolerance_m (e.g., 200-500 m).
sites_assigned <- assign_sites_to_lakes(
  lake_data$sites,
  lake_data$all_lakes,
  tolerance_m = 200
)

# Check assignments
table(sites_assigned$lake_name)

Create Ray Geometries for Map Visualization

Description

Create line geometries representing fetch rays from each site. Useful for detailed visualization of the ray-casting results.

Usage

create_ray_geometries(fetch_data)

Arguments

Value

An sf object with ray line geometries

Examples

csv_path <- system.file("extdata", "sample_sites.csv", package = "lakefetch")
sites <- load_sites(csv_path)
lake <- get_lake_boundary(sites)
results <- fetch_calculate(sites, lake)
rays <- create_ray_geometries(results)

# Plot rays for a specific site
site_name <- results$results$Site[1]
site_rays <- rays[rays$Site == site_name, ]
ggplot2::ggplot() + ggplot2::geom_sf(data = site_rays, ggplot2::aes(color = Distance))

Blue Mountain Lake Polygon (Example Lake)

Description

The OpenStreetMap boundary polygon for Blue Mountain Lake in Hamilton County, New York. Bundled with the package so that fetch examples can run offline (no internet or Overpass API call required) and pkgdown pages can render plot output. The coordinates match the sites in system.file("extdata", "sample_sites.csv", package = "lakefetch"), so the two datasets can be used together end-to-end.

Usage

example_lake

Format

An sf object with 1 row and 3 fields plus geometry:

osm_id

OSM relation identifier

name

Lake name ("Blue Mountain Lake")

area_km2

Surface area in square kilometers

geometry

MULTIPOLYGON geometry in UTM Zone 18N (EPSG:32618)

Source

Downloaded from OpenStreetMap https://www.openstreetmap.org/. See data-raw/create_example_data.R for the exact query.

Examples

data(example_lake)
print(example_lake)

# Plot the lake
library(ggplot2)
ggplot(example_lake) + geom_sf()

# Load matching sample sites (they lie inside this polygon) and
# compute fetch end-to-end without touching OSM. First convert
# example_lake into the multi-lake list format that fetch_calculate()
# expects:
sites <- load_sites(system.file("extdata", "sample_sites.csv",
                                 package = "lakefetch"))
sites_sf <- sf::st_transform(
  sf::st_as_sf(sites, coords = c("longitude", "latitude"), crs = 4326,
               remove = FALSE),
  sf::st_crs(example_lake)
)
lake_data <- list(all_lakes = example_lake,
                  sites = sites_sf,
                  utm_epsg = sf::st_crs(example_lake)$epsg)
results <- fetch_calculate(sites, lake_data, add_context = FALSE)
sf::st_drop_geometry(results$results)[, c("Site", "fetch_effective",
                                           "exposure_category")]

Launch Interactive Fetch App

Description

Launch a Shiny app for interactive exploration of fetch calculation results. Click on site markers to view fetch rays and detailed information. Click anywhere on the map to analyze a new point.

Usage

fetch_app(fetch_data, title = NULL)

Arguments

Details

Requires the shiny, leaflet, and base64enc packages (suggested dependencies).

The app displays:

• Interactive map with satellite imagery

• Site markers colored by exposure category

• Click markers to see fetch rays

• Popup with rose diagram and metrics

• Click anywhere on the map to analyze a new point

Value

Launches a Shiny app (does not return)

Examples

if (interactive()) {
  sites <- load_sites("my_sites.csv")
  lake <- get_lake_boundary(sites)
  results <- fetch_calculate(sites, lake)
  fetch_app(results)
}

Launch Interactive Fetch App with File Upload

Description

Launch a standalone Shiny app where users can upload a CSV file with GPS coordinates, and the app will automatically download lake boundaries, calculate fetch, and display interactive results.

Usage

fetch_app_upload(title = "Lake Fetch Calculator")

Arguments

Details

Requires the shiny, leaflet, and base64enc packages (suggested dependencies).

The app workflow:

1. Upload a CSV file with latitude/longitude columns

2. App downloads lake boundaries from OpenStreetMap

3. Calculates fetch for all uploaded points

4. Displays interactive map with results

5. Click anywhere on a lake to analyze additional points

6. Download results as CSV or GeoPackage

CSV file requirements:

• Must have columns starting with "lat" and "lon" (case-insensitive)

• Optional "Site" column for point names

• Additional columns are preserved in output

Value

Launches a Shiny app (does not return)

Examples

if (interactive()) {
  # Launch the upload app
  fetch_app_upload()
}

Calculate Fetch for Lake Sampling Sites

Description

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

Details

For each site, the function:

1. Assigns the site to its containing lake polygon

2. Buffers the site inward from shore (GPS accuracy adjustment)

3. Casts rays in all directions at specified angle resolution

4. Measures distance to shore in each direction

5. Calculates summary metrics (mean, max, effective fetch)

6. Calculates orbital velocity using depth

7. Derives exposure category (Sheltered/Moderate/Exposed)

Exposure thresholds can be configured via lakefetch_options.

Value

A list with elements:

References

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

Examples

csv_path <- system.file("extdata", "sample_sites.csv", package = "lakefetch")
sites <- load_sites(csv_path)
lake <- get_lake_boundary(sites)
results <- fetch_calculate(sites, lake)

# With explicit depth
results <- fetch_calculate(sites, lake, depth_m = 5)

# Using cosine-weighted effective fetch (SPM method)
results <- fetch_calculate(sites, lake, fetch_method = "cosine")

# Access results
results$results  # sf with all fetch data
results$lakes    # lake polygons

# Find the location with maximum fetch in each lake
results <- fetch_calculate(sites, lake, find_max_fetch = TRUE)
results$max_fetch  # sf with max fetch location per lake

Get Lake Boundary

Description

Get lake boundary polygon(s) either from OpenStreetMap or from a local file.

Usage

get_lake_boundary(
  sites,
  file = NULL,
  timeout = 90,
  simplify_tolerance_m = 0,
  total_timeout_s = 300
)

Arguments

Details

If file is provided, the lake boundary is loaded from the file. Otherwise, the function downloads lake boundaries from OpenStreetMap based on the bounding box of the provided sites.

For very large lakes (> ~500 km^2), the default 90-second Overpass API timeout may be exceeded. Use timeout = 300 or higher in those cases. For lakes with very complex shorelines (e.g., Mälaren, Vättern, Võrtsjärv), additionally pass simplify_tolerance_m = 100 (or higher) to coarsen the polygon and speed up downstream fetch calculations.

Value

A list with elements:

Examples

csv_path <- system.file("extdata", "sample_sites.csv", package = "lakefetch")
sites <- load_sites(csv_path)
lake_data <- get_lake_boundary(sites)

# For very large lakes, increase the timeout
lake_data <- get_lake_boundary(sites, timeout = 300)

# For large/complex lakes, also coarsen the shoreline
lake_data <- get_lake_boundary(sites, timeout = 300,
                               simplify_tolerance_m = 100)

Get Lake Depth Estimates

Description

Retrieves or estimates lake depth for wave calculations. Uses user-provided depth if available, otherwise estimates from lake surface area using empirical relationships.

Usage

get_lake_depth(
  lake_polygon,
  site_coords = NULL,
  user_depth = NULL,
  method = "auto"
)

Arguments

Details

Depth estimation methods:

1. User-provided: Direct input, highest confidence

2. Empirical: Estimated from lake surface area using published relationships

The empirical method uses the relationship from Cael et al. (2017): mean_depth ~ 10.3 * area_km2^0.25

Value

A list with elements:

References

Messager, M.L., Lehner, B., Grill, G., Nedeva, I., Schmitt, O. (2016): Estimating the volume and age of water stored in global lakes using a geo-statistical approach. Nature Communications, 7: 13603.

Cael, B.B., Heathcote, A.J., Seekell, D.A. (2017): The volume and mean depth of Earth's lakes. Geophysical Research Letters, 44: 209-218.

Examples

data(example_lake)

# With user-provided depth
depth <- get_lake_depth(example_lake, user_depth = 8.5)

# Estimate from lake area
depth <- get_lake_depth(example_lake)

Get or Set lakefetch Package Options

Description

Get or set options that control the behavior of lakefetch functions.

Usage

lakefetch_options(...)

Arguments

Details

Available options:

buffer_distance_m

GPS accuracy buffer in meters (default: 10)

angle_resolution_deg

Direction resolution in degrees (default: 5)

max_fetch_m

Maximum fetch distance in meters (default: 50000)

validation_buffer_m

Shore detection validation buffer (default: 10)

default_wind_speed_ms

Default wind speed in m/s (default: 10)

default_depth_m

Default water depth in meters (default: 10)

gps_tolerance_m

Buffer for matching sites to lakes (default: 100)

fetch_method

Effective fetch calculation method: "top3" (mean of 3 highest directional fetches, default), "max" (maximum directional fetch), or "cosine" (SPM/CERC cosine-weighted average across 9 radials at 6-degree intervals; see Shore Protection Manual, 1984)

exposure_sheltered_m

Fetch threshold below which sites are classified as "Sheltered" (default: 2500 m). This is a practical default; no universal standard exists in the literature. Adjust based on your study system.

exposure_exposed_m

Fetch threshold above which sites are classified as "Exposed" (default: 5000 m). Sites between thresholds are "Moderate". See Mason et al. (2018) for Great Lakes exposure mapping methodology.

exposure_relative_sheltered

Proportion of lake maximum fetch below which sites are classified as "Sheltered" in the relative exposure system (default: 0.25). Sites are classified relative to the lake's longest internal chord (maximum possible fetch).

exposure_relative_exposed

Proportion of lake maximum fetch above which sites are classified as "Exposed" in the relative exposure system (default: 0.50). Sites between thresholds are "Moderate".

use_parallel

Use parallel processing for multi-lake (default: TRUE)

use_nhd

Use NHD integration if available (default: TRUE)

Value

If no arguments, returns a list of all current options. If arguments provided, sets those options and returns invisible NULL.

References

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

Mason, L. A., Riseng, C. M., Laber, A. L., & Rutherford, E. S. (2018). Effective fetch and relative exposure index maps for the Laurentian Great Lakes. Scientific Data, 5, 180295.

Examples

# Get all options
lakefetch_options()

# Get specific option
lakefetch_options()$buffer_distance_m

# Set options
lakefetch_options(buffer_distance_m = 20, angle_resolution_deg = 10)

Reset lakefetch Options to Defaults

Description

Reset all lakefetch package options to their default values.

Usage

lakefetch_reset_options()

Value

Invisible NULL

Examples

lakefetch_reset_options()

Load Sites from CSV or Data Frame

Description

Load and validate site data for fetch calculation. Automatically detects coordinate columns (latitude/longitude) and cleans the data.

Usage

load_sites(x, lat_col = NULL, lon_col = NULL, site_col = NULL, lake_col = NULL)

Arguments

Details

The function:

• Detects latitude/longitude columns (names starting with "lat"/"lon")

• Cleans coordinate values (removes non-numeric characters)

• Creates Site column if not present

• Removes rows with invalid or missing coordinates

• Detects location name from data columns or filename

Column names can be specified explicitly using the lat_col, lon_col, site_col, and lake_col arguments. This is useful when your data uses non-standard column names that the auto-detection cannot find.

Value

A data.frame with columns Site, latitude, longitude, and any additional columns from the input. Includes attributes "location_name" and "location_column" if a location was detected.

Examples

# Load from data frame
df <- data.frame(
  Site = c("A", "B", "C"),
  latitude = c(43.42, 43.43, 43.41),
  longitude = c(-73.69, -73.68, -73.70)
)
sites <- load_sites(df)

# Load with custom column names
df2 <- data.frame(
  sample_id = c("A", "B"),
  y_coord = c(43.42, 43.43),
  x_coord = c(-73.69, -73.68),
  reservoir = c("Lake One", "Lake One")
)
sites <- load_sites(df2, lat_col = "y_coord", lon_col = "x_coord",
                    site_col = "sample_id", lake_col = "reservoir")

Plot Fetch Bar Chart

Description

Create a bar chart showing effective fetch by site.

Usage

plot_fetch_bars(fetch_data, title = "Effective Fetch by Site")

Arguments

Value

A ggplot2 object

Examples

csv_path <- system.file("extdata", "sample_sites.csv", package = "lakefetch")
sites <- load_sites(csv_path)
lake <- get_lake_boundary(sites)
results <- fetch_calculate(sites, lake)
plot_fetch_bars(results)

Plot Fetch Map

Description

Create a map showing site locations colored by exposure category.

Usage

plot_fetch_map(fetch_data, title = "Fetch Analysis - Site Locations")

Arguments

Value

A ggplot2 object

Examples

# Use the bundled example lake (Blue Mountain Lake, NY) and the
# matching sample sites to compute and plot fetch offline.
data(example_lake)
sites_df <- load_sites(system.file("extdata", "sample_sites.csv",
                                    package = "lakefetch"))
sites_sf <- sf::st_transform(
  sf::st_as_sf(sites_df,
               coords = c("longitude", "latitude"), crs = 4326,
               remove = FALSE),
  sf::st_crs(example_lake)
)
lake_data <- list(all_lakes = example_lake,
                  sites = sites_sf,
                  utm_epsg = sf::st_crs(example_lake)$epsg)
results <- fetch_calculate(sites_df, lake_data, add_context = FALSE)
plot_fetch_map(results)

Plot Fetch Rose Diagram

Description

Create a rose diagram showing directional fetch for a single site.

Usage

plot_fetch_rose(fetch_data, site, title = NULL)

Arguments

Value

Invisible NULL (creates base R plot)

Examples

# Compute fetch offline against the bundled Blue Mountain Lake polygon.
data(example_lake)
sites_df <- load_sites(system.file("extdata", "sample_sites.csv",
                                    package = "lakefetch"))
sites_sf <- sf::st_transform(
  sf::st_as_sf(sites_df,
               coords = c("longitude", "latitude"), crs = 4326,
               remove = FALSE),
  sf::st_crs(example_lake)
)
lake_data <- list(all_lakes = example_lake,
                  sites = sites_sf,
                  utm_epsg = sf::st_crs(example_lake)$epsg)
results <- fetch_calculate(sites_df, lake_data, add_context = FALSE)
plot_fetch_rose(results, 1)

Sanitize a String for Use in Filenames

Description

Remove or replace invalid filename characters.

Usage

sanitize_filename(name)

Arguments

Value

A sanitized string safe for use as a filename

Examples

sanitize_filename("Lake O'Brien (2024)")

Wisconsin Lake Sampling Sites

Description

A dataset containing example sampling sites from well-known Wisconsin lakes. These coordinates are useful for testing with real lake boundaries from OpenStreetMap.

Usage

wisconsin_lakes

Format

A data frame with 8 rows and 4 variables:

Site

Unique site identifier

lake.name

Name of the lake

latitude

Latitude in decimal degrees (WGS84)

longitude

Longitude in decimal degrees (WGS84)

Details

The dataset includes sites from three Wisconsin lakes:

• Lake Mendota (3 sites) - Madison's largest lake, well-studied

• Lake Monona (2 sites) - Connected to Mendota via Yahara River

• Geneva Lake (3 sites) - Popular recreational lake in SE Wisconsin

Source

Synthetic data based on real lake locations

Examples

# Load the dataset
data(wisconsin_lakes)

# View the data
head(wisconsin_lakes)


# Use with lakefetch (requires internet connection)
sites <- load_sites(wisconsin_lakes)
lake_data <- get_lake_boundary(sites)
results <- fetch_calculate(sites, lake_data)