gridforge-spatial 0.1.0__py3-none-any.whl

gridforge/__init__.py

@@ -0,0 +1,10 @@
+"""Deterministic spatial grid alignment and dataset engineering."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gridforge-spatial")
+except PackageNotFoundError:  # pragma: no cover - editable/install builds provide metadata
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

gridforge/align/__init__.py

@@ -0,0 +1 @@
+"""Spatial alignment adapters."""

gridforge/align/points.py

@@ -0,0 +1,172 @@
+"""Deterministic point-to-grid aggregation."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from typing import Literal
+
+import geopandas as gpd
+import numpy as np
+import pandas as pd
+from pyproj import CRS
+from shapely.geometry import Point
+
+from gridforge.errors import DatasetError
+from gridforge.grid.build import get_grid_spec
+
+PointAggregation = Literal["count", "sum", "mean", "min", "max"]
+
+
+def _point_frame(
+    points: gpd.GeoDataFrame | pd.DataFrame,
+    *,
+    x_column: str,
+    y_column: str,
+    source_crs: str | CRS | None,
+) -> gpd.GeoDataFrame:
+    if isinstance(points, gpd.GeoDataFrame):
+        result = points.copy()
+        parsed_source_crs = None
+        if source_crs is not None:
+            try:
+                parsed_source_crs = CRS.from_user_input(source_crs)
+            except Exception as exc:
+                raise DatasetError(f"invalid explicit source CRS: {source_crs!r}") from exc
+        if result.crs is None:
+            if parsed_source_crs is None:
+                raise DatasetError("source CRS is unknown; provide --source-crs explicitly")
+            result = result.set_crs(parsed_source_crs)
+        elif parsed_source_crs is not None and not parsed_source_crs.equals(result.crs):
+            raise DatasetError("explicit source CRS conflicts with embedded CRS")
+        if result.geometry.isna().any() or result.geometry.is_empty.any():
+            raise DatasetError("point dataset contains null or empty geometries")
+        if not result.geometry.geom_type.eq("Point").all():
+            raise DatasetError("point alignment requires Point geometries")
+        coordinates = np.array([(geom.x, geom.y) for geom in result.geometry], dtype=float)
+    else:
+        missing = [name for name in (x_column, y_column) if name not in points.columns]
+        if missing:
+            raise DatasetError(f"point table is missing coordinate column(s): {', '.join(missing)}")
+        if source_crs is None:
+            raise DatasetError("source CRS is unknown; provide --source-crs explicitly")
+        try:
+            parsed_source_crs = CRS.from_user_input(source_crs)
+        except Exception as exc:
+            raise DatasetError(f"invalid explicit source CRS: {source_crs!r}") from exc
+        try:
+            x_values = pd.to_numeric(points[x_column], errors="raise").to_numpy(dtype=float)
+            y_values = pd.to_numeric(points[y_column], errors="raise").to_numpy(dtype=float)
+        except (TypeError, ValueError) as exc:
+            raise DatasetError("point coordinates must be numeric") from exc
+        if not np.isfinite(x_values).all() or not np.isfinite(y_values).all():
+            raise DatasetError("point coordinates must be finite and non-null")
+        result = gpd.GeoDataFrame(
+            points.copy(),
+            geometry=[Point(x, y) for x, y in zip(x_values, y_values, strict=True)],
+            crs=parsed_source_crs,
+        )
+        coordinates = np.column_stack((x_values, y_values))
+    if not np.isfinite(coordinates).all():
+        raise DatasetError("point coordinates must be finite and non-null")
+    return result
+
+
+def _aggregation_list(value: str | Sequence[str]) -> tuple[PointAggregation, ...]:
+    values = [value] if isinstance(value, str) else list(value)
+    allowed = {"count", "sum", "mean", "min", "max"}
+    if not values or any(item not in allowed for item in values):
+        raise DatasetError("point aggregations must be count, sum, mean, min, or max")
+    if len(set(values)) != len(values):
+        raise DatasetError("point aggregations cannot contain duplicates")
+    return tuple(values)  # type: ignore[return-value]
+
+
+def _aggregate(values: pd.Series, operation: PointAggregation) -> int | float | None:
+    present = values.dropna()
+    if operation == "count":
+        return int(len(present))
+    if present.empty:
+        return None
+    try:
+        numeric = pd.to_numeric(present, errors="raise").to_numpy(dtype=float)
+    except (TypeError, ValueError) as exc:
+        raise DatasetError(f"{operation} aggregation requires numeric values") from exc
+    if operation == "sum":
+        return math.fsum(sorted(numeric.tolist()))
+    if operation == "mean":
+        return math.fsum(sorted(numeric.tolist())) / len(numeric)
+    if operation == "min":
+        return float(numeric.min())
+    return float(numeric.max())
+
+
+def align_points(
+    points: gpd.GeoDataFrame | pd.DataFrame,
+    grid: gpd.GeoDataFrame,
+    *,
+    aggregations: Mapping[str, str | Sequence[str]],
+    x_column: str = "x",
+    y_column: str = "y",
+    source_crs: str | CRS | None = None,
+) -> gpd.GeoDataFrame:
+    """Assign points to canonical cells and aggregate requested attributes.
+
+    The returned frame contains every grid cell. ``point_count`` counts valid
+    point records, while empty numeric aggregates and empty-cell values remain
+    null; an empty ``count`` result is zero.
+    """
+    spec = get_grid_spec(grid)
+    if not aggregations:
+        raise DatasetError("at least one value aggregation is required")
+    points_frame = _point_frame(
+        points,
+        x_column=x_column,
+        y_column=y_column,
+        source_crs=source_crs,
+    )
+    for column in aggregations:
+        if column not in points_frame.columns:
+            raise DatasetError(f"point value column does not exist: {column}")
+    try:
+        points_in_grid = points_frame.to_crs(spec.crs)
+    except Exception as exc:
+        raise DatasetError(f"cannot reproject point dataset: {exc}") from exc
+
+    operations = {column: _aggregation_list(value) for column, value in aggregations.items()}
+    output_names = [
+        f"{column}_{operation}" for column, values in operations.items() for operation in values
+    ]
+    if len(output_names) != len(set(output_names)):
+        raise DatasetError("aggregation output column names are not unique")
+    reserved = set(grid.columns) | {"point_count"}
+    collisions = sorted(reserved.intersection(output_names))
+    if collisions:
+        joined = ", ".join(collisions)
+        raise DatasetError(f"aggregation output conflicts with grid columns: {joined}")
+
+    rows_by_cell: dict[str, list[int]] = {str(value): [] for value in grid["grid_id"]}
+    for index, point in enumerate(points_in_grid.geometry):
+        row_column = spec.cell_index(point.x, point.y)
+        if row_column is None:
+            continue
+        row, column = row_column
+        key = f"{row}:{column}"
+        if key in rows_by_cell:
+            rows_by_cell[key].append(index)
+
+    result = grid.copy()
+    point_counts: list[int] = []
+    aggregate_values: dict[str, list[int | float | None]] = {name: [] for name in output_names}
+    for grid_id in result["grid_id"].astype(str):
+        point_indexes = rows_by_cell[grid_id]
+        point_counts.append(len(point_indexes))
+        for value_column, value_operations in operations.items():
+            values = points_in_grid.iloc[point_indexes][value_column]
+            for operation in value_operations:
+                name = f"{value_column}_{operation}"
+                aggregate_values[name].append(_aggregate(values, operation))
+    result["point_count"] = point_counts
+    for name, values in aggregate_values.items():
+        result[name] = values
+    return result

