spatial-data-foundation 0.1.0__py3-none-any.whl

spatial_data_foundation-0.1.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: spatial-data-foundation
+Version: 0.1.0
+Summary: Reusable geography, time, provenance and spatial-membership infrastructure for empirical research
+Requires-Python: >=3.10
+Requires-Dist: empirical-data-contracts<0.2,>=0.1
+Requires-Dist: geopandas>=0.14
+Requires-Dist: shapely>=2
+Requires-Dist: pyproj>=3.5
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: io
+Requires-Dist: pyarrow>=15; extra == "io"
+Requires-Dist: duckdb>=1.0; extra == "io"
+Provides-Extra: raster
+Requires-Dist: rasterio>=1.3; extra == "raster"
+Provides-Extra: cli
+Requires-Dist: typer>=0.12; extra == "cli"
+Provides-Extra: presentation
+Requires-Dist: matplotlib>=3.8; extra == "presentation"
+Requires-Dist: contextily<2,>=1.7.1; extra == "presentation"
+Requires-Dist: xyzservices<2027,>=2026.3; extra == "presentation"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pyarrow>=15; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: matplotlib>=3.8; extra == "dev"
+Requires-Dist: contextily<2,>=1.7.1; extra == "dev"
+Requires-Dist: xyzservices<2027,>=2026.3; extra == "dev"

spatial_data_foundation-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+spatial_foundation/__init__.py,sha256=GRmq8A_bqovaHHE21ATVDhiDXsII8VctSClcS3B5Rh4,456
+spatial_foundation/catalog.py,sha256=53WUvgza-bOuPMcK0qg8riCJW_HhuSeM1HTeOp_QHhM,1794
+spatial_foundation/periods.py,sha256=dYqwonfGY9mFjcRaIYDZ-OPy_hOZlmr2hiPoO5T5DKs,1568
+spatial_foundation/geography/__init__.py,sha256=npTzZR_375PyzYnw_tAS5AXst0wN0wshy6UgEpzQBto,576
+spatial_foundation/geography/gadm.py,sha256=ppmEjdcjLTXFZ8Uh0jU9j-zyhok6VTgQdVZhdZHIuIg,3388
+spatial_foundation/geography/materialize.py,sha256=BgFWJZmYUgkbX-Sos4bzFxLw706MsuuPexGZOziNJNA,15447
+spatial_foundation/geography/membership.py,sha256=UddRKWwesOrxCoepsocw3jkZIsaQ2kAtKRobSpYhzKI,2954
+spatial_foundation/geography/models.py,sha256=qdDWCygh3bk8zH4GYPas06Wao8J5BeEu2sb2V-JJkBw,991
+spatial_foundation/geography/overlap.py,sha256=6aUmSc4hzg-KJmUND5nMpptojPkOoU3yFIMnorcYe50,7360
+spatial_foundation/presentation/__init__.py,sha256=bRN9F32Xyi20HYH0uLNLfJq36M0CPEHljRQ4i6BLlLs,239
+spatial_foundation/presentation/basemaps.py,sha256=8jP7NcUrtfT_LnUig3Onz1GetC6QxrvLbDa35rCqcvE,2785
+spatial_foundation/presentation/plotting.py,sha256=3_moU3OPdKf_E2dxFdLOYnb6LFaxqC8Ix2l22allhuw,786
+spatial_data_foundation-0.1.0.dist-info/METADATA,sha256=uDVIezdAnH5pO6NgFP-3hGFnKK3b_a8BUVE6FzP4j_0,1156
+spatial_data_foundation-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+spatial_data_foundation-0.1.0.dist-info/top_level.txt,sha256=96_8oHgbT_BKvhDHctnGy-57j29d1FMC5uOvEaJ_j8s,19
+spatial_data_foundation-0.1.0.dist-info/RECORD,,

spatial_data_foundation-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spatial_data_foundation-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spatial_foundation

spatial_foundation/__init__.py

@@ -0,0 +1,20 @@
+from .catalog import DataRoot, register_external_snapshot, sha256_file
+from .geography import (
+    ArealOverlapAudit,
+    GADMMaterialization,
+    materialize_gadm,
+    relate_areal_objects,
+)
+from .periods import Period, PeriodIndex
+
+__all__ = [
+    "ArealOverlapAudit",
+    "DataRoot",
+    "GADMMaterialization",
+    "Period",
+    "PeriodIndex",
+    "materialize_gadm",
+    "register_external_snapshot",
+    "relate_areal_objects",
+    "sha256_file",
+]

spatial_foundation/catalog.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+
+from empirical_contracts import SourceFileRef, SourceSnapshotRef
+
+
+@dataclass(frozen=True)
+class DataRoot:
+    root: Path
+
+    @classmethod
+    def from_path(cls, value: str | Path) -> DataRoot:
+        return cls(Path(value).expanduser().resolve())
+
+    def bronze(self, source: str, release: str, snapshot_id: str) -> Path:
+        return self.root / "bronze" / source / release / snapshot_id
+
+    def silver(self, domain: str, dataset: str, version: str) -> Path:
+        return self.root / "silver" / domain / dataset / version
+
+    def gold(self, domain: str, dataset: str, version: str) -> Path:
+        return self.root / "gold" / domain / dataset / version
+
+    def run(self, package: str, run_id: str) -> Path:
+        return self.root / "runs" / package / run_id
+
+
+def sha256_file(path: str | Path, chunk_size: int = 1024 * 1024) -> str:
+    digest = sha256()
+    with Path(path).open("rb") as handle:
+        while chunk := handle.read(chunk_size):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def register_external_snapshot(source: str, release: str, paths: list[str | Path]) -> SourceSnapshotRef:
+    resolved_paths = sorted(Path(raw).expanduser().resolve() for raw in paths)
+    refs = []
+    for path in resolved_paths:
+        stat = path.stat()
+        refs.append(SourceFileRef(path=str(path), sha256=sha256_file(path), size_bytes=stat.st_size))
+    short = sha256("".join(ref.sha256 for ref in refs).encode()).hexdigest()[:12]
+    return SourceSnapshotRef(
+        source=source,
+        release=release,
+        snapshot_id=f"{source}-{release}-{short}",
+        storage_mode="external_immutable",
+        files=tuple(refs),
+    )

