README.md

metadata

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