{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Using Interact"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"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,
"scrolled": true
},
"outputs": [],
"source": [
"from __future__ import print_function # for python 2\n",
"from ipywidgets import interact, interactive, fixed\n",
"import ipywidgets as widgets"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"The widgets in this notebook won't show up on http://nbviewer.ipython.org. To view the widgets and interact with them, you will need to download this notebook and run it with an IPython Notebook server.\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Basic `interact`"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"At the most basic level, `interact` autogenerates UI controls for function arguments, and then calls the function with those arguments when you manipulate the controls interactively. To use `interact`, you need to define a function that you want to explore. Here is a function that prints its only argument `x`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"def f(x):\n",
" print(x)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"f(10)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When you pass this function as the first argument to `interact` along with an integer keyword argument (`x=10`), a slider is generated and bound to the function."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x=10);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When you move the slider, the function is called and the current value of `x` is printed.\n",
"\n",
"If you pass `True` or `False`, `interact` will generate a checkbox:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x=True);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If you pass a string, `interact` will generate a text area."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x='Hi there!');"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"`interact` can also be used as a decorator. This allows you to define a function and interact with it in a single shot. As this example shows, `interact` also works with functions that have multiple arguments."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"@interact(x=True, y=1.0)\n",
"def g(x, y):\n",
" print(x, y)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Fixing arguments using `fixed`"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"There are times when you may want to explore a function using `interact`, but fix one or more of its arguments to specific values. This can be accomplished by wrapping values with the `fixed` function."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"def h(p, q):\n",
" print(p, q)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"h(5, 10)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When we call `interact`, we pass `fixed(20)` for q to hold it fixed at a value of `20`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(h, p=5, q=fixed(20));"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Notice that a slider is only produced for `p` since the value of `q` is fixed."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Widget creation"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"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",
"widgets.IntSlider(min=-10,max=30,step=1,value=10)\n",
"```\n",
"\n",
"We can also directly create the widget when calling `interact`, rather than having `interact` guess:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x=widgets.IntSlider(min=-10,max=30,step=1,value=10));"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This examples clarifies how `interact` processes its keyword arguments:\n",
"\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 `interact` translates arguments into widgets:\n",
"\n",
"\n",
" | Keyword argument | Widget |
\n",
" | `True` or `False` | Checkbox |
\n",
" | string `'Hi there'` | Textarea |
\n",
" | numeric `value` or `(min,max)` or `(min,max,step)` | IntSlider or FloatSlider |
\n",
" | `('orange','apple')` or `{'one':1,'two':2}` | Dropdown |
\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"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."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x=(0,4));"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If a 3-tuple of integers is passed `(min,max,step)`, the step size is set."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x=(0,8,2));"
]
},
{
"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)."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x=(0.0,10.0));"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"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."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x=(0.0,10.0,0.01));"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"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`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"@interact(x=(0.0,20.0,0.5))\n",
"def h(x=5.5):\n",
" print(x)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"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."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"interact(f, x=('apples','oranges'));"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If you want a dropdown menu that passes non-string values to the Python function, you can pass a dictionary. The keys in the dictionary are used for the names in the dropdown menu UI and the values are the arguments that are passed to the underlying Python function."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from collections import OrderedDict\n",
"interact(f, x={'a': 10, 'b': 20});"
]
},
{
"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 widgets 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."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"def f(a, b):\n",
" return a+b"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"f(1,2)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Unlike `interact`, `interactive` returns a `Widget` instance rather than immediately displaying the widget."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"w = interactive(f, a=10, b=20)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The widget is a `Box`, which is a container for other widgets."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"type(w)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The children of the `Box` are two integer valued sliders produced by the widget abbreviations above."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"w.children"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To actually display the widgets, you can use IPython's `display` function."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"from IPython.display import display\n",
"display(w)"
]
},
{
"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 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."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"w.kwargs"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here is the current return value of the function."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"w.result"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": []
}
],
"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.5.1"
},
"widgets": {
"state": {},
"version": "1.1.2"
}
},
"nbformat": 4,
"nbformat_minor": 0
}