spatial_foundation/geography/__init__.py

@@ -0,0 +1,19 @@
+from .gadm import normalize_gadm_frame
+from .materialize import GADMMaterialization, materialize_gadm
+from .membership import MembershipAudit, assign_points
+from .models import GeographyUnit, GeometryRole, MembershipStatus, geography_uid
+from .overlap import ArealOverlapAudit, relate_areal_objects
+
+__all__ = [
+    "ArealOverlapAudit",
+    "GADMMaterialization",
+    "GeographyUnit",
+    "GeometryRole",
+    "MembershipAudit",
+    "MembershipStatus",
+    "assign_points",
+    "geography_uid",
+    "materialize_gadm",
+    "normalize_gadm_frame",
+    "relate_areal_objects",
+]

spatial_foundation/geography/gadm.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import geopandas as gpd
+
+from .models import GeometryRole, geography_uid
+
+REQUIRED_BASE = {"GID_0"}
+
+
+def _require_identity(series, *, label: str):
+    missing = series.isna() | series.astype("string").str.strip().eq("")
+    if missing.any():
+        raise ValueError(f"GADM {label} is not resolvable for {int(missing.sum())} row(s)")
+    return series.astype(str)
+
+
+def normalize_gadm_frame(
+    frame: gpd.GeoDataFrame,
+    *,
+    version: str,
+    level: int,
+    area_crs: str = "EPSG:6933",
+) -> gpd.GeoDataFrame:
+    """Normalize one native GADM level without simplifying analytical geometry.
+
+    Expected source fields are GID_0 .. GID_{level}. Parent identity is retained when
+    available. Geometry is stored in EPSG:4326; area is calculated in the declared
+    equal-area CRS. The returned frame records the area CRS and geometry validity
+    profile in ``GeoDataFrame.attrs`` for run-manifest/provenance capture.
+    """
+    if level < 0:
+        raise ValueError("GADM admin level must be >= 0")
+    if not version.strip():
+        raise ValueError("GADM version must be non-empty")
+
+    gid_col = f"GID_{level}"
+    parent_col = f"GID_{level - 1}" if level > 0 else None
+    required = REQUIRED_BASE | {gid_col}
+    missing = required - set(frame.columns)
+    if missing:
+        raise ValueError(f"missing required GADM columns: {sorted(missing)}")
+    if frame.crs is None:
+        raise ValueError("GADM source must have a declared CRS")
+
+    source_ids = _require_identity(frame[gid_col], label="source geography identity")
+    country_ids = _require_identity(frame["GID_0"], label="country identity")
+
+    data = frame.to_crs("EPSG:4326").copy()
+    metric = data.to_crs(area_crs)
+    data["area_km2"] = metric.geometry.area / 1_000_000.0
+    data["provider"] = "gadm"
+    data["version"] = version
+    data["source_geo_id"] = source_ids.to_numpy()
+    data["country_iso3"] = country_ids.str.slice(0, 3).to_numpy()
+    data["native_admin_level"] = level
+    data["geo_uid"] = data["source_geo_id"].map(lambda x: geography_uid("gadm", version, level, x))
+    if parent_col and parent_col in data.columns:
+        parent_present = data[parent_col].notna() & data[parent_col].astype("string").str.strip().ne("")
+        data["parent_geo_uid"] = [
+            geography_uid("gadm", version, level - 1, str(value)) if present else None
+            for value, present in zip(data[parent_col], parent_present)
+        ]
+    else:
+        data["parent_geo_uid"] = None
+    data["geometry_role"] = GeometryRole.ANALYTICAL.value
+
+    keep = [
+        "geo_uid",
+        "provider",
+        "version",
+        "source_geo_id",
+        "country_iso3",
+        "native_admin_level",
+        "parent_geo_uid",
+        "area_km2",
+        "geometry_role",
+        "geometry",
+    ]
+    out = data[keep].copy()
+    if out["geo_uid"].duplicated().any():
+        dupes = out.loc[out["geo_uid"].duplicated(keep=False), "geo_uid"].unique().tolist()[:10]
+        raise ValueError(f"duplicate geography IDs after normalization: {dupes}")
+
+    null_geometry = out.geometry.isna()
+    invalid_geometry = ~null_geometry & ~out.geometry.is_valid
+    out.attrs["area_crs"] = area_crs
+    out.attrs["geometry_profile"] = {
+        "rows": len(out),
+        "null": int(null_geometry.sum()),
+        "invalid": int(invalid_geometry.sum()),
+    }
+    return out

spatial_foundation/geography/materialize.py

