Geovalidity: strict country equality cannot tell a mislabelled record from a mislocated one

[bmaitner]

Summary

The current-country test in gvs_geovalidity() (R/GVS_local.R, merged to main in #2) is strict equality: a record is geovalid only if the GADM country its coordinate falls in equals its declared country. That catches coordinate errors, but it also rejects records whose coordinates are correct and whose country label is wrong. The two failure modes need different treatment, and telling them apart needs its own algorithm.

For now the strict test is being kept deliberately (it matches BIEN's is_geovalid semantics). This issue records the evidence and the candidate approaches so it can be designed properly later.

Evidence

From the garden-variety-traits occurrence pipeline, using the offline GVS raster index (GADM 4.1, 30 arc-seconds), on 37,252,096 GBIF records from 5 of 64 species buckets:

	records	share
flagged by the strict GADM test	102,477	0.275%
flagged by GBIF's own COUNTRY_COORDINATE_MISMATCH	34,858	0.094%
both	14,715
strict test only	87,762
GBIF only	20,143

The strict test flags about 2.9 times as many records as GBIF. The excess is not noise. The twelve most frequent strict-only pairs (declared country, then the country the coordinate falls in) are all neighbouring countries, and together they account for 83.5% of the excess:

declared	located	records
NLD	BEL	28,583
DEU	AUT	10,903
ISR	PSE	7,401
ESP	FRA	6,190
NLD	DEU	5,394
FRA	ITA	2,626
HKG	CHN	2,572
FRA	CHE	2,568
DEU	CZE	2,122
DEU	FRA	2,049
ESP	AND	1,511
FRA	ESP	1,380

This is the signature of correct coordinates carrying a loose country label, for example a platform's or observer's country attached to a cross-border observation, rather than of coordinate errors. Swapped or negated coordinates usually land far from the declared country, often on another continent. Strict equality therefore discards valid data, concentrated in some of the best-sampled regions.

Related observations

• Boundary cells. Raster-only location (gpkg = NULL) cannot verify the country of a point in a boundary cell: gvs_locate_current() reports "raster (boundary cell, not verified)". About 21% of records fall on a GADM level-2 boundary cell, although most of those are internal county borders where the country is not in doubt.
• Different boundaries. GBIF flags 6,912 records that the GADM lookup places inside the declared country, presumably because GBIF uses different boundary data.
• Non-ISO3 GADM codes. GADM has 16 gid_0 codes that are not ISO3: the disputed Kashmir zones Z01 to Z09 (attributed to India, China or Pakistan), ZNC Northern Cyprus, XKO Kosovo, XAD Akrotiri and Dhekelia, XSP and XPI (Spratly and Paracel Islands), XCL Clipperton and XCA Caspian Sea. Without explicit handling, every record declared India that falls in a Kashmir zone would be flagged. The pipeline currently treats these codes as untestable.
• Circular declarations. GBIF sometimes fills the country in from the coordinates (COUNTRY_DERIVED_FROM_COORDINATES, about 0.73% of records). Testing such a country against the same coordinate is circular, so these records should be treated as untestable, not valid.

Candidate approaches (not decided)

1. Adjacency exemption. Flag a record only when the located country is neither the declared country nor one of its neighbours. It needs no geometry, since a neighbours table can be derived from the existing index raster, but it is also lenient toward points deep inside a neighbouring country.
2. Distance tolerance. Flag a record only when it lies more than X km from the declared country. More precise, but it needs GADM geometry and exact distances.
3. Dataset-level diagnosis. A dataset whose mismatches point systematically at one neighbour is probably mislabelled rather than mis-georeferenced. This has the strongest principled basis, but needs dataset keys the service does not currently receive.
4. Exact point-in-polygon for boundary-cell mismatches only. The subset is small, so this is cheap even with the geopackage, and it removes the raster ambiguity whichever of the above is chosen.

Whatever is chosen should probably return why a record failed (mislocated, mislabelled, unverifiable), not just a boolean, so that users can choose their own tolerance.

[bmaitner]

Following up with what the evidence turned out to be, and what has been built.

The excess was not loose labels alone

Extending the test below country level made the cause visible. Of the sub-national mismatches, 70% came from three countries, and the declared divisions say why:

	share of sub-national mismatches	what records actually declare
Sweden	36.0%	landskap and lappmarker (Uppland, Småland, Västergötland, Lule lappmark), not län
Britain	28.3%	Watsonian vice-counties, written VC57 Derbyshire, not GADM districts
Norway	3.3%	counties from the 2018 and 2020 reforms (Viken, Innlandet, Vestland, Trøndelag); GADM 4.1 still carries the pre-2018 ones

94.3% of state-level mismatches were within a single country. These are correctly georeferenced records, correctly labelled in their own system — the declared division simply is not a GADM division. Matching such a name to the nearest-looking GADM unit and then failing the coordinate against it mislabelled 19.8M records as geo-invalid.

So the distinction this issue asks for is not only mislocated versus mislabelled. There is a third case, and it is the largest: the declared division belongs to another division system.

What was built

GNRS now carries an altdiv component — units, their names, and their extent as the set of GADM units they cover — alongside the historical divisions it already models, since this is the same kind of object: a named place that is not a current GADM unit but has a known geography. Resolution consults it between the exact match on a GADM unit's own names and the match on its alternate names, which is the precedence the data calls for: Skåne is both a landskap and a län and stays the län, while Uppland stops being matched to Uppsala län.

gvs_geovalidity() then checks the coordinate against that extent:

• extent known → the point must fall in one of those units. Norway is fully covered this way, and real errors are still caught: a record saying Viken at Oslo's coordinates is invalid, because Oslo is not one of the three counties Viken covers.
• extent not known yet → unverifiable, never invalid. Swedish landskap and vice-counties are here for now; Alternative divisions: source extents for Swedish landskap and lappmarker and for Watsonian vice-counties RGNRS#2 tracks sourcing their boundaries.

Superseded units carry their validity period, so Viken on a 2021 record is in period and on a 2025 record is not — it was dissolved on 2024-01-01.

What this leaves of the original issue

The neighbouring-country pattern at country level is untouched and still open: NLD → BEL 28,583 records, DEU → AUT 10,903, and the rest. Those are loose labels on correct coordinates, a different problem from a different division system, and the candidate approaches listed above still apply to it.

The boundary-cell point also still stands. At 30 arc-seconds a point in a boundary cell cannot be assigned to a division with confidence, and roughly a fifth of records sit in one; sub-national testing treats those as unverifiable, while the country-level test remains strict.