Parameters and Forms

Search…
Apps can be parameterised, allowing them to dynamically generate reports through web forms or the API.
Overview
Stakeholders commonly need to provide some configuration to your apps to enable self-service report generation. Datapane allows you to add parameters, which are presented to end users as web forms. This means that other people who have accounts on your instance can generate reports without worrying about code, notebooks, or setting up a Python environment. 
Running & Parameters
Input parameters can be defined in your datapane.yaml configuration file, where you can enter a schema and configure the inputs. In your Python code, the parameters which you define in this file are accessible in the Params dictionary. You can get an item from the dictionary with Params.get([value_name], [default_value])
Following the previous example, the dataset we are pulling includes a few other useful parameters which people may want to graph. Let's add the ability for the end-user to choose from new_cases_smoothed_per_million , new_deaths_smoothed_per_million, median_age, and gdp_per_capita . Additionally, let's allow them to choose a subset of continents for the graph.
Based on this, we are going to add two parameters: plot_field and continents to the parameters section of our datapane.yaml. To configure what the end-user's form looks like, we can choose the type of widget. For the above, we're choosing a enum (which provides a dropdown select menu where the user must select one option), and a list (which allows the user to choose or more choices from a predefined list). We can also set the default parameters for each input and a description.
Full details of parameter configuration and available fields are provided in the API reference.
datapane.yaml
1
name: covid_script
2
script: simple_script.py # this could also be ipynb if it was a notebook
3
  
4
parameters:
5
  - name: field_to_plot
6
    description: Field to plot
7
    type: enum
8
    choices: 
9
      - new_cases_smoothed_per_million
10
      - new_deaths_smoothed_per_million
11
      - median_age
12
      - gdp_per_capita
13
  - name: continents
14
    description: Field to plot
15
    type: list
16
    choices:
17
      - Africa
18
      - Asia
19
      - Europe
20
      - Oceania
21
      - North America
22
      - South America
23
    default: 
24
      - Asia
25
      - North America
Copied!
You can then use the Params object as you would when running on your Datapane instance, and we can customise our data and graph based on those inputs.
simple_script.py
1
import pandas as pd
2
import altair as alt
3
import datapane as dp
4
​
5
dataset = pd.read_csv('https://covid.ourworldindata.org/data/owid-covid-data.csv')
6
​
7
# Get input parameters
8
continents = dp.Params.get('continents', ['Asia', 'North America'])
9
field_to_plot = dp.Params.get('field_to_plot', 'new_cases_smoothed_per_million')
10
​
11
df = dataset[dataset.continent.isin(continents)].groupby(['continent', 'date'])[field_to_plot].mean().reset_index()
12
​
13
plot = alt.Chart(df).mark_area(opacity=0.4, stroke='black').encode(
14
    x='date:T',
15
    y=alt.Y(field_to_plot, stack=None),
16
    color=alt.Color('continent:N', scale=alt.Scale(scheme='set1')),
17
    tooltip='continent:N'
18
).interactive().properties(width='container')
19
​
20
dp.Report(
21
    dp.Plot(plot), 
22
    dp.Table(df)
23
).publish(name='covid_report', open=True)
Copied!
When we run app deploy, Datapane will deploy a new version of our app, and use our parameters definition to generate the following form:
Stakeholders can enter parameters and generate custom reports themselves, based on these fields.  
​
Datapane Teams - Previous
Apps
Configuration
Last modified 7mo ago
Copy link
Contents
Overview
Running & Parameters