Merge pull request #34 from jasongrout/update-jupyter

Update Interactive Widgets to Jupyter, revise text

Author: minrk

examples/Interactive Widgets/Using Interact.ipynb

@@ -11,20 +11,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The `interact` function (`IPython.html.widgets.interact`) automatically creates user interface (UI) controls for exploring code and data interactively. It is the easiest way to get started using IPython's widgets."
+    "The `interact` function (`ipywidgets.interact`) automatically creates user interface (UI) controls for exploring code and data interactively. It is the easiest way to get started using IPython's widgets."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "collapsed": false
+    "collapsed": false,
+    "scrolled": true
    },
    "outputs": [],
    "source": [
-    "from __future__ import print_function\n",
-    "from IPython.html.widgets import interact, interactive, fixed\n",
-    "from IPython.html import widgets"
+    "from __future__ import print_function # for python 2\n",
+    "from ipywidgets import interact, interactive, fixed\n",
+    "import ipywidgets as widgets"
    ]
   },
   {
@@ -62,6 +63,17 @@
     "    print(x)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "f(10)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -164,6 +176,17 @@
     "    print(p, q)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "h(5, 10)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -186,27 +209,27 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Notice that a slider is only produced for `p` as the value of `q` is fixed."
+    "Notice that a slider is only produced for `p` since the value of `q` is fixed."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Widget abbreviations"
+    "## Widget creation"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "When you pass an integer valued keyword argument (`x=10`) to `interact`, it generates an integer valued slider control with a range of $[-10,+3\\times10]$. In this case `10` is an *abbreviation* for an actual slider widget:\n",
+    "The `interact` function tries to guess which type of control you want based on the value you pass in to the `interact` function.  When you pass an integer argument to `interact`, such as `interact(f, x=10)`, an integer-valued slider control is generated centered at the value:\n",
     "\n",
     "```python\n",
-    "IntSliderWidget(min=-10,max=30,step=1,value=10)\n",
+    "widgets.IntSlider(min=-10,max=30,step=1,value=10)\n",
     "```\n",
     "\n",
-    "In fact, we can get the same result if we pass this `IntSliderWidget` as the keyword argument for `x`:"
+    "We can also directly create the widget when calling `interact`, rather than having `interact` guess:"
    ]
   },
   {
@@ -224,19 +247,18 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This examples clarifies how `interact` proceses its keyword arguments:\n",
+    "This examples clarifies how `interact` processes its keyword arguments:\n",
     "\n",
-    "1. If the keyword argument is `Widget` instance with a `value` attribute, that widget is used. Any widget with a `value` attribute can be used, even custom ones.\n",
-    "2. Otherwise, the value is treated as a *widget abbreviation* that is converted to a widget before it is used.\n",
+    "1. If the keyword argument is a `Widget` instance with a `value` attribute, the widget is used. Any widget with a `value` attribute can be used, even custom ones.\n",
+    "2. Otherwise, the value is used to guess a correct a widget, which is used.\n",
     "\n",
-    "The following table gives an overview of different widget abbreviations:\n",
+    "The following table gives an overview of `interact` translates arguments into widgets:\n",
     "\n",
     "<table class=\"table table-condensed table-bordered\">\n",
     "  <tr><td><strong>Keyword argument</strong></td><td><strong>Widget</strong></td></tr>  \n",
     "  <tr><td>`True` or `False`</td><td>Checkbox</td></tr>  \n",
-    "  <tr><td>`'Hi there'`</td><td>Textarea</td></tr>\n",
-    "  <tr><td>`value` or `(min,max)` or `(min,max,step)` if integers are passed</td><td>IntSlider</td></tr>\n",
-    "  <tr><td>`value` or `(min,max)` or `(min,max,step)` if floats are passed</td><td>FloatSlider</td></tr>\n",
+    "  <tr><td>string `'Hi there'`</td><td>Textarea</td></tr>\n",
+    "  <tr><td>numeric `value` or `(min,max)` or `(min,max,step)`</td><td>IntSlider or FloatSlider</td></tr>\n",
     "  <tr><td>`('orange','apple')` or `{'one':1,'two':2}`</td><td>Dropdown</td></tr>\n",
     "</table>"
    ]
