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

sameer_graph_lib/topology_analyzer.py

@@ -0,0 +1,174 @@
+"""Topology analysis for route affinity graphs."""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Sequence
+
+import networkx as nx
+
+
+class TopologyAnalyzer:
+    """Split a graph into its main trunk and residual minor branches."""
+
+    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 decompose_branches(self, seed_hexes: Sequence[str] | None = None) -> dict:
+        if self.graph.number_of_nodes() == 0:
+            return {
+                "main_branch": {
+                    "node_count": 0,
+                    "total_count": 0,
+                    "total_value": 0,
+                    "hexes": [],
+                },
+                "minor_branches": [],
+            }
+
+        forest = self._maximum_spanning_forest()
+        main_branch = self._choose_main_branch(forest, seed_hexes=seed_hexes)
+        main_set = set(main_branch)
+
+        residual = self.graph.copy()
+        residual.remove_nodes_from(main_set)
+
+        branches = []
+        for component in nx.connected_components(residual):
+            hexes = self._stable_component_order(component)
+            branches.append(
+                {
+                    "node_count": len(hexes),
+                    "total_count": self._sum_node_attr(hexes, "count"),
+                    "total_value": self._sum_node_attr(hexes, "value"),
+                    "hexes": hexes,
+                    "connects_to_main_at": self._main_attachment(component, main_set),
+                }
+            )
+
+        branches.sort(key=lambda item: (item["total_count"], item["node_count"]), reverse=True)
+        for idx, branch in enumerate(branches, start=1):
+            branch["branch_id"] = idx
+
+        return {
+            "main_branch": {
+                "node_count": len(main_branch),
+                "total_count": self._sum_node_attr(main_branch, "count"),
+                "total_value": self._sum_node_attr(main_branch, "value"),
+                "hexes": main_branch,
+            },
+            "minor_branches": branches,
+        }
+
+    def _maximum_spanning_forest(self) -> nx.Graph:
+        weighted = nx.Graph()
+        weighted.add_nodes_from(self.graph.nodes(data=True))
+
+        for u, v, data in self.graph.edges(data=True):
+            copied = dict(data)
+            copied["_trunk_strength"] = self._edge_strength(u, v, data)
+            weighted.add_edge(u, v, **copied)
+
+        if weighted.number_of_edges() == 0:
+            return weighted
+
+        return nx.maximum_spanning_tree(weighted, weight="_trunk_strength")
+
+    def _choose_main_branch(
+        self,
+        forest: nx.Graph,
+        seed_hexes: Sequence[str] | None = None,
+    ) -> List[str]:
+        if forest.number_of_nodes() == 1:
+            return list(forest.nodes)
+
+        candidates = []
+        seed_path = self._seed_path(forest, seed_hexes)
+        if seed_path:
+            candidates.append(seed_path)
+
+        for component in nx.connected_components(forest):
+            subgraph = forest.subgraph(component)
+            candidates.append(self._diameter_path(subgraph))
+
+        return max(
+            candidates,
+            key=lambda path: (len(path), self._sum_node_attr(path, "count")),
+            default=[],
+        )
+
+    def _seed_path(self, forest: nx.Graph, seed_hexes: Sequence[str] | None) -> List[str]:
+        if not seed_hexes:
+            return []
+
+        present = [cell for cell in seed_hexes if cell in forest]
+        if len(present) < 2:
+            return []
+
+        best_path: List[str] = []
+        # Limit pair scans for very long seed routes while keeping endpoint intent.
+        candidates = present[:25] + present[-25:]
+        for idx, source in enumerate(candidates):
+            for target in candidates[idx + 1 :]:
+                if not nx.has_path(forest, source, target):
+                    continue
+                path = nx.shortest_path(forest, source, target)
+                if len(path) > len(best_path):
+                    best_path = path
+
+        return best_path
+
+    def _diameter_path(self, graph: nx.Graph) -> List[str]:
+        if graph.number_of_nodes() == 0:
+            return []
+        if graph.number_of_nodes() == 1:
+            return list(graph.nodes)
+
+        start = next(iter(graph.nodes))
+        first = self._farthest_by_hops(graph, start)
+        second = self._farthest_by_hops(graph, first)
+        return nx.shortest_path(graph, first, second)
+
+    def _farthest_by_hops(self, graph: nx.Graph, source: str) -> str:
+        lengths = nx.single_source_shortest_path_length(graph, source)
+        return max(lengths, key=lambda node: (lengths[node], self._node_metric(node)))
+
+    def _edge_strength(self, u: str, v: str, data: dict) -> float:
+        traversal_count = float(data.get("count", 0) or 0)
+        endpoint_strength = (self._node_metric(u) + self._node_metric(v)) / 2.0
+        distance = max(float(data.get("distance", data.get("weight", 1)) or 1), 1.0)
+        return traversal_count * 1000.0 + endpoint_strength - distance * 0.001
+
+    def _node_metric(self, node: str) -> float:
+        return float(self.graph.nodes[node].get("count", 0) or 0)
+
+    def _sum_node_attr(self, nodes: Iterable[str], attr: str) -> float:
+        return sum(float(self.graph.nodes[node].get(attr, 0) or 0) for node in nodes)
+
+    def _stable_component_order(self, component: Iterable[str]) -> List[str]:
+        return sorted(
+            component,
+            key=lambda node: (
+                -float(self.graph.nodes[node].get("count", 0) or 0),
+                str(node),
+            ),
+        )
+
+    def _main_attachment(self, component: Iterable[str], main_set: set[str]) -> str | None:
+        options = []
+        for node in component:
+            for neighbor in self.graph.neighbors(node):
+                if neighbor not in main_set:
+                    continue
+                data = self.graph[node][neighbor]
+                options.append(
+                    (
+                        -float(data.get("count", 0) or 0),
+                        float(data.get("distance", data.get("weight", 0)) or 0),
+                        neighbor,
+                    )
+                )
+
+        if not options:
+            return None
+        options.sort()
+        return options[0][2]

