demos/csv_hierarchy.ipynb

{
 "cells": [
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "# CSV Hierarchies\n",
    "\n",
    "In this short demo notebook, we see how to describe the experiment hierarchy in a csv file. \n",
    "\n",
    "First we define the basics of a simple brightway based calculation, without any hierarchy"
   ],
   "id": "67acc06124cc828f"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-14T08:17:45.103002Z",
     "start_time": "2024-05-14T08:17:42.471951Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import pandas as pd\n",
    "\n",
    "from enbios import Experiment\n",
    "\n",
    "BRIGHTWAY_ECOINVENT_391_PROJECT_NAME = \"ecoinvent_391\"\n",
    "experiment_config = {\n",
    "    \"adapters\": [\n",
    "        {\n",
    "            \"adapter_name\": \"brightway-adapter\",\n",
    "            \"config\": {\"bw_project\": BRIGHTWAY_ECOINVENT_391_PROJECT_NAME},\n",
    "            \"methods\": {\n",
    "                \"GWP1000\": (\n",
    "                    \"ReCiPe 2016 v1.03, midpoint (H)\",\n",
    "                    \"climate change\",\n",
    "                    \"global warming potential (GWP1000)\",\n",
    "                )\n",
    "            },\n",
    "        }\n",
    "    ]\n",
    "}"
   ],
   "id": "initial_id",
   "execution_count": 1,
   "outputs": []
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "There are a couple of test files within enbios. ",
   "id": "dcc55ee023408ae1"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-14T08:17:45.111462Z",
     "start_time": "2024-05-14T08:17:45.104224Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import os\n",
    "from enbios.const import BASE_TEST_DATA_PATH\n",
    "\n",
    "csv_hierarchy_files = BASE_TEST_DATA_PATH / \"hierarchy_csvs/inputs/\"\n",
    "os.listdir(csv_hierarchy_files)\n",
    "# do not try out files ending with \"_x\", these are invalid test files"
   ],
   "id": "5c74fc396c144205",
   "execution_count": 2,
   "outputs": []
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "Let's look at a first very simple example: `hierarchy1.csv`",
   "id": "39ebf728911598de"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-14T08:17:45.133367Z",
     "start_time": "2024-05-14T08:17:45.113195Z"
    }
   },
   "cell_type": "code",
   "source": "pd.read_csv(csv_hierarchy_files / \"hierarchy1.csv\").fillna(\"\")",
   "id": "84be1da9ff209437",
   "execution_count": 3,
   "outputs": []
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "The columns which describe the structure of the hierarchy are named __`level_{i}`__. Basically how it internally works, is that it first checks for all columns, that have this structure: `level_<number>` and then sorts them alphabetically. You might want to check the order, if your hierarchy is very deep. Each row describes one node and the contents on one respective column defines the level. \n",
    "\n",
    "The __module__ column defines the adapter or aggregator for that node. Enbios will automatically specify the right option, since it basically just depends on if the node is at the bottom of the hierarchy (structural node - adapter) or not (functional node - aggregator).\n",
    "\n",
    "all other columns should start with `config.` and are values for the configuration. Enbios will consider all those columns as keys for a structured config dictionary, where `.` is used as a separator to create a nested dictionary, in case the config requires that.\n",
    "\n",
    "E.g. \n",
    "```\n",
    "config.loc.0, config.loc.1\n",
    "eu, es\n",
    "```\n",
    "will be turned into:\n",
    "`{'config': {'loc': ['eu', 'es']}}`\n",
    "\n",
    "Let's insert print the hierarchy"
   ],
   "id": "7069cfd595c49ccd"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-14T08:17:50.064569Z",
     "start_time": "2024-05-14T08:17:48.372266Z"
    }
   },
   "cell_type": "code",
   "source": [
    "experiment_config[\"hierarchy\"] = csv_hierarchy_files / \"hierarchy1.csv\"\n",
    "experiment = Experiment(experiment_config)\n",
    "\n",
    "experiment.get_simplified_hierarchy(print_it=True);"
   ],
   "id": "893861ae846bd6bb",
   "execution_count": 4,
   "outputs": []
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "A more complex example:",
   "id": "a9dd4aa481e56f12"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-14T08:17:50.074397Z",
     "start_time": "2024-05-14T08:17:50.066079Z"
    }
   },
   "cell_type": "code",
   "source": "pd.read_csv(csv_hierarchy_files / \"hierarchy4.csv\").fillna(\"\")",
   "id": "df89e275806b94f8",
   "execution_count": 5,
   "outputs": []
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-14T08:17:51.993912Z",
     "start_time": "2024-05-14T08:17:51.043955Z"
    }
   },
   "cell_type": "code",
   "source": [
    "experiment_config[\"hierarchy\"] = csv_hierarchy_files / \"hierarchy4.csv\"\n",
    "experiment = Experiment(experiment_config)\n",
    "\n",
    "experiment.get_simplified_hierarchy(print_it=True);"
   ],
   "id": "2f7b6ad96169daff",
   "execution_count": 6,
   "outputs": []
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "If it is crucial to use different level column names you can call the function `csv2hierarchy` directly and passing one of the two arguments:\n",
    "`level_cols` a list of strings, which include the columns which specify the names of nodes or `levels_regex` (which is the default with the regular expression : `^level_\\d+$`. The result is a dictionary which can be inserted into the experiment config as the hierarchy."
   ],
   "id": "c1269da612ffd6b1"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-14T08:17:56.305577Z",
     "start_time": "2024-05-14T08:17:56.298751Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from enbios.base.tree_operations import csv2hierarchy\n",
    "\n",
    "csv2hierarchy(csv_hierarchy_files / \"hierarchy4.csv\")"
   ],
   "id": "9c6ed27120694972",
   "execution_count": 7,
   "outputs": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}