Inferring CRS from Retrieved Spatial Context

Retrieval gives you neighbours; it does not give you an answer. A handful of documents that mention the same place, each with its own coordinates and its own declared frame, have to be turned into one scored hypothesis about the reference system of the mention in hand. This guide sets out the four signals that do that work and how to combine them without manufacturing false confidence, as the scoring stage of retrieval-augmented CRS resolution.

When to Use This Approach

Use inference when a mention arrives with coordinates but no declared frame, and there is a corpus with enough overlap to supply evidence. Do not use it when the frame is declared — validate the declaration instead — and do not use it when the corpus covers a different region from the mention, where retrieved neighbours are noise wearing the clothes of evidence.

None of the four is decisive on its own, which is the whole difficulty. Magnitude narrows a registry of thousands to a few dozen; precision usually separates geographic from projected; agreement and provenance do the rest. A design that leans on any single one produces confident answers exactly where the evidence is weakest.

Implementation

The scorer takes a coordinate pair and a set of retrieved neighbours, applies the four signals in order, and returns a ranked list with an explicit rationale for each candidate.

import logging
import math
from collections import Counter
from dataclasses import dataclass
from typing import Sequence

from pyproj import CRS
from pyproj.exceptions import CRSError

log = logging.getLogger("crs_inference")


@dataclass(frozen=True)
class Neighbour:
    epsg: int
    declared: bool          # the source stated this frame, rather than it being assumed
    similarity: float       # retrieval score in [0, 1]


@dataclass(frozen=True)
class Hypothesis:
    epsg: int
    score: float
    rationale: str


def _looks_geographic(x: float, y: float, decimals: int) -> bool:
    """Degrees are small and precise; projected metres are large and blunt."""
    in_range = -180.0 <= x <= 180.0 and -90.0 <= y <= 90.0
    return in_range and decimals >= 4


def _magnitude_ok(epsg: int, x: float, y: float) -> bool:
    """Reject frames whose own axis ranges cannot hold these numbers."""
    try:
        crs = CRS.from_epsg(epsg)
    except CRSError:
        return False
    if crs.is_geographic:
        return -180.0 <= x <= 180.0 and -90.0 <= y <= 90.0
    # Projected frames: reject values no plausible grid uses.
    return abs(x) < 1.0e7 and abs(y) < 1.0e7 and (abs(x) > 1000.0 or abs(y) > 1000.0)


def infer_crs(
    x: float,
    y: float,
    decimals: int,
    neighbours: Sequence[Neighbour],
) -> list[Hypothesis]:
    """Rank candidate frames for an undeclared coordinate pair. Never raises."""
    if not all(math.isfinite(v) for v in (x, y)):
        log.warning("non-finite coordinate (%r, %r) — no hypothesis possible", x, y)
        return []

    geographic = _looks_geographic(x, y, decimals)
    counts = Counter(n.epsg for n in neighbours)
    declared = {n.epsg for n in neighbours if n.declared}
    best_sim = {n.epsg: 0.0 for n in neighbours}
    for n in neighbours:
        best_sim[n.epsg] = max(best_sim[n.epsg], n.similarity)

    out: list[Hypothesis] = []
    for epsg, count in counts.items():
        if not _magnitude_ok(epsg, x, y):
            continue                                   # magnitude gate: hard exclusion
        try:
            crs = CRS.from_epsg(epsg)
        except CRSError:
            continue
        if crs.is_geographic != geographic:
            continue                                   # precision gate: hard exclusion

        agreement = min(0.30, 0.10 * count)            # capped: three neighbours, then no more
        provenance = 0.35 if epsg in declared else 0.0
        similarity = 0.25 * best_sim[epsg]
        score = round(min(1.0, 0.10 + agreement + provenance + similarity), 3)
        reason = (f"{count} neighbour(s), "
                  f"{'declared' if provenance else 'assumed'} frame, "
                  f"{'geographic' if geographic else 'projected'} magnitudes")
        out.append(Hypothesis(epsg, score, reason))

    return sorted(out, key=lambda h: h.score, reverse=True)

The two gates are exclusions rather than penalties, and that asymmetry is deliberate. A frame whose axes cannot hold the numbers is not unlikely, it is impossible, and letting a strong provenance score outweigh an impossibility is how a pipeline produces answers that no amount of downstream validation can rescue.

The floor of 0.10 on the score means even the best-supported hypothesis tops out below the fallback threshold used in the parent topic unless it has both provenance and agreement. That is the intended behaviour: inference from context should rarely reach high confidence on its own, and a design where it usually does is one that has stopped distinguishing evidence from coincidence.

Validation & Testing

def test_impossible_frame_is_excluded_not_ranked_low():
    # Geographic-looking coordinates cannot belong to a projected grid.
    hyps = infer_crs(-3.19, 55.95, 6, [Neighbour(27700, True, 0.95)])
    assert all(h.epsg != 27700 for h in hyps)


def test_declared_provenance_outranks_bare_agreement():
    ns = [Neighbour(4326, True, 0.5), Neighbour(4258, False, 0.5), Neighbour(4258, False, 0.5)]
    top = infer_crs(-3.19, 55.95, 6, ns)[0]
    assert top.epsg == 4326


def test_no_neighbours_yields_no_hypothesis():
    assert infer_crs(-3.19, 55.95, 6, []) == []


def test_non_finite_input_returns_empty_not_raises():
    assert infer_crs(float("nan"), 55.95, 6, [Neighbour(4326, True, 1.0)]) == []

The second test encodes the ranking policy explicitly, which matters because it is the assertion that fails when someone raises the agreement cap to “make the scores more decisive”. The third is equally important and easy to omit: a scorer that returns a hypothesis with no evidence at all is worse than one that returns nothing, because the caller cannot tell the two apart from the shape of the result.

Gotchas & Edge Cases

Corpus bias masquerading as agreement. If nine tenths of the corpus uses one frame, neighbour agreement will favour it for every mention, including the ones that belong to something else. Cap the agreement contribution, as the code does, and consider normalising by the frame’s overall prevalence in the corpus so a common frame has to earn its lead.

Northing and easting confusion. A pair swapped at export looks like a plausible position in the same frame, and no signal here detects it. The check that does is geographic: transform to geographic coordinates and ask whether the result falls in the region the document is about. This is the same class of error covered in axis-order handling for declared frames.

Precision inflation from reprojection. A projected coordinate reprojected to degrees acquires many decimals that carry no real accuracy, so a document full of six-decimal degrees may be a reprojection of a metre-precision survey. The signal remains useful for typing the frame and should not be read as evidence about the data’s accuracy.

Frames that are equivalent in practice. Several codes describe datums that differ by centimetres, and choosing between them from retrieved context is not possible. Group such codes and return the group with a note, rather than picking one and implying a distinction the evidence cannot support.

Neighbours retrieved from the mention’s own document. Self-agreement is not evidence. Exclude neighbours that share a source identifier with the mention before counting, or a single document with a repeated frame will reliably reach the agreement cap on its own.

Frequently Asked Questions

Related

• Up to the parent topic: Retrieval-Augmented CRS Resolution
• Resolving Ambiguous EPSG Codes from Document Context
• Concept: Coordinate Reference System Normalization
• Technique: Detecting Axis-Order Swaps in Coordinate Input