sameer-graph-lib 0.1.0__py3-none-any.whl

sameer_graph_lib/corridor_extractor.py

@@ -0,0 +1,82 @@
+"""Dominant route corridor extraction."""
+
+from __future__ import annotations
+
+from typing import List, Sequence
+
+import networkx as nx
+
+
+class CorridorExtractor:
+    """Extract compact Dijkstra clusters that cover a target metric share."""
+
+    def __init__(self, graph_or_affinity) -> None:
+        self.graph = graph_or_affinity if isinstance(graph_or_affinity, nx.Graph) else graph_or_affinity.graph
+
+    def extract_x_percent_corridor(
+        self,
+        target_pct: float = 0.8,
+        weight_attr: str = "count",
+        seed_hexes: Sequence[str] | None = None,
+    ) -> List[str]:
+        del seed_hexes
+
+        if self.graph.number_of_nodes() == 0:
+            return []
+        if self.graph.number_of_nodes() <= 2:
+            return list(self.graph.nodes)
+
+        pct = self._normalize_pct(target_pct)
+        total = self._total_metric(weight_attr)
+        if total <= 0:
+            return list(self.graph.nodes)
+
+        target = total * pct
+        best_hexes = None
+        best_score = float("inf")
+        best_accumulated = 0.0
+
+        for center in self.graph.nodes:
+            try:
+                distances = nx.single_source_dijkstra_path_length(
+                    self.graph,
+                    center,
+                    weight="weight",
+                )
+            except Exception:
+                continue
+
+            selected = []
+            accumulated = 0.0
+            path_sum = 0.0
+            for node, distance in sorted(distances.items(), key=lambda item: item[1]):
+                selected.append(node)
+                accumulated += self._metric(node, weight_attr)
+                path_sum += float(distance or 0)
+                if accumulated >= target:
+                    break
+
+            if accumulated >= target and (
+                path_sum < best_score
+                or (path_sum == best_score and accumulated > best_accumulated)
+            ):
+                best_score = path_sum
+                best_accumulated = accumulated
+                best_hexes = selected[:]
+
+        return best_hexes if best_hexes else list(self.graph.nodes)
+
+    @staticmethod
+    def _normalize_pct(target_pct: float) -> float:
+        pct = float(target_pct)
+        if pct > 1:
+            pct = pct / 100.0
+        if pct <= 0 or pct > 1:
+            raise ValueError("target_pct must be in the range (0, 1] or (0, 100].")
+        return pct
+
+    def _total_metric(self, weight_attr: str) -> float:
+        return sum(self._metric(node, weight_attr) for node in self.graph.nodes)
+
+    def _metric(self, node: str, weight_attr: str) -> float:
+        return float(self.graph.nodes[node].get(weight_attr, 0) or 0)

sameer_graph_lib/geometry.py