@@ -247,7 +269,7 @@
    "source": [
     "You have seen how the checkbox and textarea widgets work above. Here, more details about the different abbreviations for sliders and dropdowns are given.\n",
     "\n",
-    "If a 2-tuple of integers is passed `(min,max)` a integer valued slider is produced with those minimum and maximum (inclusive) values. In this case, the default step size of `1` is used."
+    "If a 2-tuple of integers is passed, `(min,max)`, a integer-valued slider is produced with those minimum and maximum (inclusive) values. In this case, the default step size of `1` is used."
    ]
   },
   {
@@ -265,7 +287,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If a 3-tuple of integers is passed `(min,max,step)` the step size can also be set."
+    "If a 3-tuple of integers is passed `(min,max,step)`, the step size is set."
    ]
   },
   {
@@ -283,7 +305,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A float valued slider is produced if the elements of the tuples are floats. Here the minimum is `0.0`, the maximum is `10.0` and step size is `0.1` (the default)."
+    "A float-valued slider is produced if the elements of the tuples are floats. Here the minimum is `0.0`, the maximum is `10.0` and step size is `0.1` (the default)."
    ]
   },
   {
@@ -301,7 +323,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The step size can be changed by passing a 3rd element in the tuple."
+    "The step size can be changed by passing a 3-element tuple.  The length of the slider may necessitate skipping some steps if there are two many to fit."
    ]
   },
   {
@@ -319,7 +341,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For both integer and float valued sliders, you can pick the initial value of the widget by passing a default keyword argument to the underlying Python function. Here we set the initial value of a float slider to `5.5`."
+    "For both integer and float-valued sliders, the initial value is the default value of the function parameter, if it exists. Here we set the initial value of a float slider to `5.5`."
    ]
   },
   {
@@ -339,7 +361,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Dropdown menus can be produced by passing a tuple of strings. In this case, the strings are both used as the names in the dropdown menu UI and passed to the underlying Python function."
+    "Dropdown menus can be produced by passing a tuple of strings. In this case, the strings are  used both as the names in the dropdown menu UI and passed to the underlying Python function."
    ]
   },
   {
@@ -368,42 +390,29 @@
    },
    "outputs": [],
    "source": [
-    "interact(f, x={'one': 10, 'two': 20});"
+    "from collections import OrderedDict\n",
+    "interact(f, x={'a': 10, 'b': 20});"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Using function annotations with `interact`"
+    "## `interactive`"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you are using Python 3, you can also specify widget abbreviations using [function annotations](https://docs.python.org/3/tutorial/controlflow.html#function-annotations). This is a convenient approach allows the widget abbreviations to be defined with a function.\n",
-    "\n",
-    "Define a function with an checkbox widget abbreviation for the argument `x`."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "collapsed": false
-   },
-   "outputs": [],
-   "source": [
-    "def f(x:True):\n",
-    "    print(x)"
+    "In addition to `interact`, IPython provides another function, `interactive`, that is useful when you want to reuse the widgets that are produced or access the data that is bound to the UI controls."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Then, because the widget abbreviation has already been defined, you can call `interact` with a single argument."
+    "Here is a function that returns the sum of its two arguments."
    ]
   },
   {
@@ -414,28 +423,8 @@
    },
    "outputs": [],
    "source": [
-    "interact(f);"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## `interactive`"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "In addition to `interact` IPython provides another function, `interactive`, that is useful when you want to reuse the widget that are produced or access the data that is bound to the UI controls."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Here is a function that returns the sum of its two arguments."
+    "def f(a, b):\n",
+    "    return a+b"
    ]
   },
   {
@@ -446,8 +435,7 @@
    },
    "outputs": [],
    "source": [
-    "def f(a, b):\n",
-    "    return a+b"
+    "f(1,2)"
    ]
   },
   {
@@ -527,7 +515,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "At this point, the UI controls work just like they would if `interact` had been used. You can manipulate them interactively and the function will be called. However, the widget instance returned by `interactive` also give you access to the current keyword arguments and return value of the underlying Python function.\n",
+    "At this point, the UI controls work just like they would if `interact` had been used. You can manipulate them interactively and the function will be called. However, the widget instance returned by `interactive` also gives you access to the current keyword arguments and return value of the underlying Python function.\n",
     "\n",
     "Here are the current keyword arguments. If you rerun this cell after manipulating the sliders, the values will have changed."
    ]
@@ -560,13 +548,22 @@
    "source": [
     "w.result"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (conda:strata)",
    "language": "python",
-   "name": "python3"
+   "name": "strata"
   },
   "language_info": {
    "codemirror_mode": {
@@ -578,7 +575,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.4.3"
+   "version": "3.5.0"
   }
  },
  "nbformat": 4,