Update README.md

README.md

@@ -4,48 +4,291 @@ emoji: 📍
 colorFrom: red
 colorTo: red
 sdk: gradio
-sdk_version: 5.35.0
+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 Data Downloader 🌍
+## eVCA Hazard and Exposure Analysis App
 
-This Gradio app enables users to download GloFAS flood hazard rasters and relevant exposure data for vulnerability and capacity assessments (VCAs).
+Digital Enhanced Vulnerability and Capacity Assessment
+510 Netherlands Red Cross
 
-## 🚀 Features
+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.
 
-- Select a country and return period
-- Fetch hazard rasters and exposure data
-- CKAN and HOTOSM integrations
-- Modular hazard support
+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.
 
-## 🧪 How to Use
+---
+
+# 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
 
-1. Select a country from the dropdown
-2. Choose a return period and hazard (e.g. Flood)
-3. Select subdivision if prompted
-4. Click **Generate Raster**
-5. Download your files below
+---
+
+# 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
+```
 
-## 📁 Output
+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.
+
+---
 
-- `.tif` raster files (hazards)
-- `.geojson` files (exposure layers)
-- Bundled `.zip` for downloads
+# 4. Adding a New Hazard Type
 
-## 🧩 Modular Design
+To add a new hazard
 
-- `hazards/`: Hazard-specific logic (flood, wildfire, etc.)
-- `data/`: HOTOSM and CKAN fetchers
-- `app.py`: UI and orchestration logic
+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`.
+
+---
 
-## 🛠 Run Locally
+# 6. Adding a New Analysis Function
 
-```bash
+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
-cd 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