Add cookbook notebook showing how to set scale (and update nbconvert)

Since version 5.5 nbconvert can save the widget state, so my fork is no longer
needed. This fixes builds on readthedocs.

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
 -----------------

docs/requirements.txt

@@ -1,12 +1,13 @@
 # requirements for building documentation
-nbsphinx
-git+git://github.com/ricklupton/nbconvert@execute-widgets#egg=nbconvert
+sphinx >=3,<4
+nbsphinx==0.6.1
+nbconvert >=5.5
 jupyter_client
 ipykernel
 numpy
 pandas
-networkx >=1,<2
-attrs
+networkx >=2.1
+attrs >=17.4
 palettable
 ipysankeywidget
 matplotlib