Add cookbook notebook showing how to set scale

docs/cookbook/scale.ipynb

@@ -0,0 +1,152 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Setting the scale\n",
+    "\n",
+    "This recipe demonstrates how the scale of the Sankey diagram is set.\n",
+    "\n",
+    "By default the scale is calculated for each diagram to achieve a certain whitespace-to-flow ratio within the height that is given. But in some cases, you may want to set the scale explicitly.\n",
+    "\n",
+    "For demonstration, the CSV data is written directly in the cell below -- in practice you would want to load data a file."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "from io import StringIO\n",
+    "\n",
+    "flows = pd.read_csv(StringIO(\"\"\"\n",
+    "year,source,target,value\n",
+    "2020,A,B,10\n",
+    "2025,A,B,20\n",
+    "\"\"\"))\n",
+    "\n",
+    "flows"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from floweaver import *\n",
+    "\n",
+    "# Set the default size to fit the documentation better.\n",
+    "size = dict(width=100, height=100,\n",
+    "            margins=dict(left=20, right=20, top=10, bottom=10))\n",
+    "\n",
+    "nodes = {\n",
+    "    'A': ProcessGroup(['A']),\n",
+    "    'B': ProcessGroup(['B']),\n",
+    "}\n",
+    "\n",
+    "bundles = [\n",
+    "    Bundle('A', 'B'),\n",
+    "]\n",
+    "\n",
+    "ordering = [['A'], ['B']]\n",
+    "\n",
+    "sdd = SankeyDefinition(nodes, bundles, ordering)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we draw the flow for the year 2020 and the year 2025 separately, they appear the same:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "w1 = weave(sdd, flows.query('year == 2020')).to_widget(**size)\n",
+    "w1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "w2 = weave(sdd, flows.query('year == 2025')).to_widget(**size)\n",
+    "w2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "But in fact they have different scales:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "w1.scale, w2.scale"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The units of the scale are `units-of-value` per pixel.\n",
+    "\n",
+    "If we draw the Sankeys again while setting the scale, we can see that the flow indeed has changed between years:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "SCALE = 2.0\n",
+    "\n",
+    "from ipywidgets import HBox\n",
+    "\n",
+    "w1 = weave(sdd, flows.query('year == 2020')).to_widget(**size)\n",
+    "w2 = weave(sdd, flows.query('year == 2025')).to_widget(**size)\n",
+    "\n",
+    "w1.scale = w2.scale = SCALE\n",
+    "\n",
+    "HBox([w1, w2])"
+   ]
+  }
+ ],
+ "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": 2
+}

docs/index.rst

@@ -67,6 +67,7 @@ paper:
    cookbook/forwards-backwards
    cookbook/hybrid-sankey-diagrams-paper-fruit-example
    cookbook/us-energy-consumption
+   cookbook/scale
 
 API Documentation
 -----------------