{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "from_pymrio-01",
   "metadata": {},
   "source": [
    "# pymrio parser walkthrough\n",
    "\n",
    "This walkthrough covers the `mario.parse_from_pymrio(...)` bridge from one in-memory `pymrio.IOSystem` to a `mario.Database`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "from_pymrio-02",
   "metadata": {},
   "source": [
    "## Main entry point\n",
    "\n",
    "- `mario.parse_from_pymrio(...)`\n",
    "- upstream object: `pymrio.IOSystem`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2e6607e",
   "metadata": {},
   "source": [
    "## Expected input and assignment patterns\n",
    "\n",
    "This parser expects one already-loaded `pymrio.IOSystem`, not a filesystem path.\n",
    "\n",
    "Key arguments:\n",
    "\n",
    "- `io`: the `pymrio.IOSystem` to convert;\n",
    "- `value_added`: dictionary or `\"all\"` selector for the factor side;\n",
    "- `satellite_account`: dictionary or `\"all\"` selector for the satellite side;\n",
    "- `include_meta`: when `True`, copy the upstream metadata trail into the MARIO notes.\n",
    "\n",
    "Both `value_added` and `satellite_account` can be one explicit dictionary or the shorthand `\"all\"`. Dictionary values can also be `\"all\"` or one slicer for part of an extension. With the `\"all\"` / `\"all\"` shorthand, MARIO looks for one factor-like extension such as `factor_inputs`, `factor_of_production`, `value_added`, or `primary_inputs`, and assigns the remaining extensions to satellites.\n",
    "\n",
    "The conversion result is an `IOT`, not a `SUT`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "from_pymrio-03",
   "metadata": {},
   "outputs": [],
   "source": [
    "import mario\n",
    "import pymrio"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "from_pymrio-04",
   "metadata": {},
   "source": [
    "## Parse one local EXIOBASE bundle with pymrio\n",
    "\n",
    "The path below is only an example. Replace it with your local EXIOBASE directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "from_pymrio-05",
   "metadata": {},
   "outputs": [],
   "source": [
    "io = pymrio.parse_exiobase3(\n",
    "    path=\"/path/to/IOT_2013_pxp.zip\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "from_pymrio-06",
   "metadata": {},
   "source": [
    "## Inspect available pymrio Extensions\n",
    "\n",
    "This helps you decide whether to pass explicit dictionaries or to rely on the `\"all\"` shorthand."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "from_pymrio-07",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['air_emissions',\n",
       " 'energy',\n",
       " 'factor_inputs',\n",
       " 'labour',\n",
       " 'land',\n",
       " 'material',\n",
       " 'nutrients',\n",
       " 'water']"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[\n",
    "    name\n",
    "    for name in dir(io)\n",
    "    if isinstance(getattr(io, name), pymrio.Extension)\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "from_pymrio-08",
   "metadata": {},
   "source": [
    "## Use the full shorthand\n",
    "\n",
    "When one unique factor-like Extension exists, you can use `value_added=\"all\"` and `satellite_account=\"all\"`. This is practical for EXIOBASE parsed through `pymrio`, where `factor_inputs` is the natural value-added block."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "from_pymrio-09",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.api.core_model:Metadata: initialized.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: resolving v for baseline.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: resolving v for baseline.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: trying v via formula build_iot_v_from_V_X.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: trying v via formula build_iot_v_from_V_X.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: resolved X via formula build_iot_X_from_z_Y (compute_method=auto, runtime=solve).\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: resolved X via formula build_iot_X_from_z_Y (compute_method=auto, runtime=solve).\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: resolved v via formula build_iot_v_from_V_X.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: resolved v via formula build_iot_v_from_V_X.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: resolving e for baseline.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: resolving e for baseline.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: trying e via formula build_iot_e_from_E_X.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: trying e via formula build_iot_e_from_E_X.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: resolved e via formula build_iot_e_from_E_X.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: resolved e via formula build_iot_e_from_E_X.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: resolving Z for baseline.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: resolving Z for baseline.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: trying Z via formula build_iot_Z_from_z_X.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: trying Z via formula build_iot_Z_from_z_X.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Resolver: resolved Z via formula build_iot_Z_from_z_X.\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "INFO:mario.compute.resolver:Resolver: resolved Z via formula build_iot_Z_from_z_X.\n"
     ]
    }
   ],
   "source": [
    "db = mario.parse_from_pymrio(\n",
    "    io=io,\n",
    "    value_added=\"all\",\n",
    "    satellite_account=\"all\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "8f3ab0d7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "name = EXIO_IOT_2013_pxp\n",
       "table = IOT\n",
       "scenarios = ['baseline']\n",
       "Factor of production = 9\n",
       "Satellite account = 725\n",
       "Consumption category = 7\n",
       "Region = 49\n",
       "Sector = 200"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b162df18",
   "metadata": {},
   "source": [
    "## Reference notes and caveats\n",
    "\n",
    "Upstream documentation: [pymrio documentation](https://pymrio.readthedocs.io/en/latest/index.html).\n",
    "\n",
    "This is not a file parser. It converts one already-loaded `pymrio.IOSystem`, so any filesystem layout requirements belong to the upstream `pymrio` parser that created `io`.\n",
    "\n",
    "Practical caveats:\n",
    "\n",
    "- every `pymrio.Extension` must be classified explicitly, either through one mapping or through the `\"all\"` shorthand;\n",
    "- the `\"all\"` / `\"all\"` shorthand works only when MARIO can infer one unique factor-like extension;\n",
    "- this is a conversion bridge, not a generic harmonizer between arbitrary `pymrio` objects and MARIO;\n",
    "- the resulting MARIO database is currently an `IOT`, not a `SUT`."
   ]
  }
 ],
 "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
}
