{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f68f48dd",
   "metadata": {},
   "source": [
    "# Reference Damage Curves Tutorial\n",
    "\n",
    "This tutorial demonstrates how to run a **damage analysis using reference damage curves** in RA2CE.\n",
    "Reference curves (such as the Huizinga et al. dataset) are widely used for rapid assessments of hazard-related damage,\n",
    "as they provide generic hazard–damage relationships without requiring local calibration.\n",
    "\n",
    "RA2CE provides several built-in options for vulnerability curves:\n",
    "\n",
    "- **Global** → Huizinga curves (`HZ` analysis name)\n",
    "- **Europe** → OSDamage functions (`OSD` analysis name)\n",
    "\n",
    "These curves determine how hazard intensity (e.g., water depth) is translated into expected damage fractions."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73460374",
   "metadata": {},
   "source": [
    "## Important Notes\n",
    "\n",
    "- The **Huizinga curves** are the global default option and are widely used in international flood damage assessments. For more details, see publication by Huizinga et al. (2017): [Global flood depth-damage functions: Methodology and the database with guidelines](https://publications.jrc.ec.europa.eu/repository/handle/JRC105688)\n",
    "- The **OSDamage functions** provide Europe-specific depth–damage relations. For more details, see publication by van Ginkel et al. (2021): [Flood risk assessment of the European road network](https://nhess.copernicus.org/articles/21/1011/2021/).\n",
    "\n",
    "In this example, we will use **flood depth maps** as hazard input and apply the **Huizinga reference curves** to estimate\n",
    "direct damages to road infrastructure."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf041060",
   "metadata": {},
   "source": [
    "## Step 1: Define project paths\n",
    "\n",
    "We first define the **root project folder** and its subdirectories:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "83a02735",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "root_dir = Path(\"data\", 'damage_reference_curves')\n",
    "\n",
    "static_path = root_dir.joinpath(\"static\")\n",
    "hazard_path = static_path.joinpath(\"hazard\")\n",
    "network_path = static_path.joinpath(\"network\")\n",
    "output_path = root_dir.joinpath(\"output\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10a85c36",
   "metadata": {},
   "source": [
    "## Step 2: Configure the road network and hazard\n",
    "\n",
    "The network is downloaded from **OpenStreetMap (OSM)**, clipped to a region polygon (`polygon.geojson`).\n",
    "We specify which **road types** should be included in the analysis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5ca3b733",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ra2ce.network.network_config_data.enums.road_type_enum import RoadTypeEnum\n",
    "from ra2ce.network.network_config_data.enums.source_enum import SourceEnum\n",
    "from ra2ce.network.network_config_data.enums.network_type_enum import NetworkTypeEnum\n",
    "from ra2ce.network.network_config_data.network_config_data import NetworkSection\n",
    "\n",
    "network_section = NetworkSection(\n",
    "    network_type=NetworkTypeEnum.DRIVE,\n",
    "    source=SourceEnum.OSM_DOWNLOAD,\n",
    "    polygon=static_path.joinpath(\"polygon.geojson\"),\n",
    "    save_gpkg=True,\n",
    "    road_types=[\n",
    "        RoadTypeEnum.SECONDARY,\n",
    "        RoadTypeEnum.SECONDARY_LINK,\n",
    "        RoadTypeEnum.PRIMARY,\n",
    "        RoadTypeEnum.PRIMARY_LINK,\n",
    "        RoadTypeEnum.TRUNK,\n",
    "        RoadTypeEnum.MOTORWAY,\n",
    "        RoadTypeEnum.MOTORWAY_LINK,\n",
    "    ],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de3179ae",
   "metadata": {},
   "source": [
    "We provide hazard input in the form of **GeoTIFF raster files** (e.g., flood depth maps).\n",
    "RA2CE will overlay these rasters with the road network to compute hazard intensities for each asset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9216f260",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ra2ce.network.network_config_data.enums.aggregate_wl_enum import AggregateWlEnum\n",
    "from ra2ce.network.network_config_data.network_config_data import HazardSection\n",
    "\n",
    "hazard_section = HazardSection(\n",
    "    hazard_map=[Path(file) for file in hazard_path.glob(\"*.tif\")],\n",
    "    aggregate_wl=AggregateWlEnum.MEAN,  # mean water depth used in analysis\n",
    "    hazard_crs=\"EPSG:4326\",  # ensure hazard map is in EPSG:4326 projection\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5b94cf25",
   "metadata": {},
   "source": [
    "We combine the network and hazard information into a single configuration object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1ccffca8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ra2ce.network.network_config_data.network_config_data import NetworkConfigData\n",
    "\n",
    "network_config_data = NetworkConfigData(\n",
    "    root_path=root_dir,\n",
    "    static_path=static_path,\n",
    "    network=network_section,\n",
    "    hazard=hazard_section\n",
    ")\n",
    "network_config_data.network.save_gpkg = True"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b8baa31",
   "metadata": {},
   "source": [
    "## Step 3: Define the damage analysis\n",
    "\n",
    "Here, we specify that RA2CE should perform a **damage analysis** using the\n",
    "**Huizinga reference damage curves (HZ)** with the class [AnalysisSectionDamages](../api/ra2ce.analysis.analysis_config_data.html#ra2ce.analysis.analysis_config_data.analysis_config_data.AnalysisSectionDamages){.api-ref} and the attribute `damage_curve` set to [DamageCurveEnum.HZ](../api/ra2ce.analysis.analysis_config_data.enums.html#ra2ce.analysis.analysis_config_data.enums.damage_curve_enum.DamageCurveEnum.HZ){.api-ref}\n",
    "\n",
    "The event type can be set to EVENT if damages are to be calculated for the hazard maps only (example below), or to RETURN_PERIOD if the analysis should estimate risk over a specified return period (see tutorial )."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3e101548",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ra2ce.analysis.damages.damages import AnalysisSectionDamages\n",
    "from ra2ce.analysis.analysis_config_data.enums.analysis_damages_enum import AnalysisDamagesEnum\n",
    "from ra2ce.analysis.analysis_config_data.enums.event_type_enum import EventTypeEnum\n",
    "from ra2ce.analysis.analysis_config_data.enums.damage_curve_enum import DamageCurveEnum\n",
    "from ra2ce.analysis.analysis_config_data.analysis_config_data import AnalysisConfigData\n",
    "\n",
    "damages_analysis = [AnalysisSectionDamages(\n",
    "    name='damages_reference_curve_Huizinga',\n",
    "    analysis=AnalysisDamagesEnum.DAMAGES,\n",
    "    event_type=EventTypeEnum.EVENT,\n",
    "    damage_curve=DamageCurveEnum.HZ,  # use Huizinga reference curve\n",
    "    save_csv=True,\n",
    "    save_gpkg=True\n",
    ")]\n",
    "\n",
    "analysis_config_data = AnalysisConfigData(\n",
    "    analyses=damages_analysis,\n",
    "    output_path=output_path,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05115b61",
   "metadata": {},
   "source": [
    "## Step 4: Run the analysis\n",
    "\n",
    "Finally, we run the analysis using the RA2CE handler."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "16318322",
   "metadata": {},
   "outputs": [],
   "source": [
    "from ra2ce.ra2ce_handler import Ra2ceHandler\n",
    "\n",
    "Ra2ceHandler.run_with_config_data(network_config_data, analysis_config_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "304c1d2f",
   "metadata": {},
   "source": [
    "## Output\n",
    "\n",
    "The results of the Huizinga damage analysis are provided in **two GeoPackage (GPKG) files**:\n",
    "\n",
    "- **damages_reference_curve_Huizinga_link_based.gpkg**: damage estimates per **network link** (from node to node).\n",
    "- **damages_reference_curve_Huizinga_segment.gpkg**: damage estimates per **segment** of 100m along the network.\n",
    "\n",
    "Key attributes of interest in the output (expressed in currency) include:\n",
    "\n",
    "- `dam_EV1_HZ` : estimated damage for the first flood map (Huizinga method).\n",
    "- `dam_EV2_HZ` : estimated damage for the second flood map (Huizinga method).\n",
    "\n",
    "You can open these files in GIS software (QGIS, ArcGIS) or load them in Python using GeoPandas for further analysis:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "89cbdb25",
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopandas as gpd\n",
    "output_path = root_dir / \"output\" / 'damages'\n",
    "output_path.exists()\n",
    "link_based = gpd.read_file(output_path / \"damages_reference_curve_Huizinga_link_based.gpkg\")\n",
    "segment_based = gpd.read_file(output_path / \"damages_reference_curve_Huizinga_segmented.gpkg\")\n",
    "\n",
    "# Inspect the first rows\n",
    "print(link_based.head())\n",
    "print(segment_based.head())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0b95874b",
   "metadata": {},
   "source": [
    "You can open the results in GIS software to visualize which road segments\n",
    "are most affected by the hazard.\n",
    "\n",
    "## Note\n",
    "\n",
    "Reference damage curves provide **generalized estimates** of vulnerability.\n",
    "For more locally calibrated studies, consider using manual damage curves."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "ra2ce_env",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}