gridforge-spatial 0.1.0__py3-none-any.whl

gridforge/cli.py

@@ -0,0 +1,345 @@
+"""Command-line entry point for GridForge."""
+
+# Typer expresses command parameters using function-call defaults.
+# ruff: noqa: B008
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import geopandas as gpd
+import typer
+from pyproj import CRS
+
+from gridforge import __version__
+from gridforge.align.points import align_points
+from gridforge.align.raster import align_raster
+from gridforge.align.vector import align_polygons
+from gridforge.demo import run_demo
+from gridforge.errors import GridForgeError
+from gridforge.grid.build import create_grid
+from gridforge.grid.spec import GridSpec
+from gridforge.io.datasets import (
+    _crs_label,
+    inspect_dataset,
+    load_points,
+    load_vector,
+    read_dataset,
+    write_dataset,
+)
+from gridforge.io.grid import read_grid, write_grid
+from gridforge.join import join_features
+from gridforge.provenance import write_provenance
+from gridforge.validation import validate_dataset
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Build, align, join, and validate spatial grid datasets.",
+)
+grid_app = typer.Typer(no_args_is_help=True, help="Create canonical grids.")
+align_app = typer.Typer(no_args_is_help=True, help="Align source data to a canonical grid.")
+app.add_typer(grid_app, name="grid")
+app.add_typer(align_app, name="align")
+
+
+def _show_version(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_show_version,
+        is_eager=True,
+        help="Show the installed GridForge version and exit.",
+    ),
+) -> None:
+    """Create and validate deterministic grid-based spatial datasets."""
+
+
+def _run(action):
+    try:
+        return action()
+    except (GridForgeError, OSError) as exc:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+
+def _crs_arg(crs: Any) -> str | None:
+    if crs is None:
+        return None
+    return _crs_label(CRS.from_user_input(crs))
+
+
+def _print_json(value: Any) -> None:
+    typer.echo(json.dumps(value, ensure_ascii=False, indent=2, default=str))
+
+
+def _write_aligned(
+    dataset: gpd.GeoDataFrame,
+    output: Path,
+    *,
+    operation: str,
+    source: str | list[str],
+    grid: gpd.GeoDataFrame,
+    parameters: dict[str, Any],
+) -> None:
+    write_dataset(dataset, output)
+    write_provenance(
+        output,
+        operation=operation,
+        source=source,
+        grid=grid,
+        parameters=parameters,
+    )
+    typer.echo(f"Wrote {output}")
+    typer.echo(f"Wrote {output}.gridforge.json")
+
+
+@app.command("inspect")
+def inspect_command(
+    source: Path = typer.Argument(..., exists=True, readable=True),
+    source_crs: str | None = typer.Option(None, "--source-crs"),
+    x_column: str = typer.Option("x", "--x-column"),
+    y_column: str = typer.Option("y", "--y-column"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Inspect spatial metadata without guessing a missing source CRS."""
+    info = _run(
+        lambda: inspect_dataset(
+            source,
+            source_crs=source_crs,
+            x_column=x_column,
+            y_column=y_column,
+        )
+    )
+    if json_output:
+        _print_json(info.to_dict())
+        return
+    typer.echo(f"Path: {info.path}")
+    typer.echo(f"Kind: {info.kind}")
+    typer.echo(f"Geometry: {info.geometry_type or 'unknown'}")
+    typer.echo(f"CRS: {info.crs}")
+    typer.echo(f"Features: {info.feature_count if info.feature_count is not None else 'n/a'}")
+    typer.echo(f"Bands: {info.band_count if info.band_count is not None else 'n/a'}")
+    typer.echo(f"Bounds: {info.bounds if info.bounds is not None else 'n/a'}")
+
+
+@grid_app.command("create")
+def grid_create(
+    specification: Path = typer.Argument(..., exists=True, readable=True),
+    output: Path = typer.Option(..., "--output", "-o"),
+) -> None:
+    """Create a deterministic GeoParquet grid from a YAML specification."""
+
+    def action() -> None:
+        spec = GridSpec.from_yaml(specification)
+        grid = create_grid(spec)
+        write_grid(grid, output)
+        write_provenance(
+            output,
+            operation="grid_build",
+            source=str(specification),
+            grid=grid,
+            parameters={"grid_spec": spec.to_dict()},
+        )
+        typer.echo(f"Created {len(grid)} cells: {output}")
+        typer.echo(f"Wrote {output}.gridforge.json")
+
+    _run(action)
+
+
+@align_app.command("points")
+def align_points_command(
+    source: Path = typer.Argument(..., exists=True, readable=True),
+    grid_path: Path = typer.Option(..., "--grid"),
+    value: str = typer.Option(..., "--value"),
+    aggregation: str = typer.Option("mean", "--agg"),
+    output: Path = typer.Option(..., "--output", "-o"),
+    source_crs: str | None = typer.Option(None, "--source-crs"),
+    x_column: str = typer.Option("x", "--x-column"),
+    y_column: str = typer.Option("y", "--y-column"),
+) -> None:
+    """Aggregate one point attribute into canonical cells."""
+
+    def action() -> None:
+        grid = read_grid(grid_path)
+        points = load_points(
+            source,
+            x_column=x_column,
+            y_column=y_column,
+            source_crs=source_crs,
+        )
+        result = align_points(
+            points,
+            grid,
+            aggregations={value: aggregation},
+            source_crs=source_crs,
+        )
+        _write_aligned(
+            result,
+            output,
+            operation="point_alignment",
+            source=str(source),
+            grid=grid,
+            parameters={
+                "source_crs": _crs_arg(points.crs),
+                "target_crs": _crs_arg(grid.crs),
+                "x_column": x_column,
+                "y_column": y_column,
+                "aggregation": {value: aggregation},
+            },
+        )
+
+    _run(action)
+
+
+@align_app.command("vector")
+def align_vector_command(
+    source: Path = typer.Argument(..., exists=True, readable=True),
+    grid_path: Path = typer.Option(..., "--grid"),
+    output: Path = typer.Option(..., "--output", "-o"),
+    category: str | None = typer.Option(None, "--category"),
+    numeric_column: list[str] = typer.Option([], "--numeric-column"),
+    source_crs: str | None = typer.Option(None, "--source-crs"),
+) -> None:
+    """Aggregate polygon coverage, categories, and numeric attributes."""
+
+    def action() -> None:
+        grid = read_grid(grid_path)
+        vector = load_vector(source, source_crs=source_crs)
+        result = align_polygons(
+            vector,
+            grid,
+            category_column=category,
+            numeric_columns=numeric_column,
+            source_crs=source_crs,
+        )
+        _write_aligned(
+            result,
+            output,
+            operation="vector_alignment",
+            source=str(source),
+            grid=grid,
+            parameters={
+                "source_crs": _crs_arg(vector.crs),
+                "target_crs": _crs_arg(grid.crs),
+                "category_column": category,
+                "numeric_columns": numeric_column,
+                "coverage": "union area / cell area",
+                "weighted_aggregation": "intersection-area weighted mean",
+            },
+        )
+
+    _run(action)
+
+
+@align_app.command("raster")
+def align_raster_command(
+    source: Path = typer.Argument(..., exists=True, readable=True),
+    grid_path: Path = typer.Option(..., "--grid"),
+    aggregation: str = typer.Option(..., "--agg"),
+    output: Path = typer.Option(..., "--output", "-o"),
+    band: int = typer.Option(1, "--band", min=1),
+    source_crs: str | None = typer.Option(None, "--source-crs"),
+    resampling: str = typer.Option("nearest", "--resampling"),
+    value_name: str | None = typer.Option(None, "--value-name"),
+) -> None:
+    """Reproject and aggregate one raster band into canonical cells."""
+
+    def action() -> None:
+        grid = read_grid(grid_path)
+        result = align_raster(
+            source,
+            grid,
+            aggregation=aggregation,
+            band=band,
+            source_crs=source_crs,
+            resampling=resampling,
+            value_name=value_name,
+        )
+        operation = result.attrs.get("gridforge_operation", {})
+        _write_aligned(
+            result,
+            output,
+            operation="raster_alignment",
+            source=str(source),
+            grid=grid,
+            parameters={
+                "source_crs": operation.get("source_crs"),
+                "target_crs": operation.get("target_crs"),
+                "band": band,
+                "aggregation": aggregation,
+                "aggregation_resampling": operation.get("aggregation_resampling"),
+                "resampling": resampling,
+                "nodata": operation.get("nodata"),
+            },
+        )
+
+    _run(action)
+
+
+@app.command("join")
+def join_command(
+    grid_path: Path = typer.Argument(..., exists=True, readable=True),
+    feature_paths: list[Path] = typer.Argument(..., exists=True, readable=True),
+    output: Path = typer.Option(..., "--output", "-o"),
+) -> None:
+    """Join aligned GeoParquet feature datasets after identity validation."""
+
+    def action() -> None:
+        grid = read_grid(grid_path)
+        features = [read_dataset(path) for path in feature_paths]
+        result = join_features(grid, *features)
+        _write_aligned(
+            result,
+            output,
+            operation="feature_join",
+            source=[str(grid_path), *(str(path) for path in feature_paths)],
+            grid=grid,
+            parameters={"feature_datasets": len(features)},
+        )
+
+    _run(action)
+
+
+@app.command("validate")
+def validate_command(
+    dataset_path: Path = typer.Argument(..., exists=True, readable=True),
+    grid_path: Path | None = typer.Option(None, "--grid"),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Validate one GridForge GeoParquet dataset; errors exit with status 2."""
+
+    def action():
+        dataset = read_dataset(dataset_path)
+        grid = read_grid(grid_path) if grid_path is not None else None
+        return validate_dataset(dataset, grid=grid)
+
+    report = _run(action)
+    if json_output:
+        _print_json(report.to_dict())
+    else:
+        typer.echo(report.status)
+        for finding in report.findings:
+            count = f" ({finding.count})" if finding.count is not None else ""
+            typer.echo(f"{finding.severity}: {finding.message}{count}")
+    if report.exit_code:
+        raise typer.Exit(code=report.exit_code)
+
+
+@app.command("demo")
+def demo_command(
+    output_dir: Path = typer.Option(Path("gridforge-demo"), "--output-dir"),
+) -> None:
+    """Run a small, synthetic point/vector/raster-to-grid workflow."""
+    report = _run(lambda: run_demo(output_dir))
+    _print_json(report.to_dict())
+    typer.echo(f"Demo complete: {output_dir.resolve()}")

gridforge/demo.py

@@ -0,0 +1,173 @@
+"""Synthetic end-to-end workflow for the GridForge command-line demo."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import geopandas as gpd
+import numpy as np
+import pandas as pd
+import rasterio
+from affine import Affine
+from shapely.geometry import box
+
+from gridforge.align.points import align_points
+from gridforge.align.raster import align_raster
+from gridforge.align.vector import align_polygons
+from gridforge.errors import DatasetError
+from gridforge.grid.build import create_grid
+from gridforge.grid.spec import GridSpec
+from gridforge.io.datasets import load_points, write_dataset
+from gridforge.io.grid import write_grid
+from gridforge.join import join_features
+from gridforge.provenance import write_provenance
+from gridforge.validation import ValidationReport, validate_dataset
+
+
+def _write_aligned(
+    dataset: gpd.GeoDataFrame,
+    path: Path,
+    *,
+    operation: str,
+    source: str | list[str],
+    grid: gpd.GeoDataFrame,
+    parameters: dict[str, object],
+) -> None:
+    write_dataset(dataset, path)
+    write_provenance(
+        path,
+        operation=operation,
+        source=source,
+        grid=grid,
+        parameters=parameters,
+    )
+
+
+def run_demo(output_dir: str | Path) -> ValidationReport:
+    """Create synthetic spatial inputs and run the complete v0.1 workflow."""
+    directory = Path(output_dir)
+    directory.mkdir(parents=True, exist_ok=True)
+    specification_path = directory / "grid.yaml"
+    specification_path.write_text(
+        """crs: EPSG:3857
+cell_size: 20
+bounds:
+  min_x: 0
+  min_y: 0
+  max_x: 80
+  max_y: 80
+origin:
+  x: 0
+  y: 80
+""",
+        encoding="utf-8",
+    )
+    spec = GridSpec.from_yaml(specification_path)
+    grid = create_grid(spec)
+    grid_path = directory / "grid.parquet"
+    write_grid(grid, grid_path)
+    write_provenance(
+        grid_path,
+        operation="grid_build",
+        source=str(specification_path),
+        grid=grid,
+        parameters={"grid_spec": spec.to_dict()},
+    )
+
+    points_path = directory / "points.csv"
+    pd.DataFrame(
+        {
+            "station": ["P-01", "P-02", "P-03"],
+            "x": [10.0, 30.0, 70.0],
+            "y": [70.0, 50.0, 10.0],
+            "rainfall_mm": [12.0, 18.0, 9.0],
+        }
+    ).to_csv(points_path, index=False)
+    point_frame = load_points(points_path, source_crs="EPSG:3857")
+    point_output = directory / "rainfall.parquet"
+    point_result = align_points(
+        point_frame,
+        grid,
+        aggregations={"rainfall_mm": "mean"},
+    )
+    _write_aligned(
+        point_result,
+        point_output,
+        operation="point_alignment",
+        source=str(points_path),
+        grid=grid,
+        parameters={"source_crs": "EPSG:3857", "aggregation": {"rainfall_mm": "mean"}},
+    )
+
+    polygon_path = directory / "landuse.geojson"
+    polygons = gpd.GeoDataFrame(
+        {"landuse": ["park", "built"], "impervious": [0.1, 0.9]},
+        geometry=[box(0, 40, 40, 80), box(40, 0, 80, 40)],
+        crs="EPSG:3857",
+    )
+    polygons.to_file(polygon_path, driver="GeoJSON")
+    polygon_output = directory / "landuse.parquet"
+    polygon_result = align_polygons(
+        polygons,
+        grid,
+        category_column="landuse",
+        numeric_columns=("impervious",),
+    )
+    _write_aligned(
+        polygon_result,
+        polygon_output,
+        operation="vector_alignment",
+        source=str(polygon_path),
+        grid=grid,
+        parameters={
+            "source_crs": "EPSG:3857",
+            "category_column": "landuse",
+            "numeric_columns": ["impervious"],
+        },
+    )
+
+    raster_path = directory / "elevation.tif"
+    transform = Affine.translation(0, 80) @ Affine.scale(20, -20)
+    with rasterio.open(
+        raster_path,
+        "w",
+        driver="GTiff",
+        height=4,
+        width=4,
+        count=1,
+        dtype="float32",
+        crs="EPSG:3857",
+        transform=transform,
+        nodata=-9999.0,
+    ) as raster:
+        raster.write(np.arange(16, dtype="float32").reshape(4, 4), 1)
+    raster_output = directory / "elevation.parquet"
+    raster_result = align_raster(raster_path, grid, aggregation="mean")
+    _write_aligned(
+        raster_result,
+        raster_output,
+        operation="raster_alignment",
+        source=str(raster_path),
+        grid=grid,
+        parameters={
+            "source_crs": "EPSG:3857",
+            "aggregation": "mean",
+            "resampling": "nearest",
+            "band": 1,
+        },
+    )
+
+    joined = join_features(grid, point_result, polygon_result, raster_result)
+    joined_path = directory / "features.parquet"
+    _write_aligned(
+        joined,
+        joined_path,
+        operation="feature_join",
+        source=[str(point_output), str(polygon_output), str(raster_output)],
+        grid=grid,
+        parameters={"feature_datasets": 3},
+    )
+    report = validate_dataset(joined, grid=grid)
+    if report.exit_code:
+        raise DatasetError("synthetic demo output did not pass validation")
+    return report

gridforge/errors.py

@@ -0,0 +1,13 @@
+"""Domain exceptions raised by GridForge."""
+
+
+class GridForgeError(Exception):
+    """Base class for expected GridForge errors."""
+
+
+class GridSpecError(GridForgeError, ValueError):
+    """A canonical grid specification is invalid."""
+
+
+class DatasetError(GridForgeError, ValueError):
+    """An input or output dataset violates its declared contract."""

gridforge/grid/__init__.py

@@ -0,0 +1,6 @@
+"""Canonical grid specification and construction."""
+
+from gridforge.grid.build import create_grid, get_grid_spec
+from gridforge.grid.spec import GridSpec
+
+__all__ = ["GridSpec", "create_grid", "get_grid_spec"]

gridforge/grid/build.py

@@ -0,0 +1,57 @@
+"""Build canonical cell geometries and stable per-cell identifiers."""
+
+from __future__ import annotations
+
+import geopandas as gpd
+from shapely.geometry import box
+
+from gridforge.errors import DatasetError
+from gridforge.grid.spec import GridSpec
+
+
+def create_grid(spec: GridSpec) -> gpd.GeoDataFrame:
+    """Create every canonical cell intersecting the requested bounds."""
+    row_start, row_end, col_start, col_end = spec.index_extent
+    rows: list[dict[str, object]] = []
+    for row in range(row_start, row_end + 1):
+        top_decimal = spec.origin.y - row * spec.cell_size
+        bottom_decimal = top_decimal - spec.cell_size
+        top = float(top_decimal)
+        bottom = float(bottom_decimal)
+        for column in range(col_start, col_end + 1):
+            left_decimal = spec.origin.x + column * spec.cell_size
+            right_decimal = left_decimal + spec.cell_size
+            left = float(left_decimal)
+            right = float(right_decimal)
+            rows.append(
+                {
+                    "grid_id": f"{row}:{column}",
+                    "grid_fingerprint": spec.fingerprint,
+                    "row": row,
+                    "column": column,
+                    "left": left,
+                    "bottom": bottom,
+                    "right": right,
+                    "top": top,
+                    "geometry": box(left, bottom, right, top),
+                }
+            )
+    grid = gpd.GeoDataFrame(rows, geometry="geometry", crs=spec.crs)
+    grid.attrs["gridforge_spec"] = spec.to_dict()
+    return grid
+
+
+def get_grid_spec(grid: gpd.GeoDataFrame) -> GridSpec:
+    """Recover and verify the GridForge spec attached to a canonical grid."""
+    value = grid.attrs.get("gridforge_spec")
+    if value is None:
+        raise DatasetError("grid is missing GridForge specification metadata")
+    try:
+        spec = GridSpec.from_mapping(value)
+    except ValueError as exc:
+        raise DatasetError(f"grid specification metadata is invalid: {exc}") from exc
+    if grid.crs is None or not spec.crs.equals(grid.crs):
+        raise DatasetError("grid CRS does not match GridForge specification")
+    if "grid_fingerprint" not in grid or not grid["grid_fingerprint"].eq(spec.fingerprint).all():
+        raise DatasetError("grid fingerprint does not match GridForge specification")
+    return spec