{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Defined Origin–Destination Pairs Tutorial\n",
    "This tutorial demonstrates how to run a **Defined Origin–Destination (OD) analysis** with RA2CE.\n",
    "You explicitly provide origins and destinations, and RA2CE calculates shortest or quickest routes between them.\n",
    "\n",
    "If you are not yet familiar with preparing origins and destinations shapefiles, see the \n",
    "[Origins and Destinations Data Preparation](../tutorials/accessibility.prepare_data_origin_destinations.html) tutorial."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 1: Import Libraries and Set Paths"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fdb34e91",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "from ra2ce.analysis.analysis_config_data.analysis_config_data import AnalysisSectionLosses, AnalysisConfigData\n",
    "from ra2ce.analysis.analysis_config_data.enums.analysis_losses_enum import AnalysisLossesEnum\n",
    "from ra2ce.analysis.analysis_config_data.enums.weighing_enum import WeighingEnum\n",
    "from ra2ce.network import RoadTypeEnum\n",
    "from ra2ce.network.network_config_data.enums.aggregate_wl_enum import AggregateWlEnum\n",
    "from ra2ce.network.network_config_data.enums.network_type_enum import NetworkTypeEnum\n",
    "from ra2ce.network.network_config_data.enums.source_enum import SourceEnum\n",
    "from ra2ce.network.network_config_data.network_config_data import (\n",
    "    NetworkSection, NetworkConfigData, OriginsDestinationsSection, HazardSection, CleanupSection\n",
    ")\n",
    "from ra2ce.ra2ce_handler import Ra2ceHandler\n",
    "\n",
    "# Specify the path to your RA2CE project folder and input data\n",
    "root_dir = Path(\"data\", \"pairs_origins_destinations\")\n",
    "network_path = root_dir.joinpath('static', 'network')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7b4b033c",
   "metadata": {},
   "source": [
    "## Step 2: Define Network with Origins & Destinations\n",
    "Define the network configuration, in this case downloaded from OSM and clipped to a region polygon. Only specific road types are included."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f3538907",
   "metadata": {},
   "outputs": [],
   "source": [
    "network_section = NetworkSection(\n",
    "    source=SourceEnum.OSM_DOWNLOAD,\n",
    "    polygon=network_path.joinpath(\"region_polygon.geojson\"),\n",
    "    network_type=NetworkTypeEnum.DRIVE,\n",
    "    road_types=[\n",
    "        RoadTypeEnum.MOTORWAY,\n",
    "        RoadTypeEnum.MOTORWAY_LINK,\n",
    "        RoadTypeEnum.PRIMARY,\n",
    "        RoadTypeEnum.PRIMARY_LINK,\n",
    "        RoadTypeEnum.SECONDARY,\n",
    "        RoadTypeEnum.SECONDARY_LINK,\n",
    "        RoadTypeEnum.TERTIARY,\n",
    "        RoadTypeEnum.TERTIARY_LINK,\n",
    "        RoadTypeEnum.RESIDENTIAL,\n",
    "    ],\n",
    "    save_gpkg=True\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5f9de00",
   "metadata": {},
   "source": [
    "Define origins and destinations shapefiles using [OriginsDestinationsSection](../api/ra2ce.network.network_config_data.html#ra2ce.network.network_config_data.network_config_data.OriginsDestinationsSection){.api-ref}. Specify the shortcut names and attributes in the shapefiles."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f4fd7ef7",
   "metadata": {},
   "outputs": [],
   "source": [
    "origin_destination_section = OriginsDestinationsSection(\n",
    "    origins=network_path.joinpath(\"origins.shp\"),\n",
    "    destinations=network_path.joinpath(\"destinations.shp\"),\n",
    "    origin_count=\"POPULATION\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cccf801b",
   "metadata": {},
   "outputs": [],
   "source": [
    "network_config_data = NetworkConfigData(\n",
    "    root_path=root_dir,\n",
    "    static_path=root_dir.joinpath('static'),\n",
    "    network=network_section,\n",
    "    origins_destinations=origin_destination_section,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1137b9f6",
   "metadata": {},
   "source": [
    "## Step 3: Define the Analysis\n",
    "Specify the analysis type as [AnalysisLossesEnum.OPTIMAL_ROUTE_ORIGIN_DESTINATION](../api/ra2ce.analysis.analysis_config_data.enums.html#module-ra2ce.analysis.analysis_config_data.enums.analysis_losses_enum){.api-ref}, which calculates optimal routes for the OD pairs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1d29e31d",
   "metadata": {},
   "outputs": [],
   "source": [
    "analyse_section = AnalysisSectionLosses(\n",
    "    name=\"origin_destination_without_hazard\",\n",
    "    analysis=AnalysisLossesEnum.OPTIMAL_ROUTE_ORIGIN_DESTINATION,\n",
    "    weighing=WeighingEnum.LENGTH,\n",
    "    calculate_route_without_disruption=True,\n",
    "    save_csv=True,\n",
    "    save_gpkg=True,\n",
    ")\n",
    "\n",
    "analysis_config_data = AnalysisConfigData(\n",
    "    output_path=root_dir.joinpath(\"output\"),\n",
    "    static_path=root_dir.joinpath('static'),\n",
    "    analyses=[analyse_section],\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a2bd15f",
   "metadata": {},
   "source": [
    "## Step 4: Run the Analysis\n",
    "Use [Ra2ceHandler](../api/ra2ce.handler.html#ra2ce.ra2ce_handler.Ra2ceHandler){.api-ref} to configure and run the analysis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f10c566c",
   "metadata": {},
   "outputs": [],
   "source": [
    "handler = Ra2ceHandler.from_config(\n",
    "    network=network_config_data,\n",
    "    analysis=analysis_config_data\n",
    ")\n",
    "handler.configure()\n",
    "handler.run_analysis()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 5: Inspect Results\n",
    "Results are stored in the `output` folder and include both CSV and GeoPackage (GPKG) files. You can open the GPKG in GIS software or load it in Python using GeoPandas."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import geopandas as gpd\n",
    "\n",
    "results_gpkg = root_dir.joinpath(\n",
    "    \"output\", \n",
    "    \"optimal_route_origin_destination\",  \n",
    "    \"origin_destination_without_hazard.gpkg\"\n",
    ")\n",
    "gdf = gpd.read_file(results_gpkg)\n",
    "gdf.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Accessability of population to health centers]( /_resources/Beira_OD_no_hazard.png )\n",
    "All shortest routes from a chosen origin (red circle) to all possible destinations (green stars)."
   ]
  }
 ],
 "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
}