Getting Started with lakefetch

Installation

install.packages("lakefetch")

# Optional packages for extra features:
# install.packages("nhdplusTools")                      # NHD integration
# install.packages(c("shiny", "leaflet", "base64enc"))  # Interactive app

Quick Start

1. Load your site data

library(lakefetch)

# From CSV file
sites <- load_sites("my_lake_sites.csv")

# Or create manually
sites <- data.frame(
  Site = c("Site_A", "Site_B", "Site_C"),
  latitude = c(43.42, 43.43, 43.41),
  longitude = c(-73.69, -73.68, -73.70)
)
sites <- load_sites(sites)

Your CSV should have columns for site names and coordinates. Column names starting with “lat” and “lon” are automatically detected.

2. Get lake boundary

# Automatically download from OpenStreetMap
lake <- get_lake_boundary(sites)

# Or load from a local shapefile
lake <- get_lake_boundary(sites, file = "lake_boundary.shp")

3. Calculate fetch

results <- fetch_calculate(sites, lake)

# View results
head(results$results)

4. Visualize

# Map of sites
plot_fetch_map(results)

# Bar chart
plot_fetch_bars(results)

# Interactive app
fetch_app(results)

Understanding the Results

The fetch_calculate() function returns a list containing:

results: An sf object with one row per site, containing:
- fetch_0, fetch_5, …, fetch_355: Fetch distance in each direction (meters)
- fetch_mean: Average fetch across all directions
- fetch_max: Maximum fetch (longest open water distance)
- fetch_effective: Mean of the three longest fetch values
- orbital_effective: Estimated wave orbital velocity (m/s)
- exposure_category: Classification as “Sheltered”, “Moderate”, or “Exposed”
lakes: The lake polygon(s) used for calculation
angles: The angles (in degrees) used for ray-casting

Exposure Categories

Sites are classified based on effective fetch:

Category	Effective Fetch	Typical Conditions
Sheltered	< 2.5 km	Protected bays, minimal wave action
Moderate	2.5 - 5 km	Some wave exposure, mixed conditions
Exposed	> 5 km	Open water, significant wave energy

Configuration Options

Customize the calculation parameters:

# View current options
lakefetch_options()

# Change options
lakefetch_options(
  buffer_distance_m = 20,      # GPS accuracy buffer
  angle_resolution_deg = 10,   # Direction resolution (degrees)
  max_fetch_m = 30000,         # Maximum fetch distance
  use_parallel = TRUE          # Parallel processing for multiple lakes
)

# Reset to defaults
lakefetch_reset_options()

NHD Integration

If the nhdplusTools package is installed, lakefetch can add hydrological context from the National Hydrography Dataset: - Lake outlet and inlet locations - Distance and direction to outlet/inlets from each site - Connectivity classification (Headwater, Drainage, Terminal, Isolated) - Outlet stream order - Watershed area

# NHD context is added automatically if available
results <- fetch_calculate(sites, lake, add_context = TRUE)

# Check connectivity
table(results$results$connectivity_class)

Working with Multiple Lakes

If your sites span multiple lakes, lakefetch handles this automatically:

# Sites are assigned to their containing lake polygon
sites_with_lakes <- assign_sites_to_lakes(lake$sites, lake$all_lakes)

# Check assignment
table(sites_with_lakes$lake_name)

Exporting Results

# To CSV (without geometry)
write.csv(sf::st_drop_geometry(results$results),
          "fetch_results.csv", row.names = FALSE)

# To GeoPackage (with geometry)
sf::st_write(results$results, "fetch_results.gpkg")

# Export ray geometries for GIS
rays <- create_ray_geometries(results)
sf::st_write(rays, "fetch_rays.gpkg")