README.md

---
title: eVCA
emoji: 📍
colorFrom: red
colorTo: red
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
short_description: Download and process hazard layers for Red Cross VCAs.
---

## eVCA Hazard and Exposure Analysis App

Digital Enhanced Vulnerability and Capacity Assessment
510 Netherlands Red Cross

This application automates spatial analysis of hazard exposure across countries and administrative regions. It retrieves hazard rasters, downloads exposure data, and runs modular analysis functions that combine both to answer operational and strategic questions in disaster risk management, emergency response, and advocacy.

The app is built entirely around modular extension. Developers can add new hazards, new exposure layers, and new analysis functions without modifying the core application logic.

---

# 1. Purpose

The app supports eVCA workflows by

* Generating hazard rasters for selected countries and return periods
* Fetching exposure datasets (HOTOSM, HDX CODs)
* Running any available analysis modules that compare hazards with exposure
* Presenting outputs in a structured and repeatable format

Typical use cases include

* National-level flood exposure prioritisation
* Identification of exposed critical infrastructure
* Road and building exposure summaries
* High resolution, locally relevant assessments of settlements and access routes

---

# 2. Architecture Overview

```
analysis/
   drm_planning.py          # Analysis functions and metadata
data/
   ckan.py                  # HDX population and admin downloads
   hotosm.py                # HOTOSM exposure downloads
   options.py               # Country and return period selections
hazards/
   flood.py                 # Hazard raster generation logic (per hazard)
app.py                      # Gradio interface
config.py                   # Hazard registry
requirements.txt
```

The structure separates responsibilities

* `hazards/` holds hazard raster generation modules
* `data/` fetches all exposure layers
* `analysis/` contains analysis functions runnable on any hazard and exposure inputs
* `app.py` dynamically discovers hazards and analyses
* `config.py` registers hazard metadata and layer dependencies

---

# 3. How the System Discovers Hazards and Analyses

## Hazards

Any file inside `hazards/` with a function named

```
generate_<hazardname>_raster(iso: str, rp: int, gis_name: str=None)
```

is automatically discovered.
Example: `flood.py` exposes `generate_flood_raster`, which the interface loads at runtime.

## Analyses

Any module inside `analysis/` that defines a dictionary named `ANALYSIS_METADATA` is registered automatically.
Its fields are

```
{
    "name": "...",
    "function": <callable>,
    "required_files": ["raster_path", ...],
    "enabled": True or False
}
```

All enabled analyses run after raster and exposure acquisition.

---

# 4. Adding a New Hazard Type

To add a new hazard

1. Create a file in `hazards/`
   Example

   ```
   hazards/landslide.py
   ```

2. Implement a generator function

   ```
   def generate_landslide_raster(iso: str, rp: int, gis_name: str=None):
       return output_path, message
   ```

   The function must

   * Accept `iso` and `rp`
   * Clip or build a raster of the hazard over the selected geometry
   * Return `(path_to_local_tif, status_message)`
   * Write only local files, no in-memory objects

3. Do not edit `app.py`. The app imports hazards dynamically.

4. Register hazard metadata in `config.py`

   ```
   hazard_registry["Landslide"] = HazardSource(
       name="Landslide",
       rp_options=[10, 25, 50, 100],
       generate_fn=generate_landslide_raster,
       data_layers=["populated_places", "roads", "buildings"]
   )
   ```

Once added, the hazard appears automatically in the dropdown interface.

---

# 5. Adding a New Exposure Layer

Exposure layers are stored under `data/`. A new exposure layer requires

* A download function
* A stable filename or return object
* Declaration inside the hazard’s `data_layers` list if required for analysis

Steps

1. Add a download function in `data/`
   Example

   ```
   data/electricity.py
   def download_electricity_grid(iso: str):
        return local_zip_path
   ```

2. Modify the hazard’s `data_layers` entry in `config.py` if the hazard depends on it.

3. In `app.py`, the wrapper automatically receives the file path if the downloader is added to the list of downloads.

You do not need to modify core logic. Analyses decide if they need the layer by reading `required_files`.

---

# 6. Adding a New Analysis Function

Analyses answer questions such as

* Which populated places intersect the hazard
* Which buildings or roads are exposed
* Which administrative areas have highest exposure intensity
* High or low exposure combined with vulnerability metrics

## Steps to add an analysis

1. Create a new file inside `analysis/`, for example

   ```
   analysis/roads_exposure.py
   ```

2. Implement a function with signature

   ```
   def analyze_something(raster_path: str, roads_path: str, ...):
       return message_string or tuple_of_message_strings
   ```

   The function must

   * Accept file paths only
   * Return human readable strings for UI display
   * Handle missing files internally with clear messages

3. Add metadata

   ```
   ANALYSIS_METADATA = {
       "name": "Road Flood Exposure",
       "function": analyze_something,
       "required_files": ["raster_path", "roads_path"],
       "enabled": True
   }
   ```

4. The app loads this automatically using `run_analyses`.

No integration changes are necessary elsewhere.

---

# 7. Example: Exposed Populated Places Analysis

`drm_planning.py` contains an example analysis that

* Loads populated places from HOTOSM
* Converts hazard rasters into polygons
* Computes intersections using GeoPandas
* Produces

  * Top 10 exposed settlements by population
  * Counts by settlement type

This module demonstrates the required structure and metadata pattern for all new analyses.

---

# 8. Example Analysis Questions That Can Be Implemented

Developers can modularly implement analyses that answer

* National settlement exposure by return period
* Provincial infrastructure exposure
* Road segments intersecting 25 to 100 year flood zones
* Disproportionate exposure for vulnerable settlements
* Local evacuation centre siting
* Isolation risk for communities after access routes are flooded
* Exposure intersection with poverty or displacement data
* Comparisons of exposure across 10, 100, and 500 year scenarios

Each question type can be implemented as a distinct analysis module.

---

# 9. Development Workflow

1. Clone the repository
2. Create a new hazard module, exposure downloader, or analysis script
3. Add metadata where required
4. Test locally with

   ```
   python app.py
   ```
5. Push to GitHub, and the app updates automatically on HuggingFace Spaces if configured

---

# 10. Running Locally

Clone repository

```
git clone https://huggingface.co/spaces/your-username/evca
```

Install dependencies in the folder where the repository was cloned

```
pip install -r requirements.txt
```

Launch locally

```
python app.py
```

The Gradio interface will open in your browser.

---

# 11. Contributing Guidelines

* Follow the modular structure
* Avoid modifying `app.py` unless updating UI behaviour
* Ensure new hazard generators return physical `.tif` files
* Ensure analyses return readable Markdown
* Handle missing data gracefully
* Keep functions pure and file based