@@ -0,0 +1,450 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from hashlib import sha256
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+from pathlib import Path
+
+import geopandas as gpd
+import pandas as pd
+from empirical_contracts import (
+    AuthorityLevel,
+    DataLayer,
+    DatasetRef,
+    GeographySpec,
+    GrainSpec,
+    QAResult,
+    RunManifest,
+    SourceSnapshotRef,
+)
+
+from ..catalog import DataRoot, sha256_file
+from .gadm import normalize_gadm_frame
+
+PACKAGE_NAME = "spatial-data-foundation"
+
+
+@dataclass(frozen=True)
+class GADMMaterialization:
+    run_id: str
+    dataset_root: Path
+    run_root: Path
+    outputs: dict[int, Path]
+    manifest_path: Path
+    qa_path: Path
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _package_version() -> str:
+    try:
+        return package_version(PACKAGE_NAME)
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+def _resolve_code_commit(explicit: str | None) -> str:
+    if explicit and explicit.strip():
+        return explicit.strip()
+    env_value = os.environ.get("SPATIAL_DATA_FOUNDATION_CODE_COMMIT")
+    if env_value and env_value.strip():
+        return env_value.strip()
+
+    repo_root = Path(__file__).resolve().parents[3]
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_root,
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError, subprocess.TimeoutExpired):
+        result = None
+    if result and result.stdout.strip():
+        return result.stdout.strip()
+    raise ValueError(
+        "code_commit is required when Git metadata is unavailable; pass it explicitly "
+        "or set SPATIAL_DATA_FOUNDATION_CODE_COMMIT"
+    )
+
+
+def _validate_levels(levels: Iterable[int]) -> tuple[int, ...]:
+    normalized = tuple(sorted(set(levels)))
+    if not normalized:
+        raise ValueError("at least one GADM level is required")
+    if any(not isinstance(level, int) or isinstance(level, bool) or level < 0 for level in normalized):
+        raise ValueError("GADM levels must be non-negative integers")
+    return normalized
+
+
+def _validate_run_id(run_id: str) -> str:
+    if not run_id or run_id in {".", ".."} or "/" in run_id or "\\" in run_id:
+        raise ValueError("run_id must be a non-empty path-safe identifier")
+    return run_id
+
+
+def _default_run_id(
+    *,
+    snapshot: SourceSnapshotRef,
+    levels: tuple[int, ...],
+    area_crs: str,
+    code_commit: str,
+    started_at: datetime,
+) -> str:
+    payload = "|".join(
+        [snapshot.snapshot_id, ",".join(map(str, levels)), area_crs, code_commit]
+    ).encode()
+    short = sha256(payload).hexdigest()[:8]
+    stamp = started_at.strftime("%Y%m%dT%H%M%S%fZ")
+    release = snapshot.release.replace(".", "-").replace("/", "-")
+    return f"gadm-{release}-{stamp}-{short}"
+
+
+def _write_json(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _verify_snapshot(snapshot: SourceSnapshotRef) -> None:
+    if snapshot.source.lower() != "gadm":
+        raise ValueError(f"materialize_gadm requires a GADM snapshot, got {snapshot.source!r}")
+    for ref in snapshot.files:
+        path = Path(ref.path)
+        if not path.exists():
+            raise ValueError(f"source snapshot file is missing: {path}")
+        actual_hash = sha256_file(path)
+        if actual_hash != ref.sha256:
+            raise ValueError(
+                f"source snapshot hash mismatch for {path}: expected {ref.sha256}, got {actual_hash}"
+            )
+        actual_size = path.stat().st_size
+        if actual_size != ref.size_bytes:
+            raise ValueError(
+                f"source snapshot size mismatch for {path}: expected {ref.size_bytes}, got {actual_size}"
+            )
+
+
+def _native_level(frame: gpd.GeoDataFrame) -> int | None:
+    levels = []
+    for column in frame.columns:
+        if not column.startswith("GID_"):
+            continue
+        suffix = column[4:]
+        if suffix.isdigit():
+            levels.append(int(suffix))
+    return max(levels) if levels else None
+
+
+def _read_single_level(path: Path, level: int) -> gpd.GeoDataFrame | None:
+    suffix = path.suffix.lower()
+    if suffix in {".parquet", ".geoparquet"}:
+        frame = gpd.read_parquet(path)
+        return frame if _native_level(frame) == level else None
+
+    if suffix == ".gpkg":
+        layer = f"ADM_ADM_{level}"
+        try:
+            frame = gpd.read_file(path, layer=layer)
+        except (ValueError, RuntimeError, OSError):
+            try:
+                frame = gpd.read_file(path)
+            except (ValueError, RuntimeError, OSError):
+                return None
+        return frame if _native_level(frame) == level else None
+
+    try:
+        frame = gpd.read_file(path)
+    except (ValueError, RuntimeError, OSError) as exc:
+        raise ValueError(f"cannot read registered GADM source file {path}: {exc}") from exc
+    return frame if _native_level(frame) == level else None
+
+
+def _read_level(
+    snapshot: SourceSnapshotRef,
+    level: int,
+    *,
+    area_crs: str,
+) -> gpd.GeoDataFrame:
+    normalized_parts = []
+    for ref in snapshot.files:
+        source = _read_single_level(Path(ref.path), level)
+        if source is None:
+            continue
+        normalized_parts.append(
+            normalize_gadm_frame(
+                source,
+                version=snapshot.release,
+                level=level,
+                area_crs=area_crs,
+            )
+        )
+
+    if not normalized_parts:
+        raise ValueError(
+            f"registered GADM snapshot {snapshot.snapshot_id!r} contains no readable ADM{level} layer"
+        )
+
+    combined = gpd.GeoDataFrame(
+        pd.concat(normalized_parts, ignore_index=True),
+        geometry="geometry",
+        crs="EPSG:4326",
+    )
+    if combined["geo_uid"].duplicated().any():
+        duplicates = int(combined["geo_uid"].duplicated(keep=False).sum())
+        raise ValueError(f"duplicate geography IDs across registered GADM files: {duplicates} row(s)")
+    return combined
+
+
+def _level_metrics(frame: gpd.GeoDataFrame) -> dict[str, int]:
+    null_geometry = frame.geometry.isna()
+    invalid_geometry = ~null_geometry & ~frame.geometry.is_valid
+    return {
+        "row_count": len(frame),
+        "country_count": int(frame["country_iso3"].nunique(dropna=True)),
+        "null_geometry_count": int(null_geometry.sum()),
+        "invalid_geometry_count": int(invalid_geometry.sum()),
+        "duplicate_id_count": int(frame["geo_uid"].duplicated(keep=False).sum()),
+    }
+
+
+def _dataset_ref(level: int, release: str, content_hash: str) -> DatasetRef:
+    return DatasetRef(
+        dataset_id=f"gadm_native_adm{level}",
+        version=release,
+        schema_version="1",
+        layer=DataLayer.SILVER,
+        authority=AuthorityLevel.L1_NORMALIZED,
+        grain=GrainSpec(keys=("geo_uid",)),
+        geography=GeographySpec(
+            provider="gadm",
+            version=release,
+            scheme="native",
+            level=f"adm{level}",
+        ),
+        content_sha256=content_hash,
+    )
+
+
+def materialize_gadm(
+    *,
+    snapshot: SourceSnapshotRef,
+    levels: Iterable[int],
+    output_root: str | Path,
+    area_crs: str = "EPSG:6933",
+    code_commit: str | None = None,
+    run_id: str | None = None,
+    overwrite: bool = False,
+) -> GADMMaterialization:
+    """Materialize registered GADM sources as auditable silver GeoParquet assets.
+
+    Source bytes are never downloaded or copied by this function. Registered hashes are
+    revalidated before reading. All requested levels are normalized and staged before
+    final silver paths are published. Run provenance and geography QA are persisted as
+    JSON companions under ``runs/spatial-data-foundation/<run_id>/``.
+
+    The registered snapshot may contain separate level files or standard GADM 4.x
+    GeoPackages with ``ADM_ADM_<level>`` layers. GeoParquet materialization requires
+    the package ``io`` extra (pyarrow).
+    """
+    try:
+        import pyarrow  # noqa: F401
+    except ImportError as exc:
+        raise RuntimeError(
+            "materialize_gadm requires pyarrow; install spatial-data-foundation[io]"
+        ) from exc
+
+    requested_levels = _validate_levels(levels)
+    if not area_crs or not area_crs.strip():
+        raise ValueError("area_crs must be non-empty")
+    commit = _resolve_code_commit(code_commit)
+    started_at = _utc_now()
+    resolved_run_id = _validate_run_id(
+        run_id
+        or _default_run_id(
+            snapshot=snapshot,
+            levels=requested_levels,
+            area_crs=area_crs,
+            code_commit=commit,
+            started_at=started_at,
+        )
+    )
+
+    data_root = DataRoot.from_path(output_root)
+    dataset_root = data_root.silver("geography", "gadm", snapshot.release)
+    run_root = data_root.run(PACKAGE_NAME, resolved_run_id)
+    manifest_path = run_root / "run_manifest.json"
+    qa_path = run_root / "geography_qa.json"
+    run_root.mkdir(parents=True, exist_ok=True)
+
+    outputs = {level: dataset_root / f"adm{level}.geoparquet" for level in requested_levels}
+    temp_paths = {level: dataset_root / f".adm{level}.geoparquet.tmp" for level in requested_levels}
+
+    try:
+        _verify_snapshot(snapshot)
+        normalized = {
+            level: _read_level(snapshot, level, area_crs=area_crs)
+            for level in requested_levels
+        }
+
+        for path in outputs.values():
+            if path.exists() and not overwrite:
+                raise FileExistsError(
+                    f"refusing to overwrite existing GADM asset {path}; pass overwrite=True explicitly"
+                )
+
+        dataset_root.mkdir(parents=True, exist_ok=True)
+        output_hashes: dict[int, str] = {}
+        level_qa: dict[str, dict[str, int | str]] = {}
+        for level, frame in normalized.items():
+            temp = temp_paths[level]
+            if temp.exists():
+                temp.unlink()
+            frame.to_parquet(temp, index=False)
+            output_hash = sha256_file(temp)
+            output_hashes[level] = output_hash
+            level_qa[str(level)] = {
+                **_level_metrics(frame),
+                "output_path": str(outputs[level]),
+                "output_sha256": output_hash,
+            }
+
+        dataset_refs = tuple(
+            _dataset_ref(level, snapshot.release, output_hashes[level])
+            for level in requested_levels
+        )
+        qa_results = [
+            QAResult(
+                check_id="gadm_source_snapshot_integrity",
+                state="GREEN",
+                message="registered GADM source files match their snapshot hashes",
+                metrics={"file_count": len(snapshot.files)},
+            )
+        ]
+        for level in requested_levels:
+            metrics = level_qa[str(level)]
+            has_geometry_issue = bool(
+                metrics["null_geometry_count"] or metrics["invalid_geometry_count"]
+            )
+            qa_results.append(
+                QAResult(
+                    check_id=f"gadm_adm{level}_geometry_profile",
+                    state="YELLOW" if has_geometry_issue else "GREEN",
+                    message=(
+                        "geometry profile contains null or invalid geometries"
+                        if has_geometry_issue
+                        else "geometry profile is clean"
+                    ),
+                    metrics={
+                        "row_count": metrics["row_count"],
+                        "country_count": metrics["country_count"],
+                        "null_geometry_count": metrics["null_geometry_count"],
+                        "invalid_geometry_count": metrics["invalid_geometry_count"],
+                        "duplicate_id_count": metrics["duplicate_id_count"],
+                    },
+                )
+            )
+
+        finished_at = _utc_now()
+        manifest = RunManifest(
+            run_id=resolved_run_id,
+            package=PACKAGE_NAME,
+            package_version=_package_version(),
+            code_commit=commit,
+            started_at=started_at,
+            finished_at=finished_at,
+            inputs=(snapshot,),
+            parameters={
+                "provider": "gadm",
+                "version": snapshot.release,
+                "area_crs": area_crs,
+                "requested_levels": list(requested_levels),
+                "available_levels": list(requested_levels),
+                "output_files": {
+                    str(level): {
+                        "path": str(outputs[level]),
+                        "sha256": output_hashes[level],
+                    }
+                    for level in requested_levels
+                },
+            },
+            outputs=dataset_refs,
+            qa=tuple(qa_results),
+        )
+        qa_payload = {
+            "state": "YELLOW"
+            if any(result.state == "YELLOW" for result in qa_results)
+            else "GREEN",
+            "provider": "gadm",
+            "version": snapshot.release,
+            "area_crs": area_crs,
+            "available_levels": list(requested_levels),
+            "source_snapshot": snapshot.model_dump(mode="json"),
+            "levels": level_qa,
+        }
+
+        for level in requested_levels:
+            temp_paths[level].replace(outputs[level])
+        _write_json(manifest_path, manifest.model_dump(mode="json"))
+        _write_json(qa_path, qa_payload)
+
+        return GADMMaterialization(
+            run_id=resolved_run_id,
+            dataset_root=dataset_root,
+            run_root=run_root,
+            outputs=outputs,
+            manifest_path=manifest_path,
+            qa_path=qa_path,
+        )
+    except Exception as exc:
+        for temp in temp_paths.values():
+            if temp.exists():
+                temp.unlink()
+        failure = QAResult(
+            check_id="gadm_materialization",
+            state="RED",
+            message=str(exc),
+            metrics={"requested_level_count": len(requested_levels)},
+        )
+        failure_manifest = RunManifest(
+            run_id=resolved_run_id,
+            package=PACKAGE_NAME,
+            package_version=_package_version(),
+            code_commit=commit,
+            started_at=started_at,
+            finished_at=_utc_now(),
+            inputs=(snapshot,),
+            parameters={
+                "provider": "gadm",
+                "version": snapshot.release,
+                "area_crs": area_crs,
+                "requested_levels": list(requested_levels),
+                "available_levels": [],
+            },
+            outputs=(),
+            qa=(failure,),
+        )
+        _write_json(manifest_path, failure_manifest.model_dump(mode="json"))
+        _write_json(
+            qa_path,
+            {
+                "state": "RED",
+                "provider": "gadm",
+                "version": snapshot.release,
+                "area_crs": area_crs,
+                "available_levels": [],
+                "source_snapshot": snapshot.model_dump(mode="json"),
+                "error": str(exc),
+                "levels": {},
+            },
+        )
+        raise

spatial_foundation/geography/membership.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import geopandas as gpd
+import pandas as pd
+
+from .models import MembershipStatus
+
+
+@dataclass(frozen=True)
+class MembershipAudit:
+    input_points: int
+    matched_unique: int
+    unmatched_outside: int
+    ambiguous_multiple: int
+
+
+def assign_points(
+    points: gpd.GeoDataFrame,
+    polygons: gpd.GeoDataFrame,
+    *,
+    point_id_col: str,
+    polygon_id_col: str = "geo_uid",
+) -> tuple[pd.DataFrame, MembershipAudit]:
+    """Return candidate memberships and explicit point-level assignment status.
+
+    Boundary/multiple-polygon cases are *not* silently tie-broken. A downstream
+    source-specific policy may decide what to do with them.
+    """
+    if points.crs is None or polygons.crs is None:
+        raise ValueError("both points and polygons require a CRS")
+    if point_id_col not in points.columns:
+        raise ValueError(f"missing point id column: {point_id_col}")
+    if polygon_id_col not in polygons.columns:
+        raise ValueError(f"missing polygon id column: {polygon_id_col}")
+    if points[point_id_col].duplicated().any():
+        raise ValueError("point IDs must be unique")
+    if polygons[polygon_id_col].duplicated().any():
+        raise ValueError("polygon IDs must be unique")
+    if "geometry_role" in polygons.columns:
+        roles = polygons["geometry_role"].astype("string")
+        if roles.isna().any() or roles.ne("analytical").any():
+            raise ValueError("point assignment requires analytical geometry")
+
+    left = points[[point_id_col, "geometry"]].to_crs(polygons.crs)
+    right = polygons[[polygon_id_col, "geometry"]]
+
+    # intersects intentionally preserves exact-boundary candidates instead of
+    # dropping them as `within` could do.
+    joined = gpd.sjoin(left, right, how="left", predicate="intersects")
+    candidates = joined[[point_id_col, polygon_id_col]].copy()
+
+    counts = candidates.groupby(point_id_col)[polygon_id_col].count()
+    status_rows = []
+    for point_id in left[point_id_col]:
+        n = int(counts.get(point_id, 0))
+        if n == 0:
+            status = MembershipStatus.UNMATCHED_OUTSIDE.value
+        elif n == 1:
+            status = MembershipStatus.MATCHED_UNIQUE.value
+        else:
+            status = MembershipStatus.AMBIGUOUS_MULTIPLE.value
+        status_rows.append({point_id_col: point_id, "candidate_count": n, "assignment_status": status})
+    status_df = pd.DataFrame(status_rows)
+    result = candidates.merge(status_df, on=point_id_col, how="left")
+
+    audit = MembershipAudit(
+        input_points=len(left),
+        matched_unique=int((status_df.assignment_status == MembershipStatus.MATCHED_UNIQUE.value).sum()),
+        unmatched_outside=int((status_df.assignment_status == MembershipStatus.UNMATCHED_OUTSIDE.value).sum()),
+        ambiguous_multiple=int((status_df.assignment_status == MembershipStatus.AMBIGUOUS_MULTIPLE.value).sum()),
+    )
+    return result, audit

spatial_foundation/geography/models.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FrozenModel(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class GeometryRole(str, Enum):
+    ANALYTICAL = "analytical"
+    DISPLAY = "display"
+
+
+class MembershipStatus(str, Enum):
+    MATCHED_UNIQUE = "matched_unique"
+    UNMATCHED_OUTSIDE = "unmatched_outside"
+    AMBIGUOUS_MULTIPLE = "ambiguous_multiple"
+    INVALID_POINT = "invalid_point"
+
+
+class GeographyUnit(FrozenModel):
+    geo_uid: str
+    provider: str
+    version: str
+    source_geo_id: str
+    country_iso3: str
+    native_admin_level: int = Field(ge=0)
+    parent_geo_uid: str | None = None
+    area_km2: float | None = Field(default=None, ge=0)
+    geometry_role: GeometryRole = GeometryRole.ANALYTICAL
+
+
+def geography_uid(provider: str, version: str, native_admin_level: int, source_geo_id: str) -> str:
+    return f"{provider}:{version}:adm{native_admin_level}:{source_geo_id}"

spatial_foundation/geography/overlap.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import geopandas as gpd
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class ArealOverlapAudit:
+    input_objects: int
+    matched_single: int
+    matched_multiple: int
+    unmatched_outside: int
+    invalid_geometry: int
+    relation_rows: int
+
+
+_AREAL_GEOMETRY_TYPES = {"Polygon", "MultiPolygon"}
+
+
+def _require_analytical_geography(polygons: gpd.GeoDataFrame) -> None:
+    if "geometry_role" not in polygons.columns:
+        return
+    roles = polygons["geometry_role"].astype("string")
+    if roles.isna().any() or roles.ne("analytical").any():
+        raise ValueError("areal overlap requires analytical geography geometry")
+
+
+def _positive_overlap_pairs(
+    objects: gpd.GeoDataFrame,
+    polygons: gpd.GeoDataFrame,
+    *,
+    object_id_col: str,
+    polygon_id_col: str,
+    area_crs: str,
+    min_overlap_area_m2: float,
+) -> pd.DataFrame:
+    left = objects[[object_id_col, "geometry"]].to_crs(polygons.crs)
+    right = polygons[[polygon_id_col, "geometry"]]
+    candidates = gpd.sjoin(left, right, how="inner", predicate="intersects")
+    pairs = candidates[[object_id_col, polygon_id_col]].drop_duplicates().copy()
+    if pairs.empty:
+        return pd.DataFrame(
+            columns=[object_id_col, polygon_id_col, "overlap_area_m2", "overlap_share_of_object"]
+        )
+
+    object_area = objects[[object_id_col, "geometry"]].to_crs(area_crs)
+    polygon_area = polygons[[polygon_id_col, "geometry"]].to_crs(area_crs)
+    object_geometries = object_area.set_index(object_id_col)["geometry"]
+    polygon_geometries = polygon_area.set_index(polygon_id_col)["geometry"]
+
+    overlap_areas: list[float] = []
+    object_areas: list[float] = []
+    for object_id, polygon_id in pairs[[object_id_col, polygon_id_col]].itertuples(
+        index=False, name=None
+    ):
+        object_geometry = object_geometries.loc[object_id]
+        polygon_geometry = polygon_geometries.loc[polygon_id]
+        overlap_areas.append(float(object_geometry.intersection(polygon_geometry).area))
+        object_areas.append(float(object_geometry.area))
+
+    pairs["overlap_area_m2"] = overlap_areas
+    pairs["_object_area_m2"] = object_areas
+    pairs = pairs.loc[pairs["overlap_area_m2"] > min_overlap_area_m2].copy()
+    pairs["overlap_share_of_object"] = pairs["overlap_area_m2"] / pairs["_object_area_m2"]
+    return pairs.drop(columns=["_object_area_m2"]).reset_index(drop=True)
+
+
+def relate_areal_objects(
+    objects: gpd.GeoDataFrame,
+    polygons: gpd.GeoDataFrame,
+    *,
+    object_id_col: str,
+    polygon_id_col: str = "geo_uid",
+    area_crs: str = "EPSG:6933",
+    min_overlap_area_m2: float = 0.0,
+) -> tuple[pd.DataFrame, ArealOverlapAudit]:
+    """Relate areal source objects to analytical geography without assigning ownership.
+
+    One source geometry may legitimately overlap several geography units. Those rows are
+    retained as a many-to-many relation rather than treated as assignment ambiguity.
+    Intersection area and the share of the source object's area are geometric facts only;
+    they do not allocate money, exposure, population, or any other substantive quantity.
+
+    Boundary-only touches have zero intersection area and are excluded by default.
+    """
+    if min_overlap_area_m2 < 0:
+        raise ValueError("min_overlap_area_m2 must be non-negative")
+    if objects.crs is None or polygons.crs is None:
+        raise ValueError("both objects and polygons require a CRS")
+    if object_id_col not in objects.columns:
+        raise ValueError(f"missing object id column: {object_id_col}")
+    if polygon_id_col not in polygons.columns:
+        raise ValueError(f"missing polygon id column: {polygon_id_col}")
+    if objects[object_id_col].isna().any() or objects[object_id_col].duplicated().any():
+        raise ValueError("object IDs must be non-missing and unique")
+    if polygons[polygon_id_col].isna().any() or polygons[polygon_id_col].duplicated().any():
+        raise ValueError("polygon IDs must be non-missing and unique")
+    _require_analytical_geography(polygons)
+
+    polygon_geometry = polygons.geometry
+    if polygon_geometry.isna().any() or polygon_geometry.is_empty.any() or (~polygon_geometry.is_valid).any():
+        raise ValueError("analytical geography contains missing, empty, or invalid geometry")
+
+    object_geometry = objects.geometry
+    nonempty = object_geometry.notna() & ~object_geometry.is_empty
+    non_areal = nonempty & ~object_geometry.geom_type.isin(_AREAL_GEOMETRY_TYPES)
+    if non_areal.any():
+        found = sorted(object_geometry.loc[non_areal].geom_type.unique().tolist())
+        raise ValueError(
+            "relate_areal_objects accepts Polygon/MultiPolygon source geometry only; "
+            f"found {found}. Use point membership for point sources."
+        )
+
+    valid = nonempty & object_geometry.is_valid
+    valid_objects = objects.loc[valid, [object_id_col, "geometry"]].copy()
+    pairs = _positive_overlap_pairs(
+        valid_objects,
+        polygons,
+        object_id_col=object_id_col,
+        polygon_id_col=polygon_id_col,
+        area_crs=area_crs,
+        min_overlap_area_m2=min_overlap_area_m2,
+    )
+
+    overlap_counts = pairs.groupby(object_id_col)[polygon_id_col].count() if len(pairs) else pd.Series(dtype="int64")
+    rows: list[dict] = []
+    for object_id in objects[object_id_col]:
+        if not bool(valid.loc[objects[object_id_col].eq(object_id)].iloc[0]):
+            rows.append(
+                {
+                    object_id_col: object_id,
+                    polygon_id_col: pd.NA,
+                    "overlap_area_m2": pd.NA,
+                    "overlap_share_of_object": pd.NA,
+                    "overlap_count": 0,
+                    "relation_status": "invalid_geometry",
+                }
+            )
+            continue
+
+        count = int(overlap_counts.get(object_id, 0))
+        if count == 0:
+            rows.append(
+                {
+                    object_id_col: object_id,
+                    polygon_id_col: pd.NA,
+                    "overlap_area_m2": pd.NA,
+                    "overlap_share_of_object": pd.NA,
+                    "overlap_count": 0,
+                    "relation_status": "unmatched_outside",
+                }
+            )
+            continue
+
+        status = "matched_single" if count == 1 else "matched_multiple"
+        object_pairs = pairs.loc[pairs[object_id_col].eq(object_id)]
+        for pair in object_pairs.to_dict(orient="records"):
+            rows.append(
+                {
+                    **pair,
+                    "overlap_count": count,
+                    "relation_status": status,
+                }
+            )
+
+    result = pd.DataFrame(rows)
+    status_by_object = result[[object_id_col, "relation_status"]].drop_duplicates(object_id_col)
+    audit = ArealOverlapAudit(
+        input_objects=len(objects),
+        matched_single=int(status_by_object["relation_status"].eq("matched_single").sum()),
+        matched_multiple=int(status_by_object["relation_status"].eq("matched_multiple").sum()),
+        unmatched_outside=int(status_by_object["relation_status"].eq("unmatched_outside").sum()),
+        invalid_geometry=int(status_by_object["relation_status"].eq("invalid_geometry").sum()),
+        relation_rows=int(result[polygon_id_col].notna().sum()),
+    )
+    return result, audit

spatial_foundation/periods.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from empirical_contracts import PeriodScheme
+
+
+@dataclass(frozen=True)
+class Period:
+    period_id: str
+    start_year: int
+    end_year: int
+    ordinal: int
+    start_date: date
+    end_date_exclusive: date
+
+
+class PeriodIndex:
+    def __init__(self, scheme: PeriodScheme):
+        self.scheme = scheme
+
+    def start_year_for(self, value: date | datetime | int) -> int:
+        year = value if isinstance(value, int) else value.year
+        width = self.scheme.width_years
+        return self.scheme.anchor_year + math.floor((year - self.scheme.anchor_year) / width) * width
+
+    def period_for(self, value: date | datetime | int) -> Period:
+        start = self.start_year_for(value)
+        width = self.scheme.width_years
+        end = start + width - 1
+        ordinal = (start - self.scheme.anchor_year) // width
+        return Period(
+            period_id=f"{start}-{end}",
+            start_year=start,
+            end_year=end,
+            ordinal=ordinal,
+            start_date=date(start, 1, 1),
+            end_date_exclusive=date(start + width, 1, 1),
+        )
+
+    def range(self, start_year: int, end_year: int) -> tuple[Period, ...]:
+        if end_year < start_year:
+            raise ValueError("end_year must be >= start_year")
+        first = self.start_year_for(start_year)
+        last = self.start_year_for(end_year)
+        return tuple(self.period_for(year) for year in range(first, last + 1, self.scheme.width_years))

spatial_foundation/presentation/__init__.py

@@ -0,0 +1,10 @@
+from .basemaps import BASEMAP_ALIASES, BasemapSource, add_basemap, resolve_basemap
+from .plotting import plot_context
+
+__all__ = [
+    "BASEMAP_ALIASES",
+    "BasemapSource",
+    "add_basemap",
+    "plot_context",
+    "resolve_basemap",
+]

spatial_foundation/presentation/basemaps.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+_PRESENTATION_INSTALL_HINT = (
+    "spatial_foundation.presentation requires the optional presentation dependencies; "
+    "install with `pip install 'spatial-data-foundation[presentation]'`"
+)
+
+try:
+    import contextily as cx
+    from xyzservices import TileProvider, providers
+except ModuleNotFoundError as exc:  # pragma: no cover - exercised in an isolated subprocess
+    raise ModuleNotFoundError(_PRESENTATION_INSTALL_HINT) from exc
+
+
+BASEMAP_ALIASES: dict[str, TileProvider] = {
+    "neutral": providers.CartoDB.Positron,
+    "imagery": providers.Esri.WorldImagery,
+    "terrain": providers.OpenTopoMap,
+}
+
+BasemapSource = str | Path | TileProvider
+
+
+def resolve_basemap(source: BasemapSource = "neutral") -> str | TileProvider:
+    """Resolve a small governed alias vocabulary or pass through a concrete source.
+
+    String sources outside the alias vocabulary are intentionally passed through to
+    contextily, which can interpret a tile URL/provider name or a local raster path.
+    `Path` values are normalized to strings for the same reason.
+    """
+    if isinstance(source, Path):
+        return str(source)
+    if isinstance(source, str) and source in BASEMAP_ALIASES:
+        return BASEMAP_ALIASES[source]
+    return source
+
+
+def add_basemap(
+    ax: Any,
+    *,
+    crs: Any,
+    kind: str = "neutral",
+    source: BasemapSource | None = None,
+    alpha: float = 1.0,
+    attribution: str | None = None,
+    zoom: int | str = "auto",
+    interpolation: str = "bilinear",
+) -> Any:
+    """Add contextual cartography beneath an existing analytical plot.
+
+    This is presentation-only. It never changes source geometry or spatial
+    membership. The caller must provide the CRS of the plotted analytical data.
+    Provider attribution is preserved by default and cannot be disabled here.
+    """
+    if crs is None:
+        raise ValueError("a CRS is required to align a contextual basemap")
+    if attribution is False:
+        raise ValueError("basemap attribution cannot be disabled")
+    if not 0 <= alpha <= 1:
+        raise ValueError("alpha must be between 0 and 1")
+
+    selected: BasemapSource = source if source is not None else kind
+    resolved_source = resolve_basemap(selected)
+    xlim = ax.get_xlim()
+    ylim = ax.get_ylim()
+
+    cx.add_basemap(
+        ax,
+        crs=crs,
+        source=resolved_source,
+        alpha=alpha,
+        attribution=attribution,
+        reset_extent=True,
+        zoom=zoom,
+        interpolation=interpolation,
+    )
+
+    # contextily already promises reset_extent=True, but preserve the public
+    # presentation contract even if a provider/local raster behaves unusually.
+    ax.set_xlim(xlim)
+    ax.set_ylim(ylim)
+    return ax

spatial_foundation/presentation/plotting.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+import geopandas as gpd
+
+from .basemaps import BasemapSource, add_basemap
+
+
+def plot_context(
+    gdf: gpd.GeoDataFrame,
+    *,
+    basemap: BasemapSource = "neutral",
+    basemap_alpha: float = 1.0,
+    basemap_attribution: str | None = None,
+    basemap_zoom: int | str = "auto",
+    **plot_kwargs: Any,
+) -> Any:
+    """Plot a GeoDataFrame and add an optional contextual basemap beneath it."""
+    if gdf.crs is None:
+        raise ValueError("GeoDataFrame requires a CRS for contextual plotting")
+
+    ax = gdf.plot(**plot_kwargs)
+    add_basemap(
+        ax,
+        crs=gdf.crs,
+        source=basemap,
+        alpha=basemap_alpha,
+        attribution=basemap_attribution,
+        zoom=basemap_zoom,
+    )
+    return ax