Measure what a partially DEM-covered footprint costs, and report dem_elev_sd (#58)

[NewGraphEnvironment]

Measures what a partially DEM-covered footprint costs, and ships one new column. Closes #58.

What the measurement found

11,520 truncations of 120 real frames, cut from eight directions at eight depths by two mechanisms, each compared against that frame's own full-coverage answer.

The error is exactly the elevation bias over the height above ground. Realised width error equals Δelev / height_agl to 1.6e-13 over 10,248 runs, so the pipeline adds nothing measurable of its own and the result is terrain statistics rather than a property of this code.

Against MRDEM-30 — the DEM the package documents as its default — partial coverage is all but absent.

population	n	could reach nodata	DEM-sized	under 0.95
film, DEM-eligible	1,437,147	113	87	66 (0.005%)
digital	223,667	173	6	0
random film control	3,000	—	2,975	0

The issue's own figure does not reproduce. #58 reports 18 of 416 frames under 95% from the #50 run; nothing in the catalogue's digital population is partially covered by MRDEM-30. The likely explanation is a DEM cropped to that run's AOI — which is the failure the documentation already calls the ordinary one — but that is inference, and the run left no artifact to check. So the frequency is a property of how a caller crops, not of the catalogue, and the decision below rests on cost rather than rate.

Three of the four possible remedies were refused

Each by a rule fixed before the numbers existed.

No fallback floor. No coverage band exists where the DEM route is worse than the nominal scale it replaced, in the median. Below 20% coverage it is still better by nearly four times (1.49% against 5.76%), though worse on 15% of individual runs there.

fly_dem_coverage_min() stays at 0.95 — but its justification changes from "reprojection slivers" to measurement. The worst linear error at or above 0.95 is 0.794%, still 0.794% at 0.94, and first passes 1% at 0.92. One percent of width is about two percent of area, which is what the terrain note records as the cost of the per-corner ray-casting this model defers — so 0.95 is very nearly where a truncated frame's worst case stops being cheaper than an error already accepted in every frame. It is not moved down despite the median staying under 0.05% to 0.8, because the warning's own remedy (buffer by half_side * sqrt(2)) is correct at every coverage.

A calibrated error bound is not shipped. 4.97 * dem_elev_sd * (1 - dem_coverage) / height_agl covers 95.3% of held-out runs, fitted on the training third alone — but it is a median 6.1 times the actual error and holds on only 89.4% of runs below half coverage, which is where a caller would want it.

What did ship: two columns, and the second is the actionable one

dem_shortfall_m — the window you need

Everything the sweep measures describes the damage. None of it tells a caller what to do, and the population result says that is the gap that matters: against a remote MRDEM read this reaches 66 frames in 1.44 million, so in practice it is a DEM cropped to an AOI that is too small. The remedy is a bigger crop, not a better statistic.

On one frame: dem_coverage 0.253, dem_elev_sd 94.1 m — and dem_shortfall_m 3,822 m. max(fp$dem_shortfall_m) is the buffer that would contain the whole batch.

0 is an answer, not an absence. Partial coverage has two causes dem_coverage reports identically:

cause	dem_shortfall_m	remedy
the DEM's extent stops short of the frame	> 0	re-crop by that much; recovered exactly
nodata inside an extent that already spans it	0	none — no re-crop reaches it

The warning now names which one you have. Against a remote MRDEM read the shortfall is always 0, because the window is fetched per frame.

Three things this cost getting right: it is computed on the rectangle the caller receives, not the one the second pass sampled (those differed by 6.4 m on 3,822 m — the kind of near-miss that makes a figure impossible to check against the object in hand); a geographic DEM measures the gap in degrees, which unconverted reads 0.010 where the answer is a kilometre, so it has its own test pinning that three-orders-of-magnitude failure; and an automatic top-up from MRDEM was rejected, because it partially ignores a documented argument and reaches the network without being asked.

dem_elev_sd — for the gaps you cannot re-crop

At a fixed dem_coverage the measured error spans 13 to 52 times between frames, and nothing on the row separated them — 47% covered over a plateau costs nothing, 80% across a valley wall costs a lot, exactly as the issue argued. Frames above their band's median spread sit 2.3 to 4.1 times further from the full-coverage answer than those below.

The predictor had to be computable from the cells the DEM actually read, because that is all production has — a relief figure from the full window predicts well and could never be reported. Pooled, it barely beats coverage (0.80 against 0.72), and on that alone no column would have shipped. Pooling is the wrong comparison: coverage dominates it, and the question is what remains once coverage is known.

Reproducibility

data-raw/dem_calibrate-coverage_error.R reproduces everything from public data (BC Data Catalogue + MRDEM-30). inst/extdata/dem_coverage_{sweep,targets,population}.csv ship, and the suite parses all eight of the note's tables and recomputes every cell at the precision each figure is printed to, with the table count asserted so a ninth cannot be added unchecked. Each of the eight reddens on a planted wrong value.

Review

Four /code-check rounds, ~1.5M subagent tokens — past the usual bound, and worth naming. Rounds 2, 3 and 4 each found a defect inside the previous round's fix; the loop terminated on an enumeration, not a quiet round. Findings are archived in planning/archive/2026-09-issue-58-dem-coverage-cost/review-round[1-4].md.

Three worth reading:

• A feasibility-probe figure reached the note as a measurement. "A 0.30 target comes back as 0.215 achieved" was the two-frame probe's parameterisation quoted as the sweep's. This issue's own findings file says those numbers must not reach the note; one did, and survived two rounds. Measured, a 0.30 share gives median achieved coverage 0.699.
• Two numbers were wrong in the direction that flattered the column that shipped — the within-band rho range and the count of bands where covered_sd wins. Both were its justification, and neither had a producer line or a test.
• Each robustness arm computes its own reference, and the shipped table kept one row per frame, so arm errors were measured against the native one (ref_n 90,692 cells against 101).

Also: tolerance in testthat is relative, so at 2e-2 a three-decimal figure was pinned only to ±2% and 12.529% would have survived drifting to 12.629%.

What this is blind to

• Ocean. MRDEM returns a near-zero surface over near-shore water rather than nodata — 40,000 cells in Hecate Strait read 0.098 to 0.189 m, with no exact zeros. A coastal frame reports coverage near 1 while its mean is dragged toward sea level. Removing cells cannot generate it and dem_coverage cannot see it. Out of scope here, stated as a bound. Note the obvious guard — counting exact-zero cells — can never fire.
• The reference is each frame's own full-coverage answer, so this is a sensitivity measure (what buffering the DEM buys), not a ground-truth accuracy claim.
• Film only. A digital frame's DEM eligibility depends on camera_calibration_url and its scale is not an image scale, so it carries no second statement of height to anchor against.
• One target of 120 failed its premise and is excluded by name.

Verification

• FAIL 0 | WARN 0 | SKIP 0 | PASS 2114 (baseline 1852)
• pkgdown::check_pkgdown() clean; R CMD build clean, 1.58 MB, data-raw/ and planning/ correctly excluded
• Re-running the generator against unchanged inputs leaves git status clean

🤖 Generated with Claude Code

https://claude.ai/code/session_019MapqNGo4kVXGBuQNHqVdH