sameer_graph_lib-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: sameer-graph-lib
+Version: 0.1.0
+Summary: H3 and NetworkX based route affinity graph toolkit.
+Author-email: Sameer <sameerkumarroy073@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/iams31/sameer_graph_lib
+Project-URL: Repository, https://github.com/iams31/sameer_graph_lib
+Project-URL: Issues, https://github.com/iams31/sameer_graph_lib/issues
+Keywords: h3,networkx,geospatial,routing,graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: h3>=4.0.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: geo
+Requires-Dist: contextily>=1.5; extra == "geo"
+Requires-Dist: geopandas>=0.14; extra == "geo"
+Requires-Dist: shapely>=2.0; extra == "geo"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# sameer-graph-lib
+
+`sameer-graph-lib` is an editable Python library for building H3-based route affinity graphs with NetworkX.
+
+It turns H3 arrays, latitude/longitude sequences, and encoded polylines into connected hex chains, inserts them into a weighted graph, extracts high-affinity corridors, and decomposes the graph into a main trunk plus minor branches.
+
+## Editable install
+
+```powershell
+python -m pip install -e ".[dev,plot]"
+```
+
+Because the install is editable, changes you make inside `src/sameer_graph_lib` are picked up immediately by Python without reinstalling.
+
+If your machine uses `uv`, run commands through the managed environment:
+
+```powershell
+uv run --extra dev --extra plot python -c "import sameer_graph_lib; print(sameer_graph_lib.__version__)"
+```
+
+## Install
+
+From PyPI after publication:
+
+```powershell
+pip install sameer-graph-lib
+```
+
+With optional plotting and geospatial extras:
+
+```powershell
+pip install "sameer-graph-lib[plot,geo]"
+```
+
+## Quick start
+
+```python
+from sameer_graph_lib import HexGraph
+
+graph = HexGraph(hex_resolution=9)
+
+route = graph.add_latlng_sequence([
+    (12.9716, 77.5946),
+    (12.9760, 77.5990),
+])
+
+print(graph.get_graph_stats())
+selected = graph.get_appropriate_hexes(cutoff=0.8)
+fig = graph.visualize_graph(title="80% compact cluster", highlight_hexes=selected)
+print(graph.decompose_branches())
+```
+
+## Main APIs
+
+- `SpatialIngestor`: converts H3 arrays, lat/lng sequences, and encoded polylines into contiguous H3 chains.
+- `AffinityGraph`: NetworkX wrapper for array-based insertion, nearest attachment, affinity scoring, editing, and JSON persistence.
+- `CorridorExtractor`: uses exact all-node Dijkstra selection to extract the most compact cluster covering a target percentage of graph traversal volume.
+- `TopologyAnalyzer`: separates the main branch from residual minor branches.
+- `HexGraph`: backwards-compatible convenience class for your original code style.
+
+Graph creation follows the original per-node procedure: H3 arrays are normalized, then each hex is inserted with `add_node`/`add_hex`. Lat/lng sequences and encoded polylines are first converted into H3 arrays at the requested resolution, then inserted the same way.
+
+For QC, use:
+
+```python
+fig = graph.visualize_graph(highlight_hexes=selected)
+fig.savefig("graph_qc.png", dpi=150, bbox_inches="tight")
+
+fig = graph.visualize_step_by_step(route[:5], labels=["A", "B", "C", "D", "E"])
+fig.savefig("insertion_steps.png", dpi=150, bbox_inches="tight")
+```
+
+To plot actual H3 hex boundaries as geospatial polygons:
+
+```python
+from sameer_graph_lib import plot_h3_cells, plot_h3_cells_map
+
+fig = plot_h3_cells("88618c4f29fffff", label_full_hex=True)
+fig.savefig("single_h3_cell.png", dpi=150, bbox_inches="tight")
+
+fig = graph.plot_h3_cells(highlight_hexes=selected, show_labels=False)
+fig.savefig("h3_cell_footprint.png", dpi=150, bbox_inches="tight")
+
+fig = plot_h3_cells_map(route, selected_cells=selected)
+fig.savefig("h3_cell_basemap.png", dpi=150, bbox_inches="tight")
+```
+
+`plot_h3_cells_map` uses GeoPandas + Contextily. Install it with:
+
+```powershell
+python -m pip install -e ".[plot,geo]"
+uv run --extra plot --extra geo python -c "from sameer_graph_lib import plot_h3_cells_map"
+```
+
+To get H3 centers and a convex hull:
+
+```python
+from sameer_graph_lib import getLatLng, h3_convex_hull
+
+points = getLatLng(route)          # [(lat, lng), ...]
+hull = h3_convex_hull(route)       # Shapely geometry in (lng, lat)
+graph_hull = graph.convex_hull()   # Same, using graph nodes
+```
+
+## Useful commands
+
+```powershell
+python -m pytest
+python -m build
+uv run --extra dev pytest -q
+uv run --extra dev python -m build
+uv run --extra dev python -m twine check dist/*
+```
+
+Build artifacts will appear in `dist/` after `python -m build`.
+
+## Publish To PyPI
+
+1. Build the package:
+
+```powershell
+uv run --extra dev python -m build
+```
+
+2. Validate the package metadata:
+
+```powershell
+uv run --extra dev python -m twine check dist/*
+```
+
+3. Upload to PyPI:
+
+```powershell
+uv run --extra dev python -m twine upload dist/*
+```
+
+After upload, users can install it with:
+
+```powershell
+pip install sameer-graph-lib
+```
+
+## Publish From GitHub
+
+This repo also includes a Trusted Publishing workflow in
+[.github/workflows/publish.yml](C:/Users/rrran/Desktop/sameer_graph_lib/.github/workflows/publish.yml:1).
+
+To finish that setup:
+
+1. Create the project on PyPI, or reserve the name `sameer-graph-lib`.
+2. On PyPI, open the project settings and add a Trusted Publisher for:
+   `owner`: `iams31`
+   `repository`: `sameer_graph_lib`
+   `workflow`: `publish.yml`
+   `environment`: `pypi`
+3. Create a GitHub Release, or run the workflow manually from the Actions tab.
+
+After that, GitHub Actions can publish without storing a long-lived PyPI token.
+
+Official references:
+
+- PyPI Trusted Publishing: https://docs.pypi.org/trusted-publishers/
+- Packaging guide upload flow: https://packaging.python.org/tutorials/packaging-projects/

