From 71fcb8909a55a26cfdb3c07c2f5d6f8b000c7976 Mon Sep 17 00:00:00 2001
From: Rick Lupton <mail@ricklupton.name>
Date: Fri, 24 Apr 2020 16:07:17 +0100
Subject: [PATCH] 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 | 152 ++++++++++++++++++++++++++++++++++++++
 docs/index.rst            |   1 +
 docs/requirements.txt     |   9 ++-
 3 files changed, 158 insertions(+), 4 deletions(-)
 create mode 100644 docs/cookbook/scale.ipynb

diff --git a/docs/cookbook/scale.ipynb b/docs/cookbook/scale.ipynb
new file mode 100644
index 0000000..f1a4e9c
--- /dev/null
+++ b/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
+}
diff --git a/docs/index.rst b/docs/index.rst
index 8ac68fa..71c67b0 100644
--- a/docs/index.rst
+++ b/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
 -----------------
diff --git a/docs/requirements.txt b/docs/requirements.txt
index a55a455..e08d668 100644
--- a/docs/requirements.txt
+++ b/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