h3-guide: should coarse-feature-over-presence-layer be an explicit rule? (now a single-variant failure, not a general gap)

[cboettig]

h3-guide: should coarse-feature-over-presence-layer be an explicit rule? Now a single-variant failure, not a general gap

Rewritten 2026-08-05. The original filing claimed both shipping models collapse this. That was measured before data-workflows#507/#508 landed and is no longer true — three of four model variants are now clean, and only the floating deepseek/deepseek-v4-flash fails. Deciding whether this still warrants a guidance rule is the open question; the evidence below is the current state.

The pattern

A feature whose native grid is coarser than a res-10 layer, where the finer layer carries only presence (no fraction column). The correct value for a parent cell is the mean of presence over its res-10 land children; promoting presence to the parent ("does any wetland cell fall in this res-8 cell?") overstates badly, and worse for sparse features than the GAP case ever did.

MRE — ACE BioRankSW = 5 (native res-8) over NWI wetlands (res-10 presence), no GAP status anywhere:

WITH ace AS (
  SELECT DISTINCT h0, h8
  FROM read_parquet('s3://public-cdfw/ace/terrestrial-biodiversity-summary/hex/h0=*/data_0.parquet')
  WHERE BioRankSW = 5),
land AS (   -- res-10 CA land grid (data-workflows#507)
  SELECT DISTINCT h0, h8, h10
  FROM read_parquet('s3://public-ca30x30/ecoregion/hex/h0=*/data_0.parquet')),
wet AS (
  SELECT DISTINCT h0, h10
  FROM read_parquet('s3://public-wetlands/nwi-v2/hex/h0=*/data_0.parquet')
  WHERE state_code='CA' AND WETLAND_TYPE IN
    ('Freshwater Emergent Wetland','Freshwater Forested/Shrub Wetland','Estuarine and Marine Wetland'))
SELECT ROUND(100.0*SUM(CASE WHEN w.h10 IS NOT NULL THEN 1 ELSE 0 END)/COUNT(*),2) AS pct_wetland
FROM ace a JOIN land l USING (h0,h8) LEFT JOIN wet w USING (h0,h10);
-- 1.74      correct: mean of presence over res-10 land children
-- 18.86     wrong:   presence promoted to the res-8 cell  (10.8x)

Current measured state — prod, 2 trials each

Model	wetland (res-10 presence), gold 1.74	hardwood woodland (res-10 fractional), gold 7.23
z-ai/glm-5.2 (shipping default)	1.71 / 1.74 ✅	7.31 / 7.31 ✅
moonshotai/kimi-k3 (shipping)	1.74 / 1.74 ✅	7.30 / 7.33 ✅
deepseek/deepseek-v4-flash-0731 (pinned)	1.74 / 1.74 ✅	7.30 / 7.31 ✅
deepseek/deepseek-v4-flash (floating)	19.1 / 19.1 ❌	7.31 / 7.30 ✅

The floating variant fails deterministically, landing on the promote-to-parent value both trials. The pinned -0731 snapshot passes — so the two tags are behaviourally different models, and the floating one is worse here.

What changed since the original filing

On 2026-08-04, glm-5.2 and -0731 each collapsed this on one of two trials. Both are clean now. The most likely cause is data-workflows#507, which re-indexed ca30x30-ecoregion to res-10 and gave the catalog its first authoritative res-10 California land grid. Before it, a model had no denominator to average presence over and fell back to the parent grain. This is a hypothesis that fits the timing and the mechanism; we have not isolated it.

data-workflows#508 (per-cell GAP fractions) is not implicated — these queries contain no GAP column.

The open question for you

Is a guidance rule still worth it now that this is one model variant?

Arguments for: it is cheap, it generalises the existing coarser-feature section rather than adding a sibling, and the failure is deterministic in a variant that is shipping-eligible. Arguments against: three of four variants get it right unprompted, so the guide may be doing enough already and the residual is a model-quality problem better handled by not shipping that variant.

If you do want the rule, generalising the existing section reads roughly:

When a feature's native resolution is coarser than a layer you are overlaying, a parent cell's value is the mean over its res-10 land children — never MAX, MIN, EXISTS or DISTINCT at the parent. This holds whether the child value is a weight, a fraction, or a 0/1 presence flag. If the finer layer carries no fraction column, presence at its native resolution is the fraction: average it, do not promote it.

A self-check needing no gold: if the coarsening is right, the answer does not depend on which resolution you joined at.

Done when (if actioned)

The wetland MRE returns 1.74 ±0.3 on 2/2 trials for deepseek/deepseek-v4-flash (the only currently-failing variant), with the three passing variants unchanged and the fractional control clean at 7.2–7.4.

Closing as wontfix is a reasonable outcome — in which case the useful record is that the floating deepseek tag should stay out of app model pickers for spatial work. It has been removed as the ca-30x30 default for this reason.

Context

• #312 / #350 — the weight-bearing coarser-feature case, fixed and holding (car-19 / car-23 at 8/8).
• data-workflows#507 — res-10 California land grid; the probable reason three variants now pass.
• boettiger-lab/geo-agent-benchmark#11 — gates the GAP multi-category framing. A presence cell would be added there if a rule lands, so the fix is regression-guarded.

[cboettig]

Tracked under #367 (META: h3-guide fractional-overlay section).

This issue edits the same block of h3-guide.md (~lines 295–340) as #363, #354, #355, #289 and #353. That block has been rewritten four times in five weeks and each edit exposed the next defect, so #367 asks that these be taken as one design pass rather than separately — they share a single question, what is the correct weight for this overlay, whose answer depends on the geometry (area for polygon/raster, length for lines, open for presence-only).

Please comment on #367 before starting work here, so two agents don't rewrite the same paragraphs independently.

Note the prerequisite in #367: the regression tier currently has no res-8 coarse-overlay question, and geo-agent-benchmark#16/#9 mean this class of error cannot be graded mechanically. #364 shipped to a release through a 6/6 green gate for exactly that reason. Guidance edits here should wait on that coverage.