{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "bea-title",
   "metadata": {},
   "source": [
    "# BEA parser walkthrough\n",
    "\n",
    "This notebook shows how to parse the official BEA `SUPPLY-USE` workbook family with `mario.parse_bea(...)`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bea-sources",
   "metadata": {},
   "source": [
    "## Where the files come from\n",
    "\n",
    "Relevant official pages:\n",
    "\n",
    "- [Industry Input-Output Accounts Data](https://www.bea.gov/industry/input-output-accounts-data)\n",
    "- [Guide to the interactive industry input-output accounts tables](https://www.bea.gov/resources/guide-interactive-industry-input-output-accounts-tables)\n",
    "- [Direct `SUPPLY-USE.zip` bundle](https://apps.bea.gov/industry/release/zip/SUPPLY-USE.zip)\n",
    "\n",
    "MARIO currently supports only the `SUPPLY-USE` bundle. It does not yet parse:\n",
    "\n",
    "- `MAKE-USE-IMPORTS (BEFORE REDEFINITIONS)`\n",
    "- `TOTAL AND DOMESTIC REQUIREMENTS`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bea-years",
   "metadata": {},
   "source": [
    "## Supported levels and years\n",
    "\n",
    "The parser currently supports three aggregation levels:\n",
    "\n",
    "- `summary`: `1997` to `2024`\n",
    "- `sector`: `1997` to `2024`\n",
    "- `detail`: `2007`, `2012`, `2017`\n",
    "\n",
    "These ranges were verified directly on the current official workbook bundle."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bea-paths",
   "metadata": {},
   "source": [
    "## Accepted path inputs\n",
    "\n",
    "`parse_bea(...)` accepts any of these:\n",
    "\n",
    "- the official `SUPPLY-USE.zip`\n",
    "- one extracted directory containing the BEA workbooks\n",
    "- one workbook path inside that directory\n",
    "\n",
    "In all cases you still provide:\n",
    "\n",
    "- `year=`\n",
    "- `level=`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "66f2da36",
   "metadata": {},
   "source": [
    "## Expected extracted structure and matrix mapping\n",
    "\n",
    "Typical extracted `SUPPLY-USE` bundle:\n",
    "\n",
    "```text\n",
    "SUPPLY-USE/\n",
    "├── Supply_Summary.xlsx\n",
    "├── Use_Summary.xlsx\n",
    "├── Supply_Sector.xlsx\n",
    "├── Use_Sector.xlsx\n",
    "├── Supply_Detail.xlsx\n",
    "└── Use_SUT_Detail.xlsx\n",
    "```\n",
    "\n",
    "`level=` selects the workbook pair and `year=` selects one year inside that pair.\n",
    "\n",
    "MARIO reads the bundle as a split-native `SUT`: `S` from the domestic-industry block of the supply workbook, `U` and `Yc` from the use workbook, `Va` from the use-workbook footer rows, and `Vc` from the supply-side columns such as imports, margins, and product taxes. The result should therefore be treated as a mixed-valuation `SUT`: basic-price supply and purchaser-price use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "bea-import",
   "metadata": {},
   "outputs": [],
   "source": [
    "import mario"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "bea-summary-example",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: BEA SUT payload ready with shapes S=(71, 73), U=(73, 71), Yc=(73, 19), Va=(11, 71), Vc=(11, 73).\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "name = BEA Supply-Use 2024 Summary\n",
       "table = SUT\n",
       "tech_assumption = industry-based\n",
       "scenarios = ['baseline']\n",
       "Activity = 71\n",
       "Commodity = 73\n",
       "Factor of production = 11\n",
       "Satellite account = 1\n",
       "Consumption category = 19\n",
       "Region = 1"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "db = mario.parse_bea(\n",
    "    path=\"/path/to/SUPPLY-USE\",\n",
    "    year=2024,\n",
    "    level=\"summary\",\n",
    ")\n",
    "\n",
    "db"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "bea-sector-example",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: BEA SUT payload ready with shapes S=(15, 17), U=(17, 15), Yc=(17, 5), Va=(11, 15), Vc=(11, 17).\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    }
   ],
   "source": [
    "db = mario.parse_bea(\n",
    "    path=\"/path/to/SUPPLY-USE\",\n",
    "    year=2024,\n",
    "    level=\"sector\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "bea-detail-example",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Parser: BEA SUT payload ready with shapes S=(402, 402), U=(402, 402), Yc=(402, 19), Va=(10, 402), Vc=(10, 402).\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO Metadata: initialized.\n"
     ]
    }
   ],
   "source": [
    "db = mario.parse_bea(\n",
    "    path=\"/path/to/SUPPLY-USE\",\n",
    "    year=2017,\n",
    "    level=\"detail\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bea-mapping",
   "metadata": {},
   "source": [
    "## What the parser builds\n",
    "\n",
    "MARIO reads the BEA bundle as a split-native `SUT`:\n",
    "\n",
    "- `S` from the BEA `Supply` workbook\n",
    "- `U` and `Yc` from the BEA `Use` workbook\n",
    "- `Va` from the use-workbook footer rows\n",
    "- `Vc` from the supply-workbook commodity-side columns for imports, CIF/FOB adjustments, trade and transport margins, and product taxes\n",
    "\n",
    "This is therefore a mixed-valuation table:\n",
    "\n",
    "- supply is read at basic prices\n",
    "- use is read at purchaser prices"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "bea-shapes",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "S (402, 402)\n",
      "U (402, 402)\n",
      "Yc (402, 19)\n",
      "Va (10, 402)\n",
      "Vc (10, 402)\n"
     ]
    }
   ],
   "source": [
    "base = db[\"baseline\"]\n",
    "for name in [\"S\", \"U\", \"Yc\", \"Va\", \"Vc\"]:\n",
    "    print(name, base[name].shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bea-caveats",
   "metadata": {},
   "source": [
    "## Caveats\n",
    "\n",
    "- `table=\"SUT\"` is the only supported mode right now.\n",
    "- The parser does not yet expose the separate `MAKE-USE-IMPORTS (BEFORE REDEFINITIONS)` bundle.\n",
    "- The parser does not treat `TOTAL AND DOMESTIC REQUIREMENTS` as raw database inputs.\n",
    "- `detail` coverage is much narrower than `summary` and `sector` in the current official release."
   ]
  }
 ],
 "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
}