@@ -0,0 +1,75 @@
+"""Geometry helpers for H3 cell collections."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ._h3 import cell_to_latlng, is_valid_cell
+from .plotting import normalize_cells
+
+
+def get_latlng(cells: str | Iterable[str]) -> list[tuple[float, float]]:
+    """Return H3 cell centers as ``(lat, lng)`` tuples."""
+    hexes = normalize_cells(cells)
+    invalid = [cell for cell in hexes if not is_valid_cell(cell)]
+    if invalid:
+        raise ValueError(f"Invalid H3 cell(s): {', '.join(invalid[:3])}")
+    return [cell_to_latlng(cell) for cell in hexes]
+
+
+def get_lnglat(cells: str | Iterable[str]) -> list[tuple[float, float]]:
+    """Return H3 cell centers as Shapely-friendly ``(lng, lat)`` tuples."""
+    return [(lng, lat) for lat, lng in get_latlng(cells)]
+
+
+def making_hull(points: Iterable[tuple[float, float]]):
+    """Return the convex hull for input points.
+
+    The expected coordinate order is ``(lat, lng)`` to match your current
+    helper. The returned Shapely geometry uses standard ``(lng, lat)`` order.
+    """
+    try:
+        from shapely.geometry import MultiPoint, Point
+    except ImportError as exc:
+        raise ImportError(
+            "Convex hull helpers require the geo extra: "
+            "pip install 'sameer-graph-lib[geo]'"
+        ) from exc
+
+    coords = list(points)
+    if not coords:
+        return None
+
+    lnglat = [(lng, lat) for lat, lng in coords]
+    if len(lnglat) == 1:
+        return Point(lnglat[0])
+
+    return MultiPoint(lnglat).convex_hull
+
+
+def h3_convex_hull(cells: str | Iterable[str]):
+    """Return a Shapely convex hull around H3 cell centers."""
+    return making_hull(get_latlng(cells))
+
+
+def h3_convex_hull_geojson(cells: str | Iterable[str]) -> dict | None:
+    """Return the H3 center convex hull as a GeoJSON-like mapping."""
+    hull = h3_convex_hull(cells)
+    if hull is None:
+        return None
+
+    try:
+        from shapely.geometry import mapping
+    except ImportError as exc:
+        raise ImportError(
+            "Convex hull helpers require the geo extra: "
+            "pip install 'sameer-graph-lib[geo]'"
+        ) from exc
+
+    return mapping(hull)
+
+
+# Backwards-compatible aliases matching the user's current helper names.
+getLatLng = get_latlng
+makingHull = making_hull
+

sameer_graph_lib/hex_graph.py

@@ -0,0 +1,15 @@
+"""Backwards-compatible HexGraph facade."""
+
+from __future__ import annotations
+
+from .affinity_graph import AffinityGraph
+
+
+class HexGraph(AffinityGraph):
+    """Compatibility wrapper around :class:`AffinityGraph`.
+
+    The original single-class API is still available through this name, with
+    additional route ingestion, corridor extraction, branch decomposition,
+    editing helpers, and JSON persistence inherited from ``AffinityGraph``.
+    """
+

sameer_graph_lib/plotting.py

@@ -0,0 +1,211 @@
+"""Geospatial plotting helpers for H3 cells."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Sequence
+
+from ._h3 import cell_to_boundary, cell_to_latlng, is_valid_cell
+
+
+def normalize_cells(cells: str | Iterable[str]) -> list[str]:
+    if isinstance(cells, str):
+        if "," in cells:
+            return [cell.strip() for cell in cells.split(",") if cell.strip()]
+        return [cells]
+    return [str(cell).strip() for cell in cells if str(cell).strip()]
+
+
+def plot_h3_cells(
+    cells: str | Iterable[str],
+    *,
+    title: str = "H3 Cells",
+    ax=None,
+    figsize: tuple[float, float] = (10, 8),
+    face_color: str = "#3498db",
+    edge_color: str = "#1f2d3d",
+    selected_cells: str | Iterable[str] | None = None,
+    selected_face_color: str = "#2ecc71",
+    alpha: float = 0.45,
+    linewidth: float = 1.2,
+    show_labels: bool = True,
+    label_full_hex: bool = False,
+    show_centers: bool = False,
+    equal_aspect: bool = True,
+):
+    """Plot one H3 cell or an iterable/comma string of H3 cells as polygons.
+
+    Returns the Matplotlib ``Figure`` object. The axes use longitude on X and
+    latitude on Y, so the plot can be inspected as a geospatial footprint.
+    """
+    import matplotlib.pyplot as plt
+    from matplotlib.patches import Polygon
+
+    hexes = normalize_cells(cells)
+    invalid = [cell for cell in hexes if not is_valid_cell(cell)]
+    if invalid:
+        raise ValueError(f"Invalid H3 cell(s): {', '.join(invalid[:3])}")
+
+    if ax is None:
+        fig, ax = plt.subplots(1, 1, figsize=figsize)
+    else:
+        fig = ax.figure
+
+    selected = set(normalize_cells(selected_cells) if selected_cells is not None else [])
+    all_lngs: list[float] = []
+    all_lats: list[float] = []
+
+    for cell in hexes:
+        boundary = cell_to_boundary(cell)
+        polygon_points = [(lng, lat) for lat, lng in boundary]
+        all_lngs.extend(lng for lng, _ in polygon_points)
+        all_lats.extend(lat for _, lat in polygon_points)
+
+        patch = Polygon(
+            polygon_points,
+            closed=True,
+            facecolor=selected_face_color if cell in selected else face_color,
+            edgecolor=edge_color,
+            alpha=alpha,
+            linewidth=linewidth,
+        )
+        ax.add_patch(patch)
+
+        center_lat, center_lng = cell_to_latlng(cell)
+        if show_centers:
+            ax.scatter([center_lng], [center_lat], s=18, c=edge_color, zorder=3)
+
+        if show_labels:
+            label = cell if label_full_hex else cell[-6:]
+            ax.text(
+                center_lng,
+                center_lat,
+                label,
+                ha="center",
+                va="center",
+                fontsize=7,
+                color="#111111",
+                zorder=4,
+            )
+
+    if all_lngs and all_lats:
+        lng_margin = max((max(all_lngs) - min(all_lngs)) * 0.08, 0.001)
+        lat_margin = max((max(all_lats) - min(all_lats)) * 0.08, 0.001)
+        ax.set_xlim(min(all_lngs) - lng_margin, max(all_lngs) + lng_margin)
+        ax.set_ylim(min(all_lats) - lat_margin, max(all_lats) + lat_margin)
+
+    if equal_aspect:
+        ax.set_aspect("equal", adjustable="box")
+
+    ax.set_title(title, fontsize=13, fontweight="bold")
+    ax.set_xlabel("Longitude")
+    ax.set_ylabel("Latitude")
+    ax.grid(True, linewidth=0.4, alpha=0.35)
+    fig.tight_layout()
+    return fig
+
+
+def cells_to_geodataframe(
+    cells: str | Iterable[str],
+    *,
+    selected_cells: str | Iterable[str] | None = None,
+):
+    """Convert one or more H3 cells to a GeoPandas dataframe of polygons."""
+    try:
+        import geopandas as gpd
+        from shapely.geometry import Polygon
+    except ImportError as exc:
+        raise ImportError(
+            "GeoPandas plotting requires the geo extra: "
+            "pip install 'sameer-graph-lib[geo]'"
+        ) from exc
+
+    hexes = normalize_cells(cells)
+    invalid = [cell for cell in hexes if not is_valid_cell(cell)]
+    if invalid:
+        raise ValueError(f"Invalid H3 cell(s): {', '.join(invalid[:3])}")
+
+    selected = set(normalize_cells(selected_cells) if selected_cells is not None else [])
+    rows = []
+    for cell in hexes:
+        boundary = cell_to_boundary(cell)
+        polygon = Polygon([(lng, lat) for lat, lng in boundary])
+        center_lat, center_lng = cell_to_latlng(cell)
+        rows.append(
+            {
+                "h3_cell": cell,
+                "selected": cell in selected,
+                "center_lat": center_lat,
+                "center_lng": center_lng,
+                "geometry": polygon,
+            }
+        )
+
+    return gpd.GeoDataFrame(rows, geometry="geometry", crs="EPSG:4326")
+
+
+def plot_h3_cells_map(
+    cells: str | Iterable[str],
+    *,
+    selected_cells: str | Iterable[str] | None = None,
+    column: str | None = "selected",
+    title: str = "H3 Cells Map",
+    ax=None,
+    figsize: tuple[float, float] = (16, 16),
+    alpha: float = 0.35,
+    edge_color: str = "black",
+    linewidth: float = 1.0,
+    basemap: bool = True,
+    basemap_source=None,
+    legend: bool = True,
+    hide_axes: bool = True,
+):
+    """Plot H3 cells with GeoPandas and an optional Contextily basemap.
+
+    This mirrors the GeoPandas workflow:
+    convert H3 polygons to ``EPSG:3857``, plot them, then add a web basemap.
+    Returns the Matplotlib ``Figure`` object.
+    """
+    try:
+        import contextily as cx
+        import matplotlib.pyplot as plt
+    except ImportError as exc:
+        raise ImportError(
+            "Basemap plotting requires the geo extra: "
+            "pip install 'sameer-graph-lib[geo]'"
+        ) from exc
+
+    gdf = cells_to_geodataframe(cells, selected_cells=selected_cells).to_crs(epsg=3857)
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=figsize)
+    else:
+        fig = ax.figure
+
+    if hide_axes:
+        ax.get_xaxis().set_visible(False)
+        ax.get_yaxis().set_visible(False)
+
+    plot_kwargs = {
+        "ax": ax,
+        "alpha": alpha,
+        "edgecolor": edge_color,
+        "linewidth": linewidth,
+        "legend": legend,
+    }
+    if column and column in gdf.columns:
+        plot_kwargs.update({"column": column, "categorical": True})
+        if legend:
+            plot_kwargs["legend_kwds"] = {"loc": "upper left"}
+    else:
+        plot_kwargs["color"] = "#3498db"
+
+    gdf.plot(**plot_kwargs)
+
+    if basemap:
+        source = basemap_source or cx.providers.CartoDB.Positron
+        cx.add_basemap(ax, crs=gdf.crs, source=source)
+
+    ax.set_title(title, fontsize=13, fontweight="bold")
+    fig.tight_layout()
+    return fig

