---
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](#overview)
2. [Features](#features)
3. [Prerequisites](#prerequisites)
4. [Installation](#installation)
5. [Usage](#usage)
   - [Step 1: Assign Weights](#step-1-assign-weights)
   - [Step 2: Create Clusters](#step-2-create-clusters)
   - [Download Shapefile](#download-shapefile)
6. [Workflow Diagram](#workflow-diagram)
7. [Architecture](#architecture)
8. [Future Improvements](#future-improvements)
9. [Contributing](#contributing)
10. [License](#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:
   ```bash
   git clone https://github.com/your-org/roadway-flood-index.git
   cd roadway-flood-index
   ```
2. Create and activate a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   venv\\Scripts\\activate     # Windows
   ```
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Usage

### Step 1: Assign Weights
1. Launch the app:
   ```bash
   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

```mermaid
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](LICENSE) for details.