example_aoi.gpkg was built with two flooded defects: the bankfull units error (#49) and the channel_width field default (#47) #46

Problem

inst/extdata/example_aoi.gpkg — the Neexdzii Kwa floodplain AOI both vignettes analyse — was
generated by data-raw/example_aoi.R:86:

valleys <- flooded::fl_valley_confine(dem, streams)

That call takes both flooded defaults, and each is a known defect:

1. The bankfull units defect (NewGraphEnvironment/flooded#49, fixed in 0.5.0).
fl_flood_surface() fed hectares and millimetres into Hall et al. (2007) coefficients that take
km² and cm/yr, so bankfull depth was 3.5926x too large. The default flood_factor = 6 was
really 21.56x bankfull depth.

2. The field default (NewGraphEnvironment/flooded#47, still open).
field defaults to "channel_width", but the flood model reads the rasterized values as the
drainage-area term of the regression. So this AOI was built feeding channel width (4–31 m on
the bundled data) where upstream area in hectares was expected. Every documented caller passes
field = "upstream_area_ha" explicitly; this script does not.

The two compound: with the units fix, that channel-width value is now also divided by 100.

precip is unaffected — the script never passed it, the old default of 1 dropped the
precipitation term, and the new NULL default drops it the same way.

What this means

The shipped AOI is not the floodplain it is described as, and its extent will change once
regenerated. Both vignettes read it:

• vignettes/land-cover-change.Rmd:39
• vignettes/trajectory-break-detection.Rmd

Land-cover proportions within the AOI are the stable kind of claim — measured on
restoration_wedzin_kwa_2024, disturbed-as-a-share-of-AOI moved 27.51% → 27.50% under the units
fix, because the over-mapped margin carried almost the same mix as the core. Absolute hectares,
patch counts and the AOI polygon itself are not stable. Anything the vignettes state in hectares
or in feature counts will move.

I have not measured the magnitude for this AOI — it depends on the terrain and on which criterion
binds, and the field defect makes it not a simple scaling in either direction. It needs a re-run,
not an adjustment.

What to do

• Bump flooded to >= 0.5.0
• Pass field = "upstream_area_ha" explicitly in data-raw/example_aoi.R — do not wait on
  flooded#47, since the correct call site fix is one argument
• Consider passing precip too; omitting it underestimates flood depth by ~2.4x, and the
  streams query already pulls the network that carries map_upstream
• Regenerate inst/extdata/example_aoi.gpkg
• Re-render both vignettes and check any hectare or count figure in the prose
• Record before/after AOI area so the change is auditable
• Re-pin every test that hardcodes a bundled-tile number — the rasters are masked to the AOI in data-raw/example_aoi.R:157, so all of these move: test-dft_transition_vectors.R:189-192 (185 patches, 123.11 ha, 57 at patch_area_min = 1000) and test-dft_transition_artifact.R:279-284 and the survivor test below it (93 change patches, 75 under 1.5 px, one 0.75 ha / 1.44 px Trees -> Rangeland sliver surviving 5,000 m²). The _snaps/dft_rast_transition.md golden too. Re-pin from the regenerated data deliberately, and check the land-cover vignette's Geometric Artifacts prose, which states "0.75 ha" and "under 1.5 px" for that survivor in words (added 2026-09-05)

Why it went unnoticed

Same reason it did in flooded: nothing errors. A channel width is a plausible positive number
raised to the 0.280 power, and an over-deep flood surface produces a floodplain that looks entirely
reasonable. flooded 0.5.0 adds a units guard pinned to hard literals — there was no test anywhere
in that package pinning an absolute value before now, which is why a 3.59x error survived a green
suite for the whole life of the package.

Upstream: NewGraphEnvironment/flooded#49 (fixed), NewGraphEnvironment/flooded#47 (open).