{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "165ddf56",
   "metadata": {},
   "source": [
    "# EUROSTAT\n",
    "\n",
    "This notebook mirrors the EUROSTAT parser guide.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d95b611",
   "metadata": {},
   "source": [
    "## Main entry point\n",
    "\n",
    "Use `mario.parse_eurostat(...)` for both `SUT` and `IOT` workflows against the official Eurostat SDMX API.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "key-arguments",
   "metadata": {},
   "source": [
    "## Key arguments\n",
    "\n",
    "The key public arguments are:\n",
    "\n",
    "- `country`: Eurostat geo code such as `IT` or `DE`\n",
    "- `year`: reference year to parse\n",
    "- `table`: choose `\"SUT\"` or `\"IOT\"`\n",
    "- `iot_mode`: IOT-only selector, either `\"product\"` or `\"industry\"`\n",
    "- `unit`: choose `\"MIO_EUR\"` or `\"MIO_NAC\"`\n",
    "- `path`: optional local cache directory for raw SDMX CSV files\n",
    "- `download`: when `True`, MARIO stores the raw CSV locally before parsing it\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfc18687",
   "metadata": {},
   "source": [
    "## Available years\n",
    "\n",
    "Year availability depends on the country and on the table family.\n",
    "\n",
    "- Official Eurostat metadata states that national `SUT` annual tables are published from `2010` onward.\n",
    "- Official Eurostat metadata also states that national `IOT` tables are published from `2010` onward, but mandatory transmission is only for years ending in `0` or `5`.\n",
    "- Additional `IOT` years depend on voluntary country transmission.\n",
    "\n",
    "On the live official API, checked on **18 April 2026** with **Italy (`IT`)** as one concrete example, MARIO currently finds:\n",
    "\n",
    "- `SUT`: `2010` to `2022`\n",
    "- `IOT`: `2010` and then `2015` to `2022`\n",
    "\n",
    "So for `SUT` you should expect a broadly annual series, while for `IOT` you should treat `2010`, `2015`, and `2020` as the core mandatory years and any extra years as country-specific.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ed6b83b3",
   "metadata": {},
   "source": [
    "## Relevant source pages and local cache\n",
    "\n",
    "Relevant official pages:\n",
    "\n",
    "- [ESA supply, use and input-output tables](https://ec.europa.eu/eurostat/web/esa-supply-use-input-tables)\n",
    "- [Eurostat metadata for `naio_10_n`](https://ec.europa.eu/eurostat/cache/metadata/en/naio_10_n_esms.htm)\n",
    "- [Eurostat API introduction](https://ec.europa.eu/eurostat/web/user-guides/data-browser/api-data-access/api-introduction)\n",
    "\n",
    "`path` is optional and, when provided, acts as a raw SDMX cache:\n",
    "\n",
    "```text\n",
    "EUROSTAT/\n",
    "└── cache/\n",
    "    ├── NAIO_10_CP15_*.csv\n",
    "    ├── NAIO_10_CP16_*.csv\n",
    "    ├── NAIO_10_CP1700_*.csv\n",
    "    └── NAIO_10_CP1750_*.csv\n",
    "```\n",
    "\n",
    "If `download=False`, MARIO reads directly from the API. If `download=True`, MARIO stores the raw slices under `path` before building the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "107e8876",
   "metadata": {},
   "outputs": [],
   "source": [
    "import mario"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5046af8",
   "metadata": {},
   "source": [
    "## Parse a SUT directly from the API\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "75323e57",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: requesting Eurostat NAIO_10_CP15 for IT 2022 MIO_EUR.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: requesting Eurostat NAIO_10_CP16 for IT 2022 MIO_EUR.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: Eurostat SUT payload ready with shapes S=(65, 65), U=(65, 65), Yc=(65, 3), Va=(6, 65), Vc=(6, 65).\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "name = Eurostat SUT IT 2022\n",
       "table = SUT\n",
       "tech_assumption = industry-based\n",
       "scenarios = ['baseline']\n",
       "Activity = 65\n",
       "Commodity = 65\n",
       "Factor of production = 6\n",
       "Satellite account = 1\n",
       "Consumption category = 3\n",
       "Region = 1"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db = mario.parse_eurostat(\n",
    "    country=\"IT\",\n",
    "    year=2022,\n",
    "    table=\"SUT\",\n",
    ")\n",
    "\n",
    "db"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62bfab42",
   "metadata": {},
   "source": [
    "## Parse an IOT\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "cffa80d1",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: requesting Eurostat NAIO_10_CP1700 for IT 2022 MIO_EUR.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: Eurostat IOT payload ready with shapes Z=(65, 65), Y=(65, 3), V=(6, 65), mode=product.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "name = Eurostat IOT IT 2022 product\n",
       "table = IOT\n",
       "scenarios = ['baseline']\n",
       "Factor of production = 6\n",
       "Satellite account = 1\n",
       "Consumption category = 3\n",
       "Region = 1\n",
       "Sector = 65"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db = mario.parse_eurostat(\n",
    "    country=\"IT\",\n",
    "    year=2022,\n",
    "    table=\"IOT\",\n",
    "    iot_mode=\"product\",\n",
    ")\n",
    "\n",
    "db"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d622593f",
   "metadata": {},
   "source": [
    "## Optional raw download and cache\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "7f027399",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'table': 'SUT',\n",
       " 'country': 'IT',\n",
       " 'year': 2022,\n",
       " 'unit': 'MIO_EUR',\n",
       " 'iot_mode': None,\n",
       " 'files': {'supply': '/path/to/eurostat_cache/NAIO_10_CP15_IT_2022_MIO_EUR.csv',\n",
       "  'use': '/path/to/eurostat_cache/NAIO_10_CP16_IT_2022_MIO_EUR.csv'}}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mario.download_eurostat(\n",
    "    path=\"/path/to/SUT\",\n",
    "    country=\"IT\",\n",
    "    year=2022,\n",
    "    table=\"SUT\",\n",
    ")"
   ]
  }
 ],
 "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.11.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
