spatial-data-foundation 0.1.0__tar.gz → 0.2.1__tar.gz

{spatial_data_foundation-0.1.0 → spatial_data_foundation-0.2.1}/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: spatial-data-foundation
-Version: 0.1.0
+Version: 0.2.1
 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: numpy>=1.24
+Requires-Dist: pandas>=2.2
+Requires-Dist: geopandas>=1.1
+Requires-Dist: shapely>=2.1
+Requires-Dist: pyproj>=3.7
+Requires-Dist: pyogrio>=0.8
 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"

spatial_data_foundation-0.2.1/README.md

@@ -0,0 +1,165 @@
+# spatial-data-foundation
+
+Reusable spatial/time infrastructure for research systems.
+
+This repository owns geography authority, period indexing, source registration, auditable spatial relations, and materialization provenance. It does **not** own FCV treatments, outcomes, matching, survey harmonization, regressions, domain assignment policy, or source acquisition.
+
+The current implementation is the completed engineering candidate produced by Build Pack B: the public spatial semantics remain small, while the internals use the modern GeoPandas/Shapely/PyProj/Pyogrio stack deliberately. See [`docs/RELEASE_READINESS_0_2.md`](docs/RELEASE_READINESS_0_2.md) for the evidence and release gates. The package is not published as `0.2.0` until a separate human-approved release step.
+
+## Public spatial contracts
+
+### Point membership
+
+`assign_points(...)` returns candidate memberships without silently resolving ambiguity.
+
+```python
+from spatial_foundation import assign_points
+
+result, audit = assign_points(
+    points,
+    analytical_polygons,
+    point_id_col="event_id",
+)
+```
+
+The supported source geometry family is Point. Interior one-candidate points are `matched_unique`; points with no candidate are `unmatched_outside`; exact-boundary/multiple candidates remain `ambiguous_multiple`; and missing, empty, or invalid Point geometry is `invalid_point`. Unsupported source geometry families fail closed.
+
+Target geography must have a CRS, unique/non-missing IDs, valid non-empty Polygon/MultiPolygon geometry, and analytical geometry role when that role is present.
+
+### Areal relations
+
+`relate_areal_objects(...)` returns positive-area geometric relation facts without assigning ownership.
+
+```python
+from spatial_foundation import relate_areal_objects
+
+relations, audit = relate_areal_objects(
+    source_polygons,
+    analytical_polygons,
+    object_id_col="source_id",
+    area_crs="EPSG:6933",
+)
+```
+
+One source object may legitimately relate to multiple target units. The foundation emits `matched_single`, `matched_multiple`, `unmatched_outside`, or `invalid_geometry`, plus `overlap_area_m2` and `overlap_share_of_object`. Boundary-only touches do not become positive-area relations. Winner/tie rules, allocation, exposure, population, or treatment interpretation remain downstream policy.
+
+Any CRS used to produce `_m2` / `_km2` quantities must be projected with metre horizontal axes. This guarantees unit correctness, not universal distortion-free area measurement.
+
+## Relation engine
+
+The implementation intentionally delegates spatial mechanics to mature libraries rather than creating a custom GIS layer:
+
+```text
+GeoPandas CRS-aware geometry arrays + cached spatial index
+                         |
+                         v
+              sindex.query positional pairs
+                         |
+                         v
+           Shapely vectorized GEOS operations
+                         |
+                         v
+                NumPy counts / masks
+                         |
+                         v
+                compact pandas results
+```
+
+Candidate row order is not a public contract. The benchmark suite protects semantic parity and records candidate amplification and phase timings without turning absolute wall time into a brittle CI threshold.
+
+## Operational GADM materialization
+
+Materialization works from registered immutable **local** source snapshots; it does not download GADM or other source data.
+
+Install the I/O extra and materialize the native levels required by downstream work:
+
+```bash
+pip install "spatial-data-foundation[io]"
+```
+
+```python
+from spatial_foundation import materialize_gadm
+
+materialize_gadm(
+    snapshot=gadm_4_1_snapshot,
+    levels=[0, 1, 2, 3],
+    output_root=data_root,
+)
+```
+
+Before loading complete geometry, vector sources are inspected through Pyogrio/GDAL to identify requested ADM layers and required identity fields. Reads are column-projected and the PyArrow-backed materialization workflow uses GDAL Arrow transfer where applicable. Separate-level vector files, multi-layer GeoPackages, and GeoParquet sources are supported.
+
+The workflow publishes full analytical geometry as GeoParquet under `silver/geography/gadm/<version>/` and writes `run_manifest.json` plus `geography_qa.json` under the run directory. Registered source hashes are rechecked before interpretation; source drift or malformed requested levels produce a RED run rather than partial silver publication.
+
+Installed wheels are first-class. Git metadata is optional: when no checkout SHA exists, `code_commit` is `null` and the manifest still records installed package version, runtime/native stack versions, source snapshot hashes, output hashes, parameters, and QA.
+
+## Dependency boundary
+
+Core implementation dependencies are declared directly rather than relying on GeoPandas transitively:
+
+```text
+Python                    >= 3.10
+empirical-data-contracts >= 0.1,<0.2
+NumPy                     >= 1.24
+pandas                    >= 2.2
+GeoPandas                 >= 1.1
+Shapely                   >= 2.1
+PyProj                    >= 3.7
+Pyogrio                   >= 0.8
+Pydantic                  >= 2.7,<3
+```
+
+Optional extras are deliberately limited to capabilities the repository actually owns:
+
+- `io` — PyArrow / GeoParquet materialization support;
+- `presentation` — contextual map presentation;
+- `dev` — tests, lint, build, and development dependencies.
+
+Raster, DuckDB query, and CLI surfaces are not advertised until owned implementations exist.
+
+## Optional contextual presentation
+
+Presentation helpers are an optional, non-analytical surface. Core imports do not require plotting or tile dependencies:
+
+```bash
+pip install "spatial-data-foundation[presentation]"
+```
+
+Add contextual imagery beneath an existing analytical plot:
+
+```python
+from spatial_foundation.presentation import add_basemap
+
+ax = gdf.plot(column="value", alpha=0.65)
+add_basemap(ax, crs=gdf.crs, kind="imagery", alpha=0.55)
+```
+
+Or use the compact GeoDataFrame helper:
+
+```python
+from spatial_foundation.presentation import plot_context
+
+ax = plot_context(
+    gdf,
+    basemap="neutral",
+    column="value",
+)
+```
+
+The governed convenience aliases are `neutral`, `imagery`, and `terrain`. A concrete tile source or local raster path can also be supplied. Local rasters allow reproducible/offline presentation; web providers may perform network requests only when explicitly selected by the caller.
+
+Presentation never changes analytical geometry, membership, identifiers, or domain interpretation. Provider attribution remains enabled, and no provider credentials are bundled with this package.
+
+## Scope discipline
+
+The foundation deliberately does not contain:
+
+- treatment/control/exposure semantics;
+- census/electoral winner or crosswalk policy;
+- automatic provider downloads;
+- generic geometry repair or precision policy;
+- public STRtree/cache classes;
+- distributed orchestration;
+- speculative raster, query, or CLI frameworks.
+
+New primitives should enter this package only when they are reusable geometric/spatiotemporal mechanics with a concrete consumer, not merely because a GIS library makes them possible.

