{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5f2c5fe1",
   "metadata": {},
   "source": [
    "# ADB parser walkthrough\n",
    "\n",
    "This notebook is the practical guide for parsing Asian Development Bank Excel workbooks in MARIO."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a7bd595",
   "metadata": {},
   "source": [
    "## What this notebook covers\n",
    "\n",
    "- where to download the economic and air-emissions workbooks;\n",
    "- when to pass a direct file path and when to pass a directory;\n",
    "- how `year=` and `economies=` are used to disambiguate MRIO releases;\n",
    "- how SRIO workbooks differ from MRIO workbooks;\n",
    "- how `add_extensions=` imports the ADB air-emissions table;\n",
    "- which parser warnings can appear and where to inspect them."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7b7b948f",
   "metadata": {},
   "source": [
    "## Relevant source pages\n",
    "\n",
    "- Official ADB MRIO and SRIO page: [ADB globalization portal](https://kidb.adb.org/globalization/current)\n",
    "- Official ADB air-emissions extensions page: [ADB environmentally extended MRIOT](https://kidb.adb.org/globalization/adb_environmentally_extended_multiregional_inputoutput_tables)\n",
    "\n",
    "MARIO does not download ADB workbooks automatically. The expected workflow is to download the `.xlsx` files manually from those pages and then point the parser to the local files."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3d55bbdc",
   "metadata": {},
   "source": [
    "## Main entry point\n",
    "\n",
    "For normal user workflows, the public entry point is:\n",
    "\n",
    "- `mario.parse_adb(...)`\n",
    "\n",
    "ADB parsing currently supports only `IOT` tables, but the same public function works with:\n",
    "\n",
    "- ADB `MRIO` workbooks;\n",
    "- ADB `SRIO` workbooks;\n",
    "- optional ADB air-emissions workbooks passed through `add_extensions=`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e48f2f7",
   "metadata": {},
   "source": [
    "## Key arguments\n",
    "\n",
    "The key public arguments are:\n",
    "\n",
    "- `path`: one ADB workbook or one directory containing multiple workbooks\n",
    "- `table`: currently only `\"IOT\"` is supported\n",
    "- `year`: used to disambiguate MRIO releases in one directory; mandatory for SRIO workbooks because one file contains multiple yearly sheets\n",
    "- `economies`: used when a directory contains multiple MRIO variants for the same year, such as `62`, `72`, or `74` economies\n",
    "- `add_extensions`: optional path to the ADB air-emissions workbook; this populates `E` and keeps `EY` zero-filled"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f95cc24",
   "metadata": {},
   "source": [
    "## Direct file path vs directory path\n",
    "\n",
    "Use a **direct workbook path** when you already know the exact file to parse. This is the simplest path and usually means you do not need `year=` or `economies=`.\n",
    "\n",
    "Use a **directory path** when you keep several ADB workbooks together. In that case MARIO scans the directory, finds the candidate workbook files, and then uses `year=` and optionally `economies=` to pick the correct one."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79451ad6",
   "metadata": {},
   "source": [
    "## Expected local layout and caveats\n",
    "\n",
    "Typical MRIO directory layout:\n",
    "\n",
    "```text\n",
    "ADB/\n",
    "├── 62 economies/\n",
    "│   └── ADB-MRIO-2024_*.xlsx\n",
    "├── 72 economies/\n",
    "│   └── ADB-MRIO72-2024_*.xlsx\n",
    "└── CO2/\n",
    "    └── 2023 EE-MRIOT (Air Emissions).xlsx\n",
    "```\n",
    "\n",
    "Typical SRIO workbook layout:\n",
    "\n",
    "```text\n",
    "ADB/SRIO/\n",
    "└── CAN IOT 2000, 2007-2024.xlsx\n",
    "```\n",
    "\n",
    "When `path` is a directory, use `year=` and, when needed, `economies=` to disambiguate the workbook. For SRIO workbooks, `year=` is mandatory because one file contains multiple yearly sheets. When `add_extensions=` is used, MARIO warns if the emissions workbook year or regional coverage does not match the economic table."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "91353b18",
   "metadata": {},
   "outputs": [],
   "source": [
    "import mario"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "444a39fe",
   "metadata": {},
   "source": [
    "## Parse one explicit MRIO workbook\n",
    "\n",
    "Use this when you want to point MARIO to one specific ADB MRIO workbook on disk."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11b14f0c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: reading ADB workbook ADB-MRIO-2024-August 2025.xlsx sheet ADB MRIO 2024.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: ADB MRIO parsed with 75 regions, 35 sectors, 375 final-demand columns and 6 factor rows.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    }
   ],
   "source": [
    "db_mrio = mario.parse_adb(\n",
    "    path=\"/path/to/ADB-MRIO-2024-August 2025.xlsx\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2dfac011",
   "metadata": {},
   "source": [
    "## Parse from a directory containing multiple MRIO releases\n",
    "\n",
    "This is the important case when one directory contains several ADB MRIO files. Typical examples are:\n",
    "\n",
    "- multiple years in the same folder;\n",
    "- multiple release variants for the same year, such as `62`, `72`, or `74` economies.\n",
    "\n",
    "In those cases, `year=` narrows the release year and `economies=` narrows the workbook variant."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "e6827b76",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: reading ADB workbook ADB-MRIO-2024-August 2025.xlsx sheet ADB MRIO 2024.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: ADB MRIO parsed with 75 regions, 35 sectors, 375 final-demand columns and 6 factor rows.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    }
   ],
   "source": [
    "db_mrio = mario.parse_adb(\n",
    "    path=\"/path/to/ADB\",\n",
    "    year=2024,\n",
    "    economies=74,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c422e807",
   "metadata": {},
   "source": [
    "If the directory contains only one MRIO workbook for the requested year, `year=` may be enough on its own."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "79dd9901",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: reading ADB workbook ADB-MRIO72-2023_July 2025.xlsx sheet ADB MRIO 2023.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: ADB MRIO parsed with 73 regions, 35 sectors, 365 final-demand columns and 6 factor rows.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    }
   ],
   "source": [
    "db_mrio = mario.parse_adb(\n",
    "    path=\"/path/to/ADB\",\n",
    "    year=2023,\n",
    "    economies=72,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "926390c4",
   "metadata": {},
   "source": [
    "## Parse one SRIO workbook\n",
    "\n",
    "ADB SRIO workbooks differ from MRIO workbooks in one key way: **one file contains multiple yearly sheets**. Because of that, `year=` is mandatory for SRIO parsing.\n",
    "\n",
    "From the user side, the parser call stays simple: you still use `mario.parse_adb(...)`, but now `year=` selects the annual sheet inside the workbook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "b4b53b5e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: reading ADB workbook ITA IOT 2000, 2007-2024.xlsx sheet 2024.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: ADB SRIO parsed with 35 sectors, 6 final-demand columns and 7 factor rows.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    }
   ],
   "source": [
    "db_srio = mario.parse_adb(\n",
    "    path=\"/path/to/ITA IOT 2000, 2007-2024.xlsx\",\n",
    "    year=2024,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8c0a964",
   "metadata": {},
   "source": [
    "## Add the ADB air-emissions extensions\n",
    "\n",
    "When the matching environmental workbook is available locally, pass it through `add_extensions=`. MARIO imports the environmental extension matrix `E` from that workbook and keeps `EY` zero-filled.\n",
    "\n",
    "The same argument works for both MRIO and SRIO economic tables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "ba377822",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: reading ADB workbook ADB-MRIO72-2023_July 2025.xlsx sheet ADB MRIO 2023.\n",
      "INFO Parser: ADB MRIO parsed with 73 regions, 35 sectors, 365 final-demand columns and 6 factor rows.\n",
      "INFO Parser: importing ADB air-emissions extensions from 2023 EE-MRIOT (Air Emissions).xlsx sheet 2023.\n",
      "INFO Metadata: initialized.\n"
     ]
    }
   ],
   "source": [
    "db_mrio_ext = mario.parse_adb(\n",
    "    path=\"/path/to/ADB-MRIO-2024-August 2025.xlsx\",\n",
    "    add_extensions=\"/path/to/2023 EE-MRIOT (Air Emissions).xlsx\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "f28a690e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "name = ADB MRIO 2023 (72 economies)\n",
       "table = IOT\n",
       "scenarios = ['baseline']\n",
       "Factor of production = 6\n",
       "Satellite account = 80\n",
       "Consumption category = 5\n",
       "Region = 73\n",
       "Sector = 35"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db_mrio_ext"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "dffd45f9",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: reading ADB workbook ITA IOT 2000, 2007-2024.xlsx sheet 2024.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: ADB SRIO parsed with 35 sectors, 6 final-demand columns and 7 factor rows.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: importing ADB air-emissions extensions from 2023 EE-MRIOT (Air Emissions).xlsx sheet 2023.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "WARNING Parser: ADB emissions year 2023 does not match the economic table year 2024.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    }
   ],
   "source": [
    "db_srio_ext = mario.parse_adb(\n",
    "    path=\"/path/to/ITA IOT 2000, 2007-2024.xlsx\",\n",
    "    year=2024,\n",
    "    add_extensions=\"/path/to/2023 EE-MRIOT (Air Emissions).xlsx\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63f14cec",
   "metadata": {},
   "source": [
    "## Parser warnings you may see\n",
    "\n",
    "When `add_extensions=` is used, MARIO can record parser warnings in the metadata history. The two relevant cases are:\n",
    "\n",
    "- the emissions workbook year does not match the economic table year;\n",
    "- the emissions workbook does not cover all regions present in the economic table.\n",
    "\n",
    "The second case matters mainly for MRIO releases where the economic table contains regions not present in the emissions workbook. The parse still succeeds, but MARIO records the mismatch."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12b84acb",
   "metadata": {},
   "source": [
    "A simple way to inspect those parser notes is to check the metadata history after parsing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "38c3e26f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[2026-04-29 10:50:11]    Table added into metadata with value equal to IOT.\n",
      "[2026-04-29 10:50:11]    Price added into metadata with value equal to Current prices.\n",
      "[2026-04-29 10:50:11]    Source added into metadata with value equal to Asian Development Bank MRIO Excel workbooks via https://kidb.adb.org/globalization/current.\n",
      "[2026-04-29 10:50:11]    Year added into metadata with value equal to 2024.\n",
      "[2026-04-29 10:50:11]    Tech_Assumption added into metadata with value equal to None.\n",
      "[2026-04-29 10:50:11]    Parser: ADB emissions year 2023 does not match the economic table year 2024.\n",
      "[2026-04-29 10:50:11]    Parser: ADB emissions workbook does not cover database regions ['TAJ', 'UZB']; zero satellite values were kept for those regions.\n"
     ]
    }
   ],
   "source": [
    "db_mrio_ext.meta_history"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19f81e5d",
   "metadata": {},
   "source": [
    "## Inspect the parsed database\n",
    "\n",
    "Once parsed, the result is a standard MARIO database. At that point the normal exploration tools apply."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "8e874e44",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "name = ADB MRIO 2024 (74 economies)\n",
       "table = IOT\n",
       "scenarios = ['baseline']\n",
       "Factor of production = 6\n",
       "Satellite account = 80\n",
       "Consumption category = 5\n",
       "Region = 75\n",
       "Sector = 35"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db_mrio_ext"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "mario",
   "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.13.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
