GRAX

GRAX is a lightweight Python library for transforming geospatial shapefiles into machine-learning-ready graph networks using NetworkX.

It automates the full pipeline from raw GIS data → graph structure → ML-ready inputs, enabling seamless integration with:

• Graph Neural Networks (GNNs)
• Complex Network Analytics (CNA)
• Spatial ML models
• Routing and navigation algorithms
• Digital twin simulations
• Infrastructure ML pipelines

Whether you are building a road network classifier, a pipeline failure predictor, a mobility model, or a full city-scale digital twin, GRAX converts raw line data into a structured graph with accurate topology and geometry.

---

📦 Installation

Install from PyPI

pip install grax

---

🔥 Why GRAX?

Most ML/AI models require structured graph data, not shapefile polylines.

GRAX bridges this gap by:

• Converting shapefile line geometries into numerical matrices
• Automatically detecting intersections using Shapely
• Building a topologically correct NetworkX graph
• Embedding node attributes (x, y)
• Producing a graph that is directly usable for:
  • PyTorch Geometric
  • DGL
  • StellarGraph
  • NetworkX-based ML
  • Custom GNN pipelines

The goal:

Turn raw geospatial networks into graph datasets that you can directly feed into ML models.

---

⚙️ Features

• ✅ Converts shapefiles into clean numerical tensors (NumPy matrices)
• ✅ Builds graphs for graph theory and ML tasks
• ✅ Automatic node creation at all intersections (crucial for routing & GNNs)
• ✅ Each node stores geometry → perfect for spatial embeddings
• ✅ Produces NetworkX graphs ready for: node classification/link prediction/graph embeddings/centrality-based ML features
• ✅ Ideal preprocessing step before feeding data into PyTorch Geometric or DGL
• ✅ Designed for digital twins & infrastructure ML (roads, utilities, pipelines)

---

📚 API Reference

Class grax

grax(
      verbose=0      # prints intersection detection logs
)

Function digitize_shape()

Converts a list of LineString geometries into ML-friendly numerical matrices.

digitize_shape(shapefile)

Function create_network()

Takes digitized matrices and constructs a full-resolution graph with:

• Accurate topology
• Intersection nodes (is_i_j_k)
• Node attributes (x, y)
• Edges representing real connectivity

create_network(L)

---

🚀 Quickstart: From Shapefile to ML-Ready Graph

from grax import grax

# Initialize GRAX
g = grax(verbose=1)

# Step 1 — Digitize the shapefile
L = g.digitize_shape("city_roads.shp")

# Step 2 — Build the full network graph
G = g.create_network(L)

print("Nodes:", len(G.nodes()))
print("Edges:", len(G.edges()))

---

🧠 How GRAX Enables ML

1. ML-Ready Node Features

Every node comes with spatial features:

{x: longitude, y: latitude}

You can extend this with:

• elevation
• traffic flows
• utility capacity
• population density
• environmental layers

2. Topologically Correct Graphs

Many ML tasks require correct topology:

• shortest paths
• flow simulation
• infrastructure interdependency models
• GNNs using neighborhood aggregation
• GRAX ensures that all intersections become actual nodes, which is critical for ML accuracy.

3. Perfect for Graph Neural Networks

GNN performance depends on:

• Proper graph structure
• Correct adjacency
• Meaningful node features
• GRAX creates exactly that from raw spatial data.

---

🗺️ Real-World ML Applications

GRAX is used in:

🚗 Traffic prediction models

💧 Water or gas pipeline monitoring

🌆 Urban digital twin systems

🚉 Transit network optimization

🛣️ Road network risk modeling

🌪️ Disaster response routing ML

🧠 CNA (Complex Network Analytics) models

🛰️ Spatial graph embeddings

It is engineered for modern AI workflows in civil engineering, infrastructure, and geospatial ML.

---

📜 License

This project is licensed under the MIT License.
© 2025 Dr. Ahmed Moussa

---

🤝 Contributing

Pull requests are welcome.
For major changes, please open an issue first to discuss what you would like to change.

---

📫 Contact

For feedback, bugs, or collaboration ideas:

• GitHub: @real-ahmed-moussa

---

⭐️ Show Your Support

If you find this project useful, consider giving it a ⭐️ on GitHub!