{spatial_data_foundation-0.1.0 → spatial_data_foundation-0.2.1}/pyproject.toml

@@ -4,21 +4,22 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spatial-data-foundation"
-version = "0.1.0"
+version = "0.2.1"
 description = "Reusable geography, time, provenance and spatial-membership infrastructure for empirical research"
 requires-python = ">=3.10"
 dependencies = [
   "empirical-data-contracts>=0.1,<0.2",
-  "geopandas>=0.14",
-  "shapely>=2",
-  "pyproj>=3.5",
+  "numpy>=1.24",
+  "pandas>=2.2",
+  "geopandas>=1.1",
+  "shapely>=2.1",
+  "pyproj>=3.7",
+  "pyogrio>=0.8",
   "pydantic>=2.7,<3",
 ]
 
 [project.optional-dependencies]
-io = ["pyarrow>=15", "duckdb>=1.0"]
-raster = ["rasterio>=1.3"]
-cli = ["typer>=0.12"]
+io = ["pyarrow>=15"]
 presentation = [
   "matplotlib>=3.8",
   "contextily>=1.7.1,<2",

{spatial_data_foundation-0.1.0 → spatial_data_foundation-0.2.1}/src/spatial_data_foundation.egg-info/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: spatial-data-foundation
-Version: 0.1.0
+Version: 0.2.1
 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: numpy>=1.24
+Requires-Dist: pandas>=2.2
+Requires-Dist: geopandas>=1.1
+Requires-Dist: shapely>=2.1
+Requires-Dist: pyproj>=3.7
+Requires-Dist: pyogrio>=0.8
 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"

{spatial_data_foundation-0.1.0 → spatial_data_foundation-0.2.1}/src/spatial_data_foundation.egg-info/SOURCES.txt

@@ -6,9 +6,12 @@ src/spatial_data_foundation.egg-info/dependency_links.txt
 src/spatial_data_foundation.egg-info/requires.txt
 src/spatial_data_foundation.egg-info/top_level.txt
 src/spatial_foundation/__init__.py
+src/spatial_foundation/_runtime.py
 src/spatial_foundation/catalog.py
 src/spatial_foundation/periods.py
 src/spatial_foundation/geography/__init__.py
+src/spatial_foundation/geography/_gadm_io.py
+src/spatial_foundation/geography/_validation.py
 src/spatial_foundation/geography/gadm.py
 src/spatial_foundation/geography/materialize.py
 src/spatial_foundation/geography/membership.py
@@ -19,11 +22,16 @@ src/spatial_foundation/presentation/basemaps.py
 src/spatial_foundation/presentation/plotting.py
 tests/test_adversarial_spatial.py
 tests/test_areal_overlap.py
+tests/test_benchmarks.py
 tests/test_catalog.py
+tests/test_dependency_boundary.py
 tests/test_distribution.py
 tests/test_external_consumer.py
+tests/test_gadm_io.py
 tests/test_gadm_materialization.py
 tests/test_geography.py
 tests/test_membership_kernel.py
 tests/test_periods.py
-tests/test_presentation.py
+tests/test_presentation.py
+tests/test_relation_kernel_parity.py
+tests/test_spatial_invariants.py

{spatial_data_foundation-0.1.0 → spatial_data_foundation-0.2.1}/src/spatial_data_foundation.egg-info/requires.txt

@@ -1,12 +1,12 @@
 empirical-data-contracts<0.2,>=0.1
-geopandas>=0.14
-shapely>=2
-pyproj>=3.5
+numpy>=1.24
+pandas>=2.2
+geopandas>=1.1
+shapely>=2.1
+pyproj>=3.7
+pyogrio>=0.8
 pydantic<3,>=2.7
 
-[cli]
-typer>=0.12
-
 [dev]
 pytest>=8
 ruff>=0.6
@@ -18,12 +18,8 @@ xyzservices<2027,>=2026.3
 
 [io]
 pyarrow>=15
-duckdb>=1.0
 
 [presentation]
 matplotlib>=3.8
 contextily<2,>=1.7.1
 xyzservices<2027,>=2026.3
-
-[raster]
-rasterio>=1.3

spatial_data_foundation-0.2.1/src/spatial_foundation/_runtime.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import platform
+from importlib import metadata
+
+_PACKAGE_NAMES = (
+    "spatial-data-foundation",
+    "empirical-data-contracts",
+    "geopandas",
+    "pandas",
+    "numpy",
+    "shapely",
+    "pyproj",
+    "pyogrio",
+    "pyarrow",
+)
+
+
+def runtime_versions() -> dict[str, str]:
+    """Return installed Python/geospatial runtime versions for provenance."""
+    versions = {"python": platform.python_version()}
+    for name in _PACKAGE_NAMES:
+        try:
+            versions[name] = metadata.version(name)
+        except metadata.PackageNotFoundError:
+            versions[name] = "not-installed"
+
+    try:
+        import shapely
+
+        versions["GEOS"] = shapely.geos_version_string
+    except (ImportError, AttributeError):
+        pass
+
+    try:
+        import pyproj
+
+        versions["PROJ"] = pyproj.proj_version_str
+    except (ImportError, AttributeError):
+        pass
+
+    try:
+        import pyogrio
+
+        versions["GDAL"] = ".".join(str(part) for part in pyogrio.__gdal_version__)
+    except (ImportError, AttributeError):
+        pass
+
+    return versions

spatial_data_foundation-0.2.1/src/spatial_foundation/geography/_gadm_io.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+import geopandas as gpd
+import pyogrio
+
+
+@dataclass(frozen=True)
+class GADMSourceSelection:
+    path: Path
+    layer: str | None
+    columns: tuple[str, ...]
+    geometry_column: str | None = None
+
+
+def _native_level_from_fields(fields: Iterable[str]) -> int | None:
+    levels = []
+    for field in fields:
+        if not field.startswith("GID_"):
+            continue
+        suffix = field[4:]
+        if suffix.isdigit():
+            levels.append(int(suffix))
+    return max(levels) if levels else None
+
+
+def _required_identity_columns(fields: Iterable[str], level: int) -> tuple[str, ...]:
+    available = set(fields)
+    required = ["GID_0", f"GID_{level}"]
+    missing = sorted(set(required) - available)
+    if missing:
+        raise ValueError(
+            f"GADM ADM{level} source is missing required identity fields: {missing}"
+        )
+
+    columns = ["GID_0"]
+    if level > 0:
+        parent = f"GID_{level - 1}"
+        if parent in available and parent not in columns:
+            columns.append(parent)
+    current = f"GID_{level}"
+    if current not in columns:
+        columns.append(current)
+    return tuple(columns)
+
+
+def _inspect_vector_source(path: Path, level: int) -> GADMSourceSelection | None:
+    try:
+        layers = pyogrio.list_layers(path)
+    except Exception as exc:
+        raise ValueError(f"cannot inspect registered GADM source file {path}: {exc}") from exc
+
+    matches: list[GADMSourceSelection] = []
+    for row in layers:
+        layer = str(row[0])
+        try:
+            info = pyogrio.read_info(path, layer=layer)
+        except Exception as exc:
+            raise ValueError(
+                f"cannot inspect registered GADM layer {layer!r} in {path}: {exc}"
+            ) from exc
+        fields = tuple(str(field) for field in info.get("fields", ()))
+        if _native_level_from_fields(fields) != level:
+            continue
+        columns = _required_identity_columns(fields, level)
+        matches.append(GADMSourceSelection(path=path, layer=layer, columns=columns))
+
+    if len(matches) > 1:
+        layer_names = [selection.layer for selection in matches]
+        raise ValueError(
+            f"registered GADM source {path} contains multiple ADM{level} layers: {layer_names}"
+        )
+    return matches[0] if matches else None
+
+
+def _inspect_geoparquet_source(path: Path, level: int) -> GADMSourceSelection | None:
+    try:
+        import pyarrow.parquet as pq
+    except ImportError as exc:  # pragma: no cover - materialization checks this first
+        raise RuntimeError(
+            "GeoParquet GADM source inspection requires pyarrow; "
+            "install spatial-data-foundation[io]"
+        ) from exc
+
+    try:
+        schema = pq.read_schema(path)
+    except Exception as exc:
+        raise ValueError(f"cannot inspect registered GADM GeoParquet {path}: {exc}") from exc
+
+    fields = tuple(schema.names)
+    if _native_level_from_fields(fields) != level:
+        return None
+    columns = _required_identity_columns(fields, level)
+
+    metadata = schema.metadata or {}
+    geo_metadata = metadata.get(b"geo")
+    if not geo_metadata:
+        raise ValueError(f"registered GADM parquet source is missing GeoParquet metadata: {path}")
+    try:
+        primary_geometry = json.loads(geo_metadata.decode("utf-8"))["primary_column"]
+    except (KeyError, TypeError, ValueError, UnicodeDecodeError) as exc:
+        raise ValueError(f"cannot resolve GeoParquet primary geometry column for {path}") from exc
+    if primary_geometry not in fields:
+        raise ValueError(
+            f"GeoParquet primary geometry column {primary_geometry!r} is missing from {path}"
+        )
+    return GADMSourceSelection(
+        path=path,
+        layer=None,
+        columns=columns,
+        geometry_column=primary_geometry,
+    )
+
+
+def inspect_gadm_source(path: Path, level: int) -> GADMSourceSelection | None:
+    """Select one requested native GADM level without materializing source geometry."""
+    suffix = path.suffix.lower()
+    if suffix in {".parquet", ".geoparquet"}:
+        return _inspect_geoparquet_source(path, level)
+    return _inspect_vector_source(path, level)
+
+
+def read_gadm_selection(
+    selection: GADMSourceSelection,
+    *,
+    use_arrow: bool,
+) -> gpd.GeoDataFrame:
+    """Read only the selected GADM identity columns plus the authoritative geometry."""
+    if selection.geometry_column is not None:
+        columns = [*selection.columns, selection.geometry_column]
+        try:
+            return gpd.read_parquet(selection.path, columns=columns)
+        except Exception as exc:
+            raise ValueError(
+                f"cannot read registered GADM GeoParquet {selection.path}: {exc}"
+            ) from exc
+
+    try:
+        return pyogrio.read_dataframe(
+            selection.path,
+            layer=selection.layer,
+            columns=list(selection.columns),
+            use_arrow=use_arrow,
+        )
+    except Exception as exc:
+        layer_text = "" if selection.layer is None else f" layer {selection.layer!r}"
+        raise ValueError(
+            f"cannot read registered GADM source file {selection.path}{layer_text}: {exc}"
+        ) from exc
+
+
+def read_gadm_level_parts(
+    paths: Iterable[Path],
+    level: int,
+    *,
+    use_arrow: bool,
+) -> list[gpd.GeoDataFrame]:
+    """Inspect registered sources first, then load only parts matching ``level``."""
+    parts = []
+    for path in paths:
+        selection = inspect_gadm_source(path, level)
+        if selection is None:
+            continue
+        parts.append(read_gadm_selection(selection, use_arrow=use_arrow))
+    return parts

spatial_data_foundation-0.2.1/src/spatial_foundation/geography/_validation.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import math
+
+import geopandas as gpd
+from pyproj import CRS
+
+_AREAL_GEOMETRY_TYPES = {"Polygon", "MultiPolygon"}
+
+
+def require_unique_nonmissing_ids(
+    frame: gpd.GeoDataFrame,
+    column: str,
+    *,
+    label: str,
+) -> None:
+    if column not in frame.columns:
+        raise ValueError(f"missing {label} id column: {column}")
+    values = frame[column]
+    if values.isna().any():
+        raise ValueError(f"{label} IDs must be non-missing")
+    if values.duplicated().any():
+        raise ValueError(f"{label} IDs must be unique")
+
+
+def require_analytical_polygons(
+    polygons: gpd.GeoDataFrame,
+    *,
+    polygon_id_col: str,
+    operation: str,
+) -> None:
+    if polygons.crs is None:
+        raise ValueError(f"{operation} analytical geography inputs require a CRS")
+    require_unique_nonmissing_ids(polygons, polygon_id_col, label="polygon")
+
+    if "geometry_role" in polygons.columns:
+        roles = polygons["geometry_role"].astype("string")
+        if roles.isna().any() or roles.ne("analytical").any():
+            raise ValueError(
+                f"{operation} requires analytical geometry; analytical geography only"
+            )
+
+    geometry = polygons.geometry
+    if geometry.isna().any() or geometry.is_empty.any() or (~geometry.is_valid).any():
+        raise ValueError("analytical geography contains missing, empty, or invalid geometry")
+    non_areal = ~geometry.geom_type.isin(_AREAL_GEOMETRY_TYPES)
+    if non_areal.any():
+        found = sorted(geometry.loc[non_areal].geom_type.unique().tolist())
+        raise ValueError(
+            f"{operation} analytical geography requires Polygon/MultiPolygon geometry; "
+            f"found {found}"
+        )
+
+
+def require_projected_metre_crs(value: object, *, label: str = "area_crs") -> CRS:
+    """Return a CRS that is projected and whose horizontal axes use metres.
+
+    This establishes unit correctness for quantities labelled in square metres or
+    square kilometres. It deliberately does not claim that every projected metre
+    CRS is equal-area or otherwise suitable for every scientific measurement.
+    """
+    try:
+        crs = CRS.from_user_input(value)
+    except Exception as exc:  # pyproj accepts several user-input exception types
+        raise ValueError(f"{label} is not a resolvable CRS: {value!r}") from exc
+
+    if not crs.is_projected:
+        raise ValueError(f"{label} must be a projected CRS with metre horizontal units")
+
+    axes = crs.axis_info[:2]
+    if len(axes) < 2:
+        raise ValueError(f"{label} must expose two horizontal axes with metre units")
+    if any(
+        axis.unit_conversion_factor is None
+        or not math.isclose(float(axis.unit_conversion_factor), 1.0, rel_tol=0.0, abs_tol=1e-12)
+        for axis in axes
+    ):
+        units = [axis.unit_name for axis in axes]
+        raise ValueError(
+            f"{label} must use metre horizontal units; resolved horizontal units are {units}"
+        )
+    return crs

{spatial_data_foundation-0.1.0 → spatial_data_foundation-0.2.1}/src/spatial_foundation/geography/gadm.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import geopandas as gpd
 
+from ._validation import require_projected_metre_crs
 from .models import GeometryRole, geography_uid
 
 REQUIRED_BASE = {"GID_0"}
@@ -25,8 +26,10 @@ def normalize_gadm_frame(
 
     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.
+    projected metre CRS. The unit check ensures ``area_km2`` is dimensionally valid,
+    but does not by itself claim equal-area scientific accuracy. 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")
@@ -41,6 +44,7 @@ def normalize_gadm_frame(
         raise ValueError(f"missing required GADM columns: {sorted(missing)}")
     if frame.crs is None:
         raise ValueError("GADM source must have a declared CRS")
+    require_projected_metre_crs(area_crs)
 
     source_ids = _require_identity(frame[gid_col], label="source geography identity")
     country_ids = _require_identity(frame["GID_0"], label="country identity")
@@ -53,9 +57,13 @@ def normalize_gadm_frame(
     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))
+    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("")
+        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)
@@ -78,7 +86,9 @@ def normalize_gadm_frame(
     ]
     out = data[keep].copy()
     if out["geo_uid"].duplicated().any():
-        dupes = out.loc[out["geo_uid"].duplicated(keep=False), "geo_uid"].unique().tolist()[:10]
+        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()