This is the 3rd chapter of the Dash Tutorial.
The previous chapter covered the Dash app <code>layout<code>
and the next chapter covers interactive graphing.
Just getting started? Make sure to install the necessary dependencies.
In the previous chapter we learned that the app.layout
describes what the app
looks like and is a hierarchical tree of components.
The dash_html_components
library provides classes for all of the HTML
tags, and the keyword arguments describe the HTML attributes like
style
, className
, and id
. The dash_core_components
library
generates higher-level components like controls and graphs.
This chapter describes how to make your
Dash apps using callback functions: Python functions that are automatically called by Dash whenever an input component’s property changes.
For optimum user-interaction and chart loading performance, production
Dash applications should consider the Job Queue,
HPC, Datashader,
and horizontal scaling capabilities of
Dash Enterprise.
Let’s get started with a simple example of an interactive Dash app.
If you’re using Dash Enterprise’s Data Science Workspaces,
copy & paste the below code into your Workspace (see video).
Find out if your company is using Dash Enterprise
import dash
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
app.layout = html.Div([
html.H6("Change the value in the text box to see callbacks in action!"),
html.Div(["Input: ",
dcc.Input(id='my-input', value='initial value', type='text')]),
html.Br(),
html.Div(id='my-output'),
])
@app.callback(
Output(component_id='my-output', component_property='children'),
Input(component_id='my-input', component_property='value')
)
def update_output_div(input_value):
return 'Output: {}'.format(input_value)
if __name__ == '__main__':
app.run_server(debug=True)
Let’s break down this example:
@app.callback
decorator.a. By writing this decorator, we’re telling Dash to call this function for us whenever the value of the “input” component (the text box) changes in order to update the children of the “output” component on the page (the HTML div).
b. You can use any name for the function that is wrapped by the @app.callback
decorator. The convention is that the name describes the callback output(s).
c. You can use any name for the function arguments, but you must use the same names inside the callback function as you do in its definition, just like in a regular Python function. The arguments are positional: first the Input
items and then any State
items are given in the same order as in the decorator.
d. You must use the same id
you gave a Dash component in the app.layout
when referring to it as either an input or output of the @app.callback
decorator.
e. The @app.callback
decorator needs to be directly above the callback function declaration. If there is a blank line between the decorator and the function definition, the callback registration will not be successful.
f. If you’re curious about what the decorator syntax means under the hood, you can read this StackOverflow answer and learn more about decorators by reading PEP 318 – Decorators for Functions and Methods.
value
” property of the component that has the IDmy-input
”. Our output is the “children
” property of themy-output
”.component_id
and component_property
keywords are optionaldash.dependencies.Input
object and thedash_core_components.Input
object. The former is just used in thesechildren
property of themy-output
component in the layout
. When the Dash app starts, ithtml.Div(id='my-output', children='Hello world')
, it would getIt’s sort of like programming with Microsoft Excel:
whenever an input cell changes, all of the cells that depend on that cell
will get updated automatically. This is called “Reactive Programming”.
Remember how every component was described entirely through its set of
keyword arguments? Those properties are important now.
With Dash interactivity, we can dynamically update any of those properties
through a callback function. Frequently we’ll update the children
of a
component to display new text or the figure
of a dcc.Graph
component
to display new data, but we could also update the style
of a component or
even the available options
of a dcc.Dropdown
component!
Let’s take a look at another example where a dcc.Slider
updates a
dcc.Graph
.
In this example, the "value"
property of the Slider
is the input of the
app and the output of the app is the "figure"
property of the Graph
.
Whenever the value
of the Slider
changes, Dash calls the callback
function update_figure
with the new value. The function filters the
dataframe with this new value, constructs a figure
object,
and returns it to the Dash application.
There are a few nice patterns in this example:
df = pd.read_csv('...')
.df
is in the global state of the app and can bedf
)layout.transition
to give an ideaIn Dash, any “Output
” can have multiple “Input
” components.
Here’s a simple example that binds five Inputs
(the value
property of 2 Dropdown
components,
2 RadioItems
components, and 1 Slider
component)
to 1 Output component (the figure
property of the Graph
component).
Notice how the app.callback
lists all five dash.dependencies.Input
inside a list in the second argument.
In this example, the update_graph
function gets called whenever the
value
property of the Dropdown
, Slider
, or RadioItems
components
change.
The input arguments of the update_graph
function are the new or current
value of each of the Input
properties, in the order that they were
specified.
Even though only a single Input
changes at a time (a user can only change
the value of a single Dropdown in a given moment), Dash collects the
current state of all of the specified Input
properties and passes them
into your function for you. Your callback functions are always guaranteed
to be passed the representative state of the app.
Let’s extend our example to include multiple outputs.
So far all the callbacks we’ve written only update a
single Output
property. We can also update several at once: put all the
properties you want to update as a list in the decorator, and return that
many items from the callback. This is particularly nice if two outputs
depend on the same computationally intense intermediate result, such as a
slow database query.
import dash
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
app.layout = html.Div([
dcc.Input(
id='num-multi',
type='number',
value=5
),
html.Table([
html.Tr([html.Td(['x', html.Sup(2)]), html.Td(id='square')]),
html.Tr([html.Td(['x', html.Sup(3)]), html.Td(id='cube')]),
html.Tr([html.Td([2, html.Sup('x')]), html.Td(id='twos')]),
html.Tr([html.Td([3, html.Sup('x')]), html.Td(id='threes')]),
html.Tr([html.Td(['x', html.Sup('x')]), html.Td(id='x^x')]),
]),
])
@app.callback(
Output('square', 'children'),
Output('cube', 'children'),
Output('twos', 'children'),
Output('threes', 'children'),
Output('x^x', 'children'),
Input('num-multi', 'value'))
def callback_a(x):
return x**2, x**3, 2**x, 3**x, x**x
if __name__ == '__main__':
app.run_server(debug=True)
x 2 | |
x 3 | |
2 x | |
3 x | |
x x |
A word of caution: it’s not always a good idea to combine Outputs, even if
you can:
You can also chain outputs and inputs together: the output of one callback
function could be the input of another callback function.
This pattern can be used to create dynamic UIs where one input component
updates the available options of the next input component.
Here’s a simple example.
# -*- coding: utf-8 -*-
import dash
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
all_options = {
'America': ['New York City', 'San Francisco', 'Cincinnati'],
'Canada': [u'Montréal', 'Toronto', 'Ottawa']
}
app.layout = html.Div([
dcc.RadioItems(
id='countries-radio',
options=[{'label': k, 'value': k} for k in all_options.keys()],
value='America'
),
html.Hr(),
dcc.RadioItems(id='cities-radio'),
html.Hr(),
html.Div(id='display-selected-values')
])
@app.callback(
Output('cities-radio', 'options'),
Input('countries-radio', 'value'))
def set_cities_options(selected_country):
return [{'label': i, 'value': i} for i in all_options[selected_country]]
@app.callback(
Output('cities-radio', 'value'),
Input('cities-radio', 'options'))
def set_cities_value(available_options):
return available_options[0]['value']
@app.callback(
Output('display-selected-values', 'children'),
Input('countries-radio', 'value'),
Input('cities-radio', 'value'))
def set_display_children(selected_country, selected_city):
return u'{} is a city in {}'.format(
selected_city, selected_country,
)
if __name__ == '__main__':
app.run_server(debug=True)
The first callback updates the available options in the second RadioItems
component based off of the selected value in the first RadioItems
component.
The second callback sets an initial value when the options
property
changes: it sets it to the first value in that options
array.
The final callback displays the selected value
of each component.
If you change the value
of the countries RadioItems
component, Dash
will wait until the value
of the cities component is updated
before calling the final callback. This prevents your callbacks from being
called with inconsistent state like with "America"
and "Montréal"
.
In some cases, you might have a “form”-type pattern in your
application. In such a situation, you might want to read the value
of the input component, but only when the user is finished
entering all of his or her information in the form.
Attaching a callback to the input values directly can look like
this:
# -*- coding: utf-8 -*-
import dash
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output
external_stylesheets = ["https://codepen.io/chriddyp/pen/bWLwgP.css"]
app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
app.layout = html.Div(
[
dcc.Input(id="input-1", type="text", value="Montréal"),
dcc.Input(id="input-2", type="text", value="Canada"),
html.Div(id="number-output"),
]
)
@app.callback(
Output("number-output", "children"),
Input("input-1", "value"),
Input("input-2", "value"),
)
def update_output(input1, input2):
return u'Input 1 is "{}" and Input 2 is "{}"'.format(input1, input2)
if __name__ == "__main__":
app.run_server(debug=True)
In this example, the callback function is fired whenever any of the
attributes described by the dash.dependencies.Input
change.
Try it for yourself by entering data in the inputs above.
dash.dependencies.State
allows you to pass along extra values without
firing the callbacks. Here’s the same example as above but with the
dcc.Input
as dash.dependencies.State
and a button as
dash.dependencies.Input
.
# -*- coding: utf-8 -*-
import dash
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output, State
external_stylesheets = ['https://codepen.io/chriddyp/pen/bWLwgP.css']
app = dash.Dash(__name__, external_stylesheets=external_stylesheets)
app.layout = html.Div([
dcc.Input(id='input-1-state', type='text', value='Montréal'),
dcc.Input(id='input-2-state', type='text', value='Canada'),
html.Button(id='submit-button-state', n_clicks=0, children='Submit'),
html.Div(id='output-state')
])
@app.callback(Output('output-state', 'children'),
Input('submit-button-state', 'n_clicks'),
State('input-1-state', 'value'),
State('input-2-state', 'value'))
def update_output(n_clicks, input1, input2):
return u'''
The Button has been pressed {} times,
Input 1 is "{}",
and Input 2 is "{}"
'''.format(n_clicks, input1, input2)
if __name__ == '__main__':
app.run_server(debug=True)
In this example, changing text in the dcc.Input
boxes won’t fire
the callback but clicking on the button will. The current values of
the dcc.Input
values are still passed into the callback even though
they don’t trigger the callback function itself.
Note that we’re triggering the callback by listening to the
n_clicks
property of the html.Button
component. n_clicks
is a
property that gets incremented every time the component has been
clicked on. It is available in every component in the
dash_html_components
library.
We’ve covered the fundamentals of callbacks in Dash.
Dash apps are built off of a set
of simple but powerful principles: declarative UIs that are customizable
through reactive and functional Python callbacks.
Every element attribute of the declarative components can be updated
through a callback and a subset of the attributes, like the value
properties of the dcc.Dropdown
, are editable by the user in the
interface.
The next part of the Dash tutorial covers interactive graphing.