sameer_graph_lib/spatial_ingestor.py

@@ -0,0 +1,170 @@
+"""Input normalization utilities for H3 route data."""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Sequence, Tuple
+
+from ._h3 import (
+    cell_to_latlng,
+    get_resolution,
+    grid_distance,
+    grid_path_cells,
+    is_valid_cell,
+    latlng_to_cell,
+)
+
+Coordinate = Tuple[float, float]
+
+
+class SpatialIngestor:
+    """Convert raw spatial inputs into contiguous H3 chains."""
+
+    def __init__(self, resolution: int = 9, strict: bool = True) -> None:
+        self.resolution = int(resolution)
+        self.strict = strict
+
+    def ingest_h3_array(self, hex_list: Iterable[str]) -> List[str]:
+        """Validate and gap-fill an explicit list of H3 cells."""
+        return self.normalize_h3_chain(list(hex_list))
+
+    def ingest_latlng_sequence(
+        self,
+        coords: Sequence[Coordinate],
+        resolution: int | None = None,
+    ) -> List[str]:
+        """Convert a lat/lng sequence into a contiguous H3 route."""
+        res = self.resolution if resolution is None else int(resolution)
+        cells = [latlng_to_cell(float(lat), float(lng), res) for lat, lng in coords]
+        return self.normalize_h3_chain(cells)
+
+    def ingest_encoded_polyline(
+        self,
+        polyline_str: str,
+        resolution: int | None = None,
+        precision: int = 5,
+    ) -> List[str]:
+        """Decode a Google encoded polyline and convert it to H3 cells."""
+        return self.ingest_latlng_sequence(
+            decode_polyline(polyline_str, precision=precision),
+            resolution=resolution,
+        )
+
+    def normalize_h3_chain(self, hexes: Sequence[str]) -> List[str]:
+        """Remove consecutive duplicates and fill gaps between adjacent samples."""
+        cells = self._dedupe_consecutive([str(h) for h in hexes if h])
+        if not cells:
+            return []
+
+        self._validate_cells(cells)
+        if len(cells) == 1:
+            return cells
+
+        normalized = [cells[0]]
+        for cell in cells[1:]:
+            if cell == normalized[-1]:
+                continue
+
+            bridge = self._bridge_cells(normalized[-1], cell)
+            if not bridge:
+                normalized.append(cell)
+            elif bridge[0] == normalized[-1]:
+                normalized.extend(bridge[1:])
+            else:
+                normalized.extend(bridge)
+
+        return self._dedupe_consecutive(normalized)
+
+    def _validate_cells(self, cells: Sequence[str]) -> None:
+        invalid = [cell for cell in cells if not is_valid_cell(cell)]
+        if invalid and self.strict:
+            sample = ", ".join(invalid[:3])
+            raise ValueError(f"Invalid H3 cell(s): {sample}")
+
+        resolutions = {get_resolution(cell) for cell in cells if is_valid_cell(cell)}
+        if len(resolutions) > 1 and self.strict:
+            raise ValueError("All H3 cells in one route must use the same resolution.")
+
+    def _bridge_cells(self, start: str, end: str) -> List[str]:
+        try:
+            path = grid_path_cells(start, end)
+            return path if path else [start, end]
+        except Exception:
+            return self._fallback_bridge_cells(start, end)
+
+    def _fallback_bridge_cells(self, start: str, end: str) -> List[str]:
+        """Approximate a bridge when h3 cannot produce an exact grid path."""
+        if start == end:
+            return [start]
+
+        resolution = get_resolution(start)
+        steps = max(1, grid_distance(start, end))
+        lat1, lng1 = cell_to_latlng(start)
+        lat2, lng2 = cell_to_latlng(end)
+
+        sampled = []
+        for idx in range(steps + 1):
+            ratio = idx / steps
+            lat = lat1 + (lat2 - lat1) * ratio
+            lng = lng1 + (lng2 - lng1) * ratio
+            sampled.append(latlng_to_cell(lat, lng, resolution))
+
+        sampled[0] = start
+        sampled[-1] = end
+        sampled = self._dedupe_consecutive(sampled)
+
+        expanded = [sampled[0]]
+        for cell in sampled[1:]:
+            if cell == expanded[-1]:
+                continue
+            try:
+                bridge = grid_path_cells(expanded[-1], cell)
+                expanded.extend(bridge[1:] if bridge and bridge[0] == expanded[-1] else bridge)
+            except Exception:
+                expanded.append(cell)
+
+        return self._dedupe_consecutive(expanded)
+
+    @staticmethod
+    def _dedupe_consecutive(items: Sequence[str]) -> List[str]:
+        deduped: List[str] = []
+        for item in items:
+            if not deduped or deduped[-1] != item:
+                deduped.append(item)
+        return deduped
+
+
+def decode_polyline(polyline_str: str, precision: int = 5) -> List[Coordinate]:
+    """Decode a Google encoded polyline string without extra dependencies."""
+    coordinates: List[Coordinate] = []
+    index = 0
+    lat = 0
+    lng = 0
+    factor = 10**precision
+
+    while index < len(polyline_str):
+        lat_delta, index = _decode_polyline_value(polyline_str, index)
+        lng_delta, index = _decode_polyline_value(polyline_str, index)
+        lat += lat_delta
+        lng += lng_delta
+        coordinates.append((lat / factor, lng / factor))
+
+    return coordinates
+
+
+def _decode_polyline_value(polyline_str: str, index: int) -> tuple[int, int]:
+    result = 0
+    shift = 0
+
+    while True:
+        if index >= len(polyline_str):
+            raise ValueError("Invalid encoded polyline: truncated value.")
+        byte = ord(polyline_str[index]) - 63
+        index += 1
+        result |= (byte & 0x1F) << shift
+        shift += 5
+        if byte < 0x20:
+            break
+
+    value = ~(result >> 1) if result & 1 else result >> 1
+    return value, index
+