Add cookbook example of US energy consumption Sankey

Thanks to John Muth for the suggestion and transcribing the data.

docs/cookbook/us-energy-consumption-processes.csv

@@ -0,0 +1,14 @@
+id,type
+Solar,source
+Nuclear,source
+Hydro,source
+Wind,source
+Geothermal,source
+Natural_Gas,source
+Coal,source
+Biomass,source
+Petroleum,source
+Residential,use
+Commercial,use
+Industrial,use
+Transportation,use

docs/cookbook/us-energy-consumption.csv

@@ -0,0 +1,44 @@
+source,target,type,value
+Solar,Electricity_Generation,Solar,0.61
+Solar,Residential,Solar,0.22
+Solar,Commercial,Solar,0.1
+Solar,Industrial,Solar,0.03
+Nuclear,Electricity_Generation,Nuclear,8.44
+Hydro,Electricity_Generation,Hydro,2.67
+Hydro,Electricity_Generation,Hydro,0.01
+Wind,Electricity_Generation,Wind,2.53
+Geothermal,Electricity_Generation,Geothermal,0.15
+Geothermal,Residential,Geothermal,0.04
+Geothermal,Commercial,Geothermal,0.02
+Natural_Gas,Electricity_Generation,Natural_Gas,11
+Natural_Gas,Residential,Natural_Gas,5.15
+Natural_Gas,Commercial,Natural_Gas,3.61
+Natural_Gas,Industrial,Natural_Gas,10.4
+Natural_Gas,Transportation,Natural_Gas,0.87
+Coal,Electricity_Generation,Coal,12.1
+Coal,Commercial,Coal,0.02
+Coal,Industrial,Coal,1.2
+Biomass,Electricity_Generation,Biomass,0.5
+Biomass,Residential,Biomass,0.52
+Biomass,Commercial,Biomass,0.15
+Biomass,Industrial,Biomass,2.55
+Biomass,Transportation,Biomass,1.41
+Petroleum,Electricity_Generation,Petroleum,0.24
+Petroleum,Residential,Petroleum,0.96
+Petroleum,Commercial,Petroleum,0.85
+Petroleum,Industrial,Petroleum,8.86
+Petroleum,Transportation,Petroleum,26
+Net_Electricity_Import,Residential,Electricity,0.05
+Electricity_Generation,Residential,Electricity,5
+Electricity_Generation,Commercial,Electricity,4.7
+Electricity_Generation,Industrial,Electricity,3.25
+Electricity_Generation,Transportation,Electricity,0.03
+Electricity_Generation,Rejected_Energy,Rejected energy,25.3
+Residential,Rejected_Energy,Rejected energy,4.16
+Commercial,Rejected_Energy,Rejected energy,3.31
+Industrial,Rejected_Energy,Rejected energy,13.4
+Transportation,Rejected_Energy,Rejected energy,22.4
+Residential,Energy_Services,Energy services,7.72
+Commercial,Energy_Services,Energy services,6.14
+Industrial,Energy_Services,Energy services,12.9
+Transportation,Energy_Services,Energy services,5.95

docs/cookbook/us-energy-consumption.ipynb

@@ -0,0 +1,180 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# US energy consumption\n",
+    "\n",
+    "This example is based on the [Sankey diagrams of US energy consumption from the Lawrence Livermore National Laboratory](https://flowcharts.llnl.gov/) (thanks to John Muth for the suggestion and transcribing the data). We jump straight to the final result – for more explanation of the steps and concepts, see the [tutorials](../tutorials/index.ipynb)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from floweaver import *"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Load the dataset:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dataset = Dataset.from_csv('us-energy-consumption.csv',\n",
+    "                           dim_process_filename='us-energy-consumption-processes.csv')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This defines the order the nodes appear in:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sources = ['Solar', 'Nuclear', 'Hydro', 'Wind', 'Geothermal',\n",
+    "           'Natural_Gas', 'Coal', 'Biomass', 'Petroleum']\n",
+    "\n",
+    "uses = ['Residential', 'Commercial', 'Industrial', 'Transportation']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now define the Sankey diagram definition."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nodes = {\n",
+    "    'sources': ProcessGroup('type == \"source\"', Partition.Simple('process', sources), title='Sources'),\n",
+    "    'imports': ProcessGroup(['Net_Electricity_Import'], title='Net electricity imports'),\n",
+    "    'electricity': ProcessGroup(['Electricity_Generation'], title='Electricity Generation'),\n",
+    "    'uses': ProcessGroup('type == \"use\"', partition=Partition.Simple('process', uses)),\n",
+    "    \n",
+    "    'energy_services': ProcessGroup(['Energy_Services'], title='Energy services'),\n",
+    "    'rejected': ProcessGroup(['Rejected_Energy'], title='Rejected energy'),\n",
+    "    \n",
+    "    'direct_use': Waypoint(Partition.Simple('source', [\n",
+    "        # This is a hack to hide the labels of the partition, there should be a better way...\n",
+    "        (' '*i, [k]) for i, k in enumerate(sources)\n",
+    "    ])),\n",
+    "}\n",
+    "\n",
+    "ordering = [\n",
+    "    [[], ['sources'], []],\n",
+    "    [['imports'], ['electricity', 'direct_use'], []],\n",
+    "    [[], ['uses'], []],\n",
+    "    [[], ['rejected', 'energy_services'], []]\n",
+    "]\n",
+    "\n",
+    "bundles = [\n",
+    "    Bundle('sources', 'electricity'),\n",
+    "    Bundle('sources', 'uses', waypoints=['direct_use']),\n",
+    "    Bundle('electricity', 'uses'),\n",
+    "    Bundle('imports', 'uses'),\n",
+    "    Bundle('uses', 'energy_services'),\n",
+    "    Bundle('uses', 'rejected'),\n",
+    "    Bundle('electricity', 'rejected'),\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Define the colours to roughly imitate the original Sankey diagram:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "palette = {\n",
+    "    'Solar': 'gold',\n",
+    "    'Nuclear': 'red',\n",
+    "    'Hydro': 'blue',\n",
+    "    'Wind': 'purple',\n",
+    "    'Geothermal': 'brown',\n",
+    "    'Natural_Gas': 'steelblue',\n",
+    "    'Coal': 'black',\n",
+    "    'Biomass': 'lightgreen',\n",
+    "    'Petroleum': 'green',\n",
+    "    'Electricity': 'orange',\n",
+    "    'Rejected energy': 'lightgrey',\n",
+    "    'Energy services': 'dimgrey',\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And here's the result!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sdd = SankeyDefinition(nodes, bundles, ordering,\n",
+    "                       flow_partition=dataset.partition('type'))\n",
+    "weave(sdd, dataset, palette=palette) \\\n",
+    "    .to_widget(width=700, height=450, margins=dict(left=100, right=120), debugging=True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.7.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}