README.md

metadata

title: Roadway Risk Index
emoji: 🛣️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.26.0
app_file: app.py
pinned: false

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Focus Area Identification for Houston Thoroughfares

This README provides an overview of the Gradio-based application for analyzing flood risk and other critical factors on Houston thoroughfare roads using H3 hexagons, SWMM outputs, and multiple datasets.

---

Table of Contents

1. Overview
2. Features
3. Prerequisites
4. Installation
5. Usage
   • Step 1: Assign Weights
   • Step 2: Create Clusters
   • Download Shapefile
6. Workflow Diagram
7. Architecture
8. Future Improvements
9. Contributing
10. License

---

Overview

This web application allows users to build a custom risk index for Houston thoroughfare hexagons (H3 R11) by selecting features, assigning weights, and visualizing the resulting vulnerability. It integrates datasets such as floodplain data, Pavement Condition Index (PCI), Annual Average Daily Traffic (ADT), METRO routes, Critical Facilities, and Social Vulnerability Index (SVI).

Features

• Dynamic Weighting: Choose any combination of primary and secondary features and assign relative weights.
• Index Calculation: Computes a normalized risk index for each H3 hexagon.
• Visualization: Displays index statistics, histograms, and an interactive Folium map colored by index value.
• Cluster Analysis: Identify contiguous groups of high-risk hexagons based on a user-defined index threshold and minimum cluster size.
• Shapefile Export: Download a zipped shapefile of the focus area hexagons for further GIS analysis.

Prerequisites

• Python 3.8+
• Required Python packages: pandas, numpy, gradio, matplotlib, h3, folium, shapely, geopandas, openpyxl

Installation

1. Clone this repository:

   git clone https://github.com/your-org/roadway-flood-index.git
   cd roadway-flood-index
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   venv\\Scripts\\activate     # Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

Usage

Step 1: Assign Weights

1. Launch the app:

   python app.py
   

2. In the "Feature Weights" table, set weights for desired features (must sum to 100).
3. Click Calculate Index to generate statistics, histogram, and map.

Step 2: Create Clusters

1. Enter an Index Threshold (e.g., 3.0) and Minimum Cluster Size (number of hexagons).
2. Click Create Clusters to view clustered focus areas on the map and in a table.

Download Shapefile

• Click Download Focus Area Shapefile Zip to retrieve a zipped folder containing the shapefile of clustered hexagons.

Workflow Diagram

flowchart LR
  A[Start] --> B[Load Data]
  B --> C[User Assigns Weights]
  C --> D[Validate Sum = 100]
  D --> E[Calculate Index]
  E --> F[Display Stats & Histogram]
  F --> G[Render Index Map]
  G --> H[User Sets Threshold & Min Cluster Size]
  H --> I[Find Clusters]
  I --> J[Display Clusters Map & Table]
  J --> K[Download Shapefile]
  K --> L[End]

Architecture

• Data Layer: Loads and preprocesses instance data (MainInstances.xlsx) with Pandas and GeoPandas.
• Index Engine: Normalizes feature values, computes weighted index, and buckets instances.
• Visualization: Uses Matplotlib for histograms and Folium for interactive mapping.
• Front-End: Gradio provides the UI for user input, outputs, and file downloads.
• Clustering: Implements an H3 grid-based flood fill algorithm to group adjacent high-index hexagons.

Future Improvements

• Integrate real-time flood modeling via SWMM API.
• Add additional resilience factors (e.g., alternative route availability).
• Incorporate user authentication and data logging.
• Optimize performance for large datasets using Dask or PySpark.
• Enhance UI with thematic map layers and custom styling.

Contributing

1. Fork the repo and create a feature branch.
2. Submit a pull request with clear description of changes.
3. Ensure all tests pass and update documentation as needed.

License

MIT License. See LICENSE for details.