{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "title",
   "metadata": {},
   "source": [
    "# OECD parser walkthrough\n",
    "\n",
    "This notebook is the practical guide for parsing OECD tables in MARIO."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "covers",
   "metadata": {},
   "source": [
    "## What this notebook covers\n",
    "\n",
    "- where each OECD table family comes from;\n",
    "- when to pass a direct file path and when to pass a directory;\n",
    "- how `dataset=`, `year=`, and `country=` change the parser workflow;\n",
    "- the difference between `ICIO`, national `IOT`, and `SUT` parsing;\n",
    "- the current limitation that OECD tables are parsed as economic tables only."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "sources",
   "metadata": {},
   "source": [
    "## Relevant source pages\n",
    "\n",
    "- OECD ICIO page: [Inter-country input-output tables](https://www.oecd.org/en/data/datasets/inter-country-input-output-tables.html)\n",
    "- OECD national IOT page: [Input-output tables](https://www.oecd.org/en/data/datasets/input-output-tables.html)\n",
    "- OECD SUT page: [Supply and use tables](https://www.oecd.org/en/data/datasets/supply-and-use-tables.html)\n",
    "\n",
    "MARIO does not download OECD files automatically. For `ICIO` and national `IOT`, the expected workflow is to download the source files manually and then point the parser to the local files. For `SUT`, MARIO pulls the data directly from the official OECD SDMX API."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "entry-point",
   "metadata": {},
   "source": [
    "## Main entry point\n",
    "\n",
    "For normal user workflows, the public entry point is:\n",
    "\n",
    "- `mario.parse_oecd(...)`\n",
    "\n",
    "The same function currently supports:\n",
    "\n",
    "- OECD `ICIO` csv bundles;\n",
    "- OECD national total-table `IOT` csv files;\n",
    "- OECD `SUT` tables through the official SDMX API."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "key-arguments",
   "metadata": {},
   "source": [
    "## Key arguments\n",
    "\n",
    "The key public arguments are:\n",
    "\n",
    "- `path`: one local OECD file or one directory containing multiple OECD files;\n",
    "- `dataset`: choose `\"ICIO\"`, `\"IOT\"`, or `\"SUT\"`;\n",
    "- `year`: used to disambiguate directories and required for `dataset=\"SUT\"`;\n",
    "- `country`: used to disambiguate national IOT files and required for `dataset=\"SUT\"`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-vs-directory",
   "metadata": {},
   "source": [
    "## Direct file path vs directory path\n",
    "\n",
    "Use a **direct file path** when you already know the exact OECD file to parse. This is the simplest workflow and usually means you do not need any further disambiguation.\n",
    "\n",
    "Use a **directory path** when you keep several OECD files together. In that case MARIO scans the directory and then uses `dataset=`, `year=`, and sometimes `country=` to pick the correct candidate."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3f2aed8",
   "metadata": {},
   "source": [
    "## Expected local layouts and caveats\n",
    "\n",
    "Typical local layouts are:\n",
    "\n",
    "For `dataset=\"ICIO\"`:\n",
    "\n",
    "```text\n",
    "OECD/ICIO/\n",
    "├── Extended/\n",
    "│   └── 2022.csv\n",
    "└── Regular/\n",
    "    └── 2022_SML.csv\n",
    "```\n",
    "\n",
    "For `dataset=\"IOT\"`:\n",
    "\n",
    "```text\n",
    "OECD/IOT/TTL/\n",
    "└── ITA2022ttl.csv\n",
    "```\n",
    "\n",
    "For `dataset=\"SUT\"`, `path` is not required; use `country=` and `year=` to select the SDMX slice.\n",
    "\n",
    "Practical caveats:\n",
    "\n",
    "- the `IOT` workflow supports only the OECD accounts labeled as total table;\n",
    "- in the extended `ICIO` release, `CN1` and `CN2` are aggregated automatically into `CHN`, and `MX1` and `MX2` into `MEX`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "import-mario",
   "metadata": {},
   "outputs": [],
   "source": [
    "import mario"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "parse-icio",
   "metadata": {},
   "source": [
    "## Parse one explicit OECD ICIO csv\n",
    "\n",
    "Use this when you want to point MARIO to one exact `ICIO` file, either regular or extended."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "parse-icio-code",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: reading OECD ICIO file 2019_SML.csv.\n",
      "INFO Parser: OECD ICIO parsed with 81 sector regions, 50 sectors, 486 final-demand columns and 2 factor rows.\n",
      "INFO Metadata: initialized.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "name = OECD ICIO 2019 regular\n",
       "table = IOT\n",
       "scenarios = ['baseline']\n",
       "Factor of production = 2\n",
       "Satellite account = 1\n",
       "Consumption category = 6\n",
       "Region = 81\n",
       "Sector = 50"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db = mario.parse_oecd(\n",
    "    path=\"/path/to/2022_SML.csv\",\n",
    "    dataset=\"ICIO\",\n",
    ")\n",
    "\n",
    "db"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "parse-iot",
   "metadata": {},
   "source": [
    "## Parse one national OECD total-table IOT\n",
    "\n",
    "Use this when you want one national total table such as `CZE2014ttl.csv`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "parse-iot-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "db = mario.parse_oecd(\n",
    "    path=\"/path/to/ITA2022ttl.csv\",\n",
    "    dataset=\"IOT\",\n",
    ")\n",
    "\n",
    "db"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "parse-sut",
   "metadata": {},
   "source": [
    "## Parse one OECD SUT directly from the SDMX API\n",
    "\n",
    "In principle, this workflow does not require a local `path`, but it does require `country=` and `year=`.\n",
    "\n",
    "At the moment we do **not** show an executable example in the documentation because the official OECD SDMX endpoint can intermittently refuse the request with HTTP errors such as `403 Forbidden`. When that happens, the issue is upstream of MARIO's SUT transformation logic and the parse cannot complete.\n",
    "\n",
    "For this reason, treat `dataset=\"SUT\"` as temporarily unstable in the public docs until the OECD SDMX service becomes reliably accessible again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bf1bed4d",
   "metadata": {},
   "outputs": [],
   "source": [
    "db = mario.parse_oecd(\n",
    "    dataset=\"SUT\",\n",
    "    country=\"ITA\",\n",
    "    year=2022,\n",
    ")\n",
    "\n",
    "db"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "warning-extensions",
   "metadata": {},
   "source": [
    "## Environmental extensions\n",
    "\n",
    "**Warning.** The OECD parser currently exposes the economic tables only.\n",
    "\n",
    "`ICIO`, national `IOT`, and `SUT` tables are therefore **not** parsed as environmentally extended tables in MARIO at the moment."
   ]
  }
 ],
 "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
}
