Document VCA parameters with ecological rationale and default scenarios

[NewGraphEnvironment]

Problem

flooded's VCA (fl_valley_confine()) accepts many parameters that control floodplain delineation, but the package doesn't document what the parameter values mean ecologically or why specific defaults were chosen. Users must figure out on their own what flood_factor = 6 represents, why slope_threshold = 9, what cost_threshold = 2500 means physically, etc.

The full parameter set that shapes VCA output:

Parameter	Current default/usage	What it controls
flood_factor	varies (1-12)	Depth multiplier on bankfull — defines which ecological zone
slope_threshold	9	Valley wall cutoff (degrees)
max_width	2000	Maximum valley width (m)
cost_threshold	2500	Cost-distance limit for flood spread
size_threshold	5000	Minimum patch size (cells)
hole_threshold	2500	Fill holes smaller than this (cells)
min_order	3 (scenario-dependent)	Stream order filter for flood model
anchor_order	1	Stream order for patch connectivity
precip	from map_upstream	Mean annual precipitation raster — critical for bankfull regression

The rationale for these values is backed by hydrology/geomorphology literature (Beechie, Wheaton, Nagel, Rapp & Abbe, Hall, Zhang & Montgomery, etc.) and should live with the tool — not scattered across downstream project repos.

Proposed Solution

1. Ship a default scenario table in inst/flood_scenarios.csv — columns: scenario_id, flood_factor, min_order, anchor_order, ecological_process, description, citations
2. Document all VCA parameters with ecological rationale and literature backing — why these defaults? What happens when you change them?
3. Add fl_scenarios() — loads the default table, users can override/extend
4. Vignette with proper references covering the full parameter set

This is unusual for an R package but flooded is a scientific tool — the rationale IS the documentation. Anyone using VCA needs to understand what the parameters mean physically and ecologically.

Context

Currently working through this in restoration_wedzin_kwa_2024 (#123) where we're running 6 VCA scenarios at different flood_factors while holding other parameters constant. The literature review and parameter documentation should ultimately live upstream here in flooded.

Relates to NewGraphEnvironment/restoration_wedzin_kwa_2024#123

[NewGraphEnvironment]

flood_factor calibration: floodplain vs valley bottom

Our default ff=6 maps valley bottom (Nagel 2014's target), not functional floodplain. Key findings from source PDFs:

• Hall et al. 2007: ff=3 on 10m DEM = best fit for historical floodplain width (213 field sites)
• Nagel et al. 2014: ff=5-7 = valley bottom (wider than floodplain — includes terraces, depositional areas)
• Coarser DEMs need larger ff to compensate for smoothed valley floors (ff=7 for 30m, ff=5 for 10m)

For ecological restoration, "functional floodplain" (nutrient exchange, LWD recruitment, wetland function) is closer to Hall's historical floodplain than Nagel's full valley bottom.

Recommendation: ff=4-5 on 25m DEM for functional floodplain. ff=6 is defensible as "valley bottom extent" but should not be labelled "floodplain."

Empirical validation needed: run multiple ff values, compare against known features.

See restoration_wedzin_kwa_2024#138 for the report-side fix.

Relates to NewGraphEnvironment/restoration_wedzin_kwa_2024#123

[NewGraphEnvironment]

Updated scope (2026-03-19)

The original issue text is stale — corrections below.

Already shipped

• inst/extdata/flood_params.csv — parameter legend with units, defaults, citation keys, DEM resolution notes (Ship VCA parameter legend CSV with units, defaults, and literature sources #29, closed)
• inst/research/vca_parameter_rationale.md — full literature verification with verified quotes from Nagel 2014 and Hall 2007 (via ragnar semantic search against purchased PDFs)

Corrections to original issue

• slope_threshold is percent slope, not degrees (9% = ~5.1°)
• size_threshold and hole_threshold are m², not cells
• Flood_factor is a DEM compensation parameter, not an ecological threshold — no paper maps specific ff values to ecological processes

What remains for this issue

1. inst/extdata/flood_scenarios.csv — default scenario table (3 scenarios: ff02, ff04, ff06)
2. fl_scenarios() — loads scenario CSV, users can override with custom path
3. fl_params() — loads parameter legend CSV
4. Tests for both functions

Approach

• Branch from main
• Use planning-with-files
• Read inst/research/vca_parameter_rationale.md and inst/extdata/flood_params.csv first — all the research is there
• Close this issue with the commit
• File a separate issue for the vignette (prove the functions work with a worked example)

See implementation prompt in next comment.

[NewGraphEnvironment]

Implementation prompt

Branch, use planning-with-files, then build:

Read first:

• inst/research/vca_parameter_rationale.md — full literature verification with quotes
• inst/extdata/flood_params.csv — parameter legend (already shipped via Ship VCA parameter legend CSV with units, defaults, and literature sources #29)
• R/fl_valley_confine.R — current function parameters

Build:

1. inst/extdata/flood_scenarios.csv with columns: scenario_id, flood_factor, slope_threshold, max_width, cost_threshold, size_threshold, hole_threshold, run, description, ecological_process, citation_keys. Three core scenarios:

   • ff02 (ff=2) — Flood-prone width / active channel margin
   • ff04 (ff=4) — Functional floodplain
   • ff06 (ff=6) — Valley bottom extent
   • Non-flood_factor params use defaults from flood_params.csv
   • run column (TRUE/FALSE) so consuming projects can document all scenarios but only run selected ones

2. fl_scenarios(path = NULL) — loads default CSV from inst/extdata/flood_scenarios.csv. When path is provided, reads user's custom CSV instead. Returns tibble.

3. fl_params(path = NULL) — loads inst/extdata/flood_params.csv. When path is provided, reads user's custom CSV. Returns tibble.

Key context for roxygen:

• flood_factor is a DEM compensation parameter, NOT an ecological threshold. No paper maps specific ff values to ecological processes. The zone framework is an interpretive overlay.
• DEM resolution matters: ff=3 = historical floodplain on 10m DEM (@hall_etal2007Predictingriver). At 25m need ~ff=4. At 1m LiDAR ff=2-3 may suffice. At 30m need ff=7 (@nagel_etal2014LandscapeScale).
• size_threshold and hole_threshold need to be much smaller at 1m LiDAR (roads are ~10m wide). Users add rows with different params for site-level work.

Tests: fl_scenarios() returns tibble with expected columns. fl_params() likewise. Custom path override works. Invalid path errors cleanly.

Don't: modify fl_valley_confine(), add vignette (separate issue), bump version.

Close this issue with Fixes #28. File new issue for vignette afterward.