gridforge/align/raster.py

@@ -0,0 +1,129 @@
+"""Raster reprojection and canonical-cell aggregation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import geopandas as gpd
+import numpy as np
+import rasterio
+from affine import Affine
+from pyproj import CRS
+from rasterio.enums import Resampling
+from rasterio.vrt import WarpedVRT
+from rasterio.warp import reproject
+
+from gridforge.errors import DatasetError
+from gridforge.grid.build import get_grid_spec
+from gridforge.io.datasets import _crs_label, _resolved_crs
+
+RasterAggregation = Literal["mean", "min", "max"]
+_AGGREGATION_RESAMPLING = {
+    "mean": Resampling.average,
+    "min": Resampling.min,
+    "max": Resampling.max,
+}
+_REPROJECTION_RESAMPLING = {
+    "nearest": Resampling.nearest,
+    "bilinear": Resampling.bilinear,
+    "cubic": Resampling.cubic,
+}
+
+
+def align_raster(
+    path: str | Path,
+    grid: gpd.GeoDataFrame,
+    *,
+    aggregation: RasterAggregation,
+    band: int = 1,
+    source_crs: str | CRS | None = None,
+    resampling: str | None = None,
+    value_name: str | None = None,
+) -> gpd.GeoDataFrame:
+    """Warp a raster to the grid CRS, then aggregate valid pixels per cell.
+
+    Reprojection uses ``nearest`` by default, or the explicitly selected
+    ``nearest``, ``bilinear``, or ``cubic`` method. Cell aggregation is a
+    separate, documented mapping: mean→average, min→min, max→max. Nodata and
+    cells outside the source footprint remain NaN.
+    """
+    if aggregation not in _AGGREGATION_RESAMPLING:
+        raise DatasetError("aggregation must be mean, min, or max")
+    selected_resampling = resampling or "nearest"
+    if selected_resampling not in _REPROJECTION_RESAMPLING:
+        allowed = ", ".join(_REPROJECTION_RESAMPLING)
+        raise DatasetError(f"resampling must be one of: {allowed}")
+    if band < 1:
+        raise DatasetError("band index must be a positive one-based integer")
+
+    spec = get_grid_spec(grid)
+    input_path = Path(path)
+    output_name = value_name or input_path.stem
+    if not output_name or output_name in grid.columns:
+        raise DatasetError("raster value_name must be nonempty and cannot match a grid column")
+    output_column = f"{output_name}_{aggregation}"
+    if output_column in grid.columns:
+        raise DatasetError(f"raster output column conflicts with grid: {output_column}")
+
+    row_start, row_end, col_start, col_end = spec.index_extent
+    width = col_end - col_start + 1
+    height = row_end - row_start + 1
+    left = spec.origin.x + col_start * spec.cell_size
+    top = spec.origin.y - row_start * spec.cell_size
+    cell_size = float(spec.cell_size)
+    target_transform = Affine.translation(float(left), float(top)) @ Affine.scale(
+        cell_size, -cell_size
+    )
+    destination = np.full((height, width), np.nan, dtype="float64")
+    source_nodata: float | int | None = None
+
+    try:
+        with rasterio.open(input_path) as source:
+            resolved_crs = _resolved_crs(source.crs, source_crs)
+            source_nodata = source.nodata
+            if band > source.count:
+                raise DatasetError(f"band index {band} exceeds raster band count {source.count}")
+            with WarpedVRT(
+                source,
+                src_crs=resolved_crs,
+                crs=spec.crs,
+                resampling=_REPROJECTION_RESAMPLING[selected_resampling],
+                nodata=np.nan,
+                dtype="float64",
+                init_dest_nodata=True,
+            ) as warped:
+                reproject(
+                    source=rasterio.band(warped, band),
+                    destination=destination,
+                    src_transform=warped.transform,
+                    src_crs=warped.crs,
+                    src_nodata=warped.nodata,
+                    dst_transform=target_transform,
+                    dst_crs=spec.crs,
+                    dst_nodata=np.nan,
+                    resampling=_AGGREGATION_RESAMPLING[aggregation],
+                    init_dest_nodata=True,
+                )
+    except DatasetError:
+        raise
+    except Exception as exc:
+        raise DatasetError(f"cannot align raster {input_path}: {exc}") from exc
+
+    result = grid.copy()
+    result[output_column] = destination.reshape(-1)
+    result.attrs["gridforge_operation"] = {
+        "operation": "raster_alignment",
+        "source": str(input_path),
+        "source_crs": _crs_label(resolved_crs),
+        "target_crs": spec.crs_id,
+        "grid_fingerprint": spec.fingerprint,
+        "grid_spec": spec.to_dict(),
+        "aggregation": aggregation,
+        "aggregation_resampling": _AGGREGATION_RESAMPLING[aggregation].name,
+        "resampling": selected_resampling,
+        "band": band,
+        "nodata": None if source_nodata is None else str(source_nodata),
+        "output_column": output_column,
+    }
+    return result

gridforge/align/vector.py

@@ -0,0 +1,204 @@
+"""Polygon-to-grid area coverage and attribute aggregation."""
+
+from __future__ import annotations
+
+import math
+import unicodedata
+from collections import defaultdict
+from collections.abc import Sequence
+from urllib.parse import quote
+
+import geopandas as gpd
+import pandas as pd
+from pyproj import CRS
+from shapely.geometry import MultiPolygon, Polygon
+from shapely.ops import unary_union
+
+from gridforge.errors import DatasetError
+from gridforge.grid.build import get_grid_spec
+from gridforge.io.datasets import _resolved_crs
+
+
+def _category_name(value: object) -> str:
+    return unicodedata.normalize("NFC", str(value)).strip()
+
+
+def _category_column(category_column: str, category: str) -> str:
+    encoded = quote(category, safe="") or "%00"
+    return f"{category_column}__{encoded}__coverage_ratio"
+
+
+def _normalize_polygons(
+    polygons: gpd.GeoDataFrame,
+    *,
+    target_crs: CRS,
+    source_crs: str | CRS | None,
+) -> gpd.GeoDataFrame:
+    if not isinstance(polygons, gpd.GeoDataFrame):
+        raise DatasetError("polygon alignment requires a GeoDataFrame")
+    crs = _resolved_crs(polygons.crs, source_crs)
+    result = polygons.set_crs(crs) if polygons.crs is None else polygons.copy()
+    if result.empty:
+        try:
+            return result.to_crs(target_crs)
+        except Exception as exc:
+            raise DatasetError(f"cannot reproject polygon dataset: {exc}") from exc
+    if result.geometry.isna().any() or result.geometry.is_empty.any():
+        raise DatasetError("polygon dataset contains null or empty geometries")
+    supported = result.geometry.geom_type.isin(["Polygon", "MultiPolygon"])
+    if not supported.all():
+        raise DatasetError("polygon alignment requires Polygon or MultiPolygon geometries")
+    valid = result.geometry.is_valid
+    if not valid.all():
+        invalid_count = int((~valid).sum())
+        raise DatasetError(
+            f"polygon dataset contains {invalid_count} invalid polygon geometry row(s)"
+        )
+    try:
+        return result.to_crs(target_crs)
+    except Exception as exc:
+        raise DatasetError(f"cannot reproject polygon dataset: {exc}") from exc
+
+
+def _numeric_values(polygons: gpd.GeoDataFrame, column: str) -> pd.Series:
+    try:
+        return pd.to_numeric(polygons[column], errors="raise")
+    except (TypeError, ValueError) as exc:
+        raise DatasetError(f"polygon numeric column must contain numeric values: {column}") from exc
+
+
+def align_polygons(
+    polygons: gpd.GeoDataFrame,
+    grid: gpd.GeoDataFrame,
+    *,
+    category_column: str | None = None,
+    numeric_columns: Sequence[str] = (),
+    source_crs: str | CRS | None = None,
+) -> gpd.GeoDataFrame:
+    """Aggregate polygon intersections to a complete canonical grid.
+
+    Unique coverage is the area of the union of intersections divided by the
+    cell area. Category coverage uses a union independently per category;
+    overlapping categories may therefore have ratios whose sum exceeds one.
+    Numeric weighted means weight each feature value by its intersection area.
+    """
+    spec = get_grid_spec(grid)
+    required = list(numeric_columns)
+    if category_column is not None:
+        required.append(category_column)
+    missing = sorted(set(required) - set(polygons.columns))
+    if missing:
+        raise DatasetError(f"polygon dataset is missing attribute column(s): {', '.join(missing)}")
+    if len(set(numeric_columns)) != len(numeric_columns):
+        raise DatasetError("numeric_columns cannot contain duplicates")
+
+    source = _normalize_polygons(
+        polygons,
+        target_crs=spec.crs,
+        source_crs=source_crs,
+    )
+    numeric = {column: _numeric_values(source, column) for column in numeric_columns}
+
+    categories: list[str] = []
+    category_by_row: dict[int, str] = {}
+    if category_column is not None:
+        for position, value in enumerate(source[category_column].tolist()):
+            if pd.isna(value):
+                continue
+            category = _category_name(value)
+            categories.append(category)
+            category_by_row[position] = category
+    category_values = sorted(set(categories))
+    category_outputs = {
+        category: _category_column(category_column or "category", category)
+        for category in category_values
+    }
+    if len(set(category_outputs.values())) != len(category_outputs):
+        raise DatasetError("normalized category names produce duplicate output columns")
+
+    output_names = ["polygon_count", "polygon_coverage_ratio"]
+    if category_column is not None:
+        output_names.append(f"dominant_{category_column}")
+        output_names.extend(category_outputs.values())
+    output_names.extend(f"{column}_weighted_mean" for column in numeric_columns)
+    if len(set(output_names)) != len(output_names):
+        raise DatasetError("polygon aggregation output column names are not unique")
+    collisions = sorted(set(output_names).intersection(grid.columns))
+    if collisions:
+        raise DatasetError(f"polygon output conflicts with grid columns: {', '.join(collisions)}")
+
+    spatial_index = source.sindex if not source.empty else None
+    result = grid.copy()
+    polygon_counts: list[int] = []
+    coverage_values: list[float] = []
+    dominant_values: list[str | None] = []
+    category_ratios: dict[str, list[float]] = {category: [] for category in category_values}
+    weighted_values: dict[str, list[float | None]] = {column: [] for column in numeric_columns}
+
+    for cell in grid.geometry:
+        if spatial_index is None:
+            candidate_indexes = []
+        else:
+            candidate_indexes = sorted(spatial_index.query(cell, predicate="intersects").tolist())
+        intersection_geometries = []
+        category_geometries: dict[str, list[Polygon | MultiPolygon]] = defaultdict(list)
+        weighted_pairs: dict[str, list[tuple[float, float]]] = defaultdict(list)
+        intersecting_features = 0
+        for position in candidate_indexes:
+            intersection = source.geometry.iloc[position].intersection(cell)
+            area = float(intersection.area)
+            if intersection.is_empty or area <= 0.0:
+                continue
+            intersecting_features += 1
+            intersection_geometries.append(intersection)
+            category = category_by_row.get(position)
+            if category is not None:
+                category_geometries[category].append(intersection)
+            for column in numeric_columns:
+                value = numeric[column].iloc[position]
+                if pd.notna(value):
+                    weighted_pairs[column].append((float(value), area))
+
+        cell_area = float(cell.area)
+        if cell_area <= 0.0:
+            raise DatasetError("canonical grid contains a cell with nonpositive area")
+        union_area = (
+            float(unary_union(intersection_geometries).area) if intersection_geometries else 0.0
+        )
+        coverage_values.append(min(max(union_area / cell_area, 0.0), 1.0))
+        polygon_counts.append(intersecting_features)
+
+        if category_column is not None:
+            areas = {
+                category: float(unary_union(category_geometries[category]).area)
+                if category_geometries[category]
+                else 0.0
+                for category in category_values
+            }
+            for category in category_values:
+                category_ratios[category].append(min(max(areas[category] / cell_area, 0.0), 1.0))
+            present_categories = [category for category in category_values if areas[category] > 0]
+            dominant_values.append(
+                min(present_categories, key=lambda category: (-areas[category], category))
+                if present_categories
+                else None
+            )
+
+        for column in numeric_columns:
+            pairs = sorted(weighted_pairs[column])
+            total_area = math.fsum(area for _, area in pairs)
+            if total_area == 0:
+                weighted_values[column].append(None)
+            else:
+                numerator = math.fsum(value * area for value, area in pairs)
+                weighted_values[column].append(numerator / total_area)
+
+    result["polygon_count"] = polygon_counts
+    result["polygon_coverage_ratio"] = coverage_values
+    if category_column is not None:
+        result[f"dominant_{category_column}"] = dominant_values
+        for category, column in category_outputs.items():
+            result[column] = category_ratios[category]
+    for column, values in weighted_values.items():
+        result[f"{column}_weighted_mean"] = values
+    return result