spatial-data-foundation 0.1.0__tar.gz

spatial_data_foundation-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,56 @@
+# spatial-data-foundation
+
+Reusable spatial/time infrastructure for research systems.
+
+This repository owns geography authority, period indexing, source registration, auditable spatial membership, and materialization provenance. It does not own FCV treatments, outcomes, matching, survey harmonization, or regressions.
+
+Initial provider: GADM. Initial clients in the next build pack: GHSL and ACLED.
+
+## Operational GADM materialization
+
+After registering local GADM files as an immutable source snapshot, install the IO extra and materialize the native levels needed by downstream work:
+
+```python
+from spatial_foundation import materialize_gadm
+
+materialize_gadm(
+    snapshot=gadm_4_1_snapshot,
+    levels=[0, 1, 2, 3],
+    output_root=data_root,
+)
+```
+
+This publishes full-geometry 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 publication; source drift produces a RED run instead of silently accepting changed bytes.
+
+## 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 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.

spatial_data_foundation-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spatial-data-foundation"
+version = "0.1.0"
+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",
+  "pydantic>=2.7,<3",
+]
+
+[project.optional-dependencies]
+io = ["pyarrow>=15", "duckdb>=1.0"]
+raster = ["rasterio>=1.3"]
+cli = ["typer>=0.12"]
+presentation = [
+  "matplotlib>=3.8",
+  "contextily>=1.7.1,<2",
+  "xyzservices>=2026.3,<2027",
+]
+dev = [
+  "pytest>=8",
+  "ruff>=0.6",
+  "pyarrow>=15",
+  "build>=1.2",
+  "matplotlib>=3.8",
+  "contextily>=1.7.1,<2",
+  "xyzservices>=2026.3,<2027",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spatial_data_foundation-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spatial_data_foundation-0.1.0/src/spatial_data_foundation.egg-info/PKG-INFO

@@ -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/src/spatial_data_foundation.egg-info/SOURCES.txt

@@ -0,0 +1,29 @@
+README.md
+pyproject.toml
+src/spatial_data_foundation.egg-info/PKG-INFO
+src/spatial_data_foundation.egg-info/SOURCES.txt
+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/catalog.py
+src/spatial_foundation/periods.py
+src/spatial_foundation/geography/__init__.py
+src/spatial_foundation/geography/gadm.py
+src/spatial_foundation/geography/materialize.py
+src/spatial_foundation/geography/membership.py
+src/spatial_foundation/geography/models.py
+src/spatial_foundation/geography/overlap.py
+src/spatial_foundation/presentation/__init__.py
+src/spatial_foundation/presentation/basemaps.py
+src/spatial_foundation/presentation/plotting.py
+tests/test_adversarial_spatial.py
+tests/test_areal_overlap.py
+tests/test_catalog.py
+tests/test_distribution.py
+tests/test_external_consumer.py
+tests/test_gadm_materialization.py
+tests/test_geography.py
+tests/test_membership_kernel.py
+tests/test_periods.py
+tests/test_presentation.py

spatial_data_foundation-0.1.0/src/spatial_data_foundation.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

spatial_data_foundation-0.1.0/src/spatial_data_foundation.egg-info/requires.txt

@@ -0,0 +1,29 @@
+empirical-data-contracts<0.2,>=0.1
+geopandas>=0.14
+shapely>=2
+pyproj>=3.5
+pydantic<3,>=2.7
+
+[cli]
+typer>=0.12
+
+[dev]
+pytest>=8
+ruff>=0.6
+pyarrow>=15
+build>=1.2
+matplotlib>=3.8
+contextily<2,>=1.7.1
+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.1.0/src/spatial_data_foundation.egg-info/top_level.txt

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

spatial_data_foundation-0.1.0/src/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_data_foundation-0.1.0/src/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_data_foundation-0.1.0/src/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_data_foundation-0.1.0/src/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