sameer_graph_lib-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sameer_graph_lib/__init__.py,sha256=rfzOeoVj_WmdLCH1j2Is2p6mXlvg9ohJ1CAvlH-uFbM,791
+sameer_graph_lib/_h3.py,sha256=Vlch4zX9SR6hg4S-5lYGDNEwEH9IVosRIEg_n2Emq0I,3655
+sameer_graph_lib/affinity_graph.py,sha256=DCFLbRJ3rTmHR5oBtxNAyAZWE7sxn-rFwf3pPgmfptk,28681
+sameer_graph_lib/corridor_extractor.py,sha256=V77VtxPHWBAJYzQz553TdoRpuo3KdnEeI6H3iPex998,2667
+sameer_graph_lib/geometry.py,sha256=unCcwqZU96kewJTNpaym31B2o32v6xsmiP2hdv2Y6VY,2288
+sameer_graph_lib/hex_graph.py,sha256=51VHsD5_xVS95UW4viiBjffHdr9xziDg_YQeIHplWsU,454
+sameer_graph_lib/plotting.py,sha256=DPuUdSmoJMUQloWqEV-bauZXJjUFvKWUCtTs2WI8dvM,6597
+sameer_graph_lib/spatial_ingestor.py,sha256=3GDaTWT5etbC55fIzSTB5D0gS3HzyRzyMRKR0tjEsw0,5608
+sameer_graph_lib/topology_analyzer.py,sha256=JfZtbBeIrTZaZdzG41fsnoNZgcssml4iSZWVWAevBSc,6367
+sameer_graph_lib-0.1.0.dist-info/licenses/LICENSE,sha256=5VuvbSI3M1-d6PVSlQm5_zjokepvD9eFuWOvXS0udls,1069
+sameer_graph_lib-0.1.0.dist-info/METADATA,sha256=8UElHhnErBPw92gnA7-P8uHFsHd1S2tRdSKdMr9qmTs,6282
+sameer_graph_lib-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sameer_graph_lib-0.1.0.dist-info/top_level.txt,sha256=tgFV-BCa4PLQQ0AF9nOM1VscPuEX4LlO-DTe6H_Xnv8,17
+sameer_graph_lib-0.1.0.dist-info/RECORD,,

sameer_graph_lib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sameer_graph_lib-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sameer Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sameer_graph_lib-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sameer_graph_lib