D3.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Callysto.ca Banner](https://github.com/callysto/curriculum-notebooks/blob/master/callysto-notebook-banner-top.jpg?raw=true)\n",
    "\n",
    "<a href=\"https://hub.callysto.ca/jupyter/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2Fcallysto%2Fshorts&branch=master&subPath=D3.ipynb&depth=1\" target=\"_parent\"><img src=\"https://raw.githubusercontent.com/callysto/curriculum-notebooks/master/open-in-callysto-button.svg?sanitize=true\" width=\"123\" height=\"24\" alt=\"Open in Callysto\"/></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Animations in D3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<div id=\"myDisplay\"></div>\n",
       "<script> \n",
       "    require.config({paths: {d3: \"https://d3js.org/d3.v5.min\"}});\n",
       "    require([\"d3\"], function(d3) {\n",
       "        var mySVG = d3.select(\"#myDisplay\") \n",
       "          .append(\"svg\")\n",
       "          .attr(\"width\", 300)\n",
       "          .attr(\"height\", 300);    \n",
       "       mySVG.append(\"circle\")\n",
       "          .style(\"fill\", \"red\")\n",
       "          .attr(\"r\", 130)\n",
       "          .attr(\"cx\", 150)\n",
       "          .attr(\"cy\", 150)\n",
       "          .transition()\n",
       "             .delay(100)\n",
       "             .duration(20000)  \n",
       "             .attr(\"r\", 10)\n",
       "             .attr(\"cx\", 290)\n",
       "             .style(\"fill\", \"blue\");             \n",
       "    });\n",
       "</script>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.core.display import display, HTML\n",
    "\n",
    "html_text = '''\n",
    "<div id=\"myDisplay\"></div>\n",
    "<script> \n",
    "    require.config({paths: {d3: \"https://d3js.org/d3.v5.min\"}});\n",
    "    require([\"d3\"], function(d3) {\n",
    "        var mySVG = d3.select(\"#myDisplay\") \n",
    "          .append(\"svg\")\n",
    "          .attr(\"width\", 300)\n",
    "          .attr(\"height\", 300);    \n",
    "       mySVG.append(\"circle\")\n",
    "          .style(\"fill\", \"red\")\n",
    "          .attr(\"r\", 130)\n",
    "          .attr(\"cx\", 150)\n",
    "          .attr(\"cy\", 150)\n",
    "          .transition()\n",
    "             .delay(100)\n",
    "             .duration(20000)  \n",
    "             .attr(\"r\", 10)\n",
    "             .attr(\"cx\", 290)\n",
    "             .style(\"fill\", \"blue\");             \n",
    "    });\n",
    "</script>\n",
    "'''\n",
    "\n",
    "display(HTML(html_text))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reload the page\n",
    "to restart the animation. It only runs for 20 seconds."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notes on the above animation\n",
    "\n",
    "This is a very simple D3 animation, which should work in any Jupyter hub as well as on a Jupyter book. We kept is as simple as possible, to show the main feature of how to use D3 in a Jupyter noteboo.\n",
    "\n",
    "In the above code, we create some html text which includes a place (**div**) to display some material, then some javascript code (**script**) to create an svg canvas to draw in, then draw a circle and animate it. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notes on D3\n",
    "\n",
    "D3 is an amazing collection of tools for creating Data Driven Documents (DDD = D3). It is also a great tool for creating animations. You can read about it here: https://d3js.org/\n",
    "\n",
    "Several issues arise in using D3. First, it is written in Javascript so you need to learn Javascript to do this well. Second, your Jupyter notebook has security measures in place to avoid what it suspects might be malicious (dangerous) code. Third, the D3 libraries and the Jupyter security keeps changing, so code you write today may become inoperative in a just a few months. So be carefu!\n",
    "\n",
    "To learn **Javascript** you can search online for tutorials.\n",
    "\n",
    "To get your notebook to **bypass security,** we write the Javascript code in into a text file, then use the **display** and **HTML** functions from module **IPython.core.display**  This is what works in Summer 2020. Last year, we did it a different way, which no longer works. We then use some Python code to load in this .html code. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Fancier code\n",
    "\n",
    "Often we like to split up our HTML code into portions for CSS commansd (Cascading Style Sheets), Javascipt code, and then the body of the HTML document.\n",
    "\n",
    "Here is an example we found at: https://www.bogotobogo.com/python/IPython/iPython_Jupyter_Notebook_with_Embedded_D3.php\n",
    "\n",
    "**First step** is to load in the a few Python modules to help us out. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.core.display import display, HTML\n",
    "from string import Template\n",
    "import json"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Next,** we create an HTML template, some CSS text (empty) and a Javascript template. We will pass variables and text to the templates using the substitute command. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "html_template = Template('''\n",
    "<style> $css_text </style>\n",
    "<div id=\"animation\"></div>\n",
    "<script> $js_text </script>\n",
    "''')\n",
    "\n",
    "css_text = '''\n",
    "'''\n",
    "\n",
    "js_text_template = Template('''\n",
    "    require.config({paths: {d3: \"https://d3js.org/d3.v5.min\"}});\n",
    "    require([\"d3\"], function(d3) {\n",
    "        console.log(\"in require\");\n",
    "        console.log(d3.version)\n",
    "        console.log(d3)\n",
    "        var bogoSVG = d3.select(\"#$bogoanimation\") \n",
    "          .append(\"svg\")\n",
    "          .attr(\"width\", 300)\n",
    "          .attr(\"height\", 300);    \n",
    "\n",
    "        var data = $python_data ;\n",
    "        bogoSVG.append(\"circle\")\n",
    "          .style(\"stroke\", \"gray\")\n",
    "          .style(\"fill\", \"cyan\")\n",
    "          .attr(\"r\", data[0]['r'])\n",
    "          .attr(\"cx\", data[0]['cx'])\n",
    "          .attr(\"cy\", data[0]['cy'])\n",
    "          .transition()\n",
    "             .delay(100)\n",
    "             .duration(20000)  \n",
    "             .attr(\"r\", 10)\n",
    "             .attr(\"cx\", data[0]['cx'])\n",
    "             .style(\"fill\", \"blue\"); \n",
    "            \n",
    "       });\n",
    "       \n",
    "''')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At this point, we use the substitute command to fill in the various data into the open variables in the templates. Then we call display(HTML(...)) as in the first example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<style> \n",
       " </style>\n",
       "<div id=\"animation\"></div>\n",
       "<script> \n",
       "    require.config({paths: {d3: \"https://d3js.org/d3.v5.min\"}});\n",
       "    require([\"d3\"], function(d3) {\n",
       "        console.log(\"in require\");\n",
       "        console.log(d3.version)\n",
       "        console.log(d3)\n",
       "        var bogoSVG = d3.select(\"#animation\") \n",
       "          .append(\"svg\")\n",
       "          .attr(\"width\", 300)\n",
       "          .attr(\"height\", 300);    \n",
       "\n",
       "        var data = [{\"r\": 130, \"cx\": 150, \"cy\": 150}] ;\n",
       "        bogoSVG.append(\"circle\")\n",
       "          .style(\"stroke\", \"gray\")\n",
       "          .style(\"fill\", \"cyan\")\n",
       "          .attr(\"r\", data[0]['r'])\n",
       "          .attr(\"cx\", data[0]['cx'])\n",
       "          .attr(\"cy\", data[0]['cy'])\n",
       "          .transition()\n",
       "             .delay(100)\n",
       "             .duration(20000)  \n",
       "             .attr(\"r\", 10)\n",
       "             .attr(\"cx\", data[0]['cx'])\n",
       "             .style(\"fill\", \"blue\"); \n",
       "            \n",
       "       });\n",
       "       \n",
       " </script>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "js_text = js_text_template.substitute({'python_data': json.dumps([{'r': 130, 'cx': 150, 'cy': 150}]),\n",
    "                                       'bogoanimation': 'animation'})\n",
    "\n",
    "\n",
    "display(HTML(html_template.substitute({'css_text': css_text, 'js_text': js_text})))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reload the page\n",
    "to restart the animation. It only runs for 20 seconds."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## And that's it.\n",
    "\n",
    "Some things to look out for:\n",
    "- we need the require and require.config commands to load in the D3 files properly.\n",
    "- it is possible to use the ##javascipt magic command directly. But it does not work with Jupyter Book.\n",
    "- you will need to read the D3 documentation and learn the Javascript programming language to make good use of this tool.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Callysto.ca License](https://github.com/callysto/curriculum-notebooks/blob/master/callysto-notebook-banner-bottom.jpg?raw=true)](https://github.com/callysto/curriculum-notebooks/blob/master/LICENSE.md)"
   ]
  }
 ],
 "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.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}