Quickstart¶

Note

Download this Quickstart as a Jupyter Notebook.

These quick instructions will get you up and running with Datapane in a few minutes!

In this quickstart, we will introduce you to the concept of Blocks, create a simple data report, then make it interactive as part of a simple data app that let's a user create a scatter plot of selected features from the popular Iris dataset.

Installation¶

We're doing this in a Jupyter Notebook, but you could also use another IDE or Python script. Check out our installation page for installation options.

Let's get Datapane installed from within our notebook using pip.

!pip3 install datapane

Setting things up¶

import altair as alt
import datapane as dp
from vega_datasets import data

We've imported datapane, the popular visualization library altair, and vega_datasets which contains some sample datasets.

Let's load the Iris dataset and get a list of the features.

df = data.iris()
columns = list(df.columns)
print(columns)

['sepalLength', 'sepalWidth', 'petalLength', 'petalWidth', 'species']

Blocks¶

Datapane is built around the concept of Blocks, which are Python objects that represent an individual unit that can be processed, composed, and viewed. For instance, there are blocks to represent the concept of a Plot, or a DataTable, and basic layouts like Groups.

Having loaded our DataFrame above and With knowledge of our column names, we can create a scatter plot of two features using the Altair plotting library. We can then build a a simple set of Blocks that display our plot and the dataset in columns.

fig = (
    alt.Chart(df)
    .mark_point()
    .encode(x=alt.X("sepalLength", scale=alt.Scale(zero=False)), 
            y=alt.X("sepalWidth", scale=alt.Scale(zero=False)),
            color="species")
)

view = dp.Select(dp.Plot(fig, label="Plot"), dp.DataTable(df, label="Data"))
view

Reports¶

Our programmatically generated Data View can be converted into a Report, which can be saved to a HTML file, uploaded to Datapane Cloud and more.

Let's save it as a report and open it in a new window.

dp.save_report(view, "quickstart_report.html", open=True)

App saved to ./quickstart_report.html

Apps¶

Our blocks above that make up our report are static, however what if they could be made dynamic, in response to for instance, user input, or a schedule.

Datapane Apps allow you to attach Python functions to your blocks and pass data into them to dynamic process and return new blocks live.

Functions¶

Having loaded our DataFrame above and With knowledge of our column names, let's build and preview a function to create a scatter plot of two features from the dataset.

def plot_df(x_axis: str, y_axis: str, color: str) -> dp.Plot:
    # global dataset
    fig = (
        alt.Chart(df)
        .mark_point()
        .encode(
            x=alt.X(x_axis, scale=alt.Scale(zero=False)),
            y=alt.X(y_axis, scale=alt.Scale(zero=False)),
            color=color,
            tooltip=columns,
        )
    )

    return dp.Plot(fig, name="plot")

plot_df(x_axis="sepalLength", y_axis="sepalWidth", color="species")

Looking good. Let's highlight the minor differences between a regular Python function, and a function that is ready for Datapane interactivity.

The parameters are those that we would expect from the user submitted controls, their names match up with the name parameters of the Controls that we'll create just below.
We're returning a dp.Plot block, which supports visualizations from many popular libraries, such as altair, matplotlib, plotly, bokeh, and PlotAPI.

Datapane blocks have full notebook support, meaning they can be displayed in notebooks as seen above. This makes it easy to interactively develop your function, and call it from your notebook with test parameters before wiring it into your Datapane App.

Controls¶

Let's add some controls that let the user select which features to plot. Our feature list from earlier, columns, will be useful here with the the Choice parameter that allows the user the select an item from the list.

controls = dp.Controls(
    x_axis=dp.Choice(options=columns),
    y_axis=dp.Choice(options=columns),
    color=dp.Choice(options=columns),
)

The name of each dp.Choice is used as the parameter name when calling our function.

Bringing it Together¶

We have our function, and our controls, now let's bring them together to create a data app with a Form Block.

view = dp.View(
    dp.Text("# Iris Dataset Plotter"),
    dp.Form(plot_df, controls=controls),
)

Let's walk through the code, as earlier we are creating a list of Blocks but this time we have a new Block called Form - this is a Compute Block that allows us to call a function from the UI.

It takes the function we created earlier, plot_df, and the controls we created, controls. When the user submits the form, the function is run with the parameters and, by default, the blocks returned as the output of our function are rendered below the Form in the UI.

We can even view the design of our data app in this notebook (but the functions won't work until we publish it.)

view

Launching the App¶

There are many ways to publish a Datapane app, but for now, we can use the dp.serve_app function to see it in action locally.

dp.serve_app(view)

That's it! You've learnt about Blocks, Views, Reports, Apps, and even built and served your first data app with Datapane.

We could have done a lot more with this app, but we wanted to keep it simple. Here are some easy improvements we could make:

Add descriptions and labels to the controls,
Set the default values for the controls,
Present a plot by default, rather than waiting for the user to select features.
Set publish=True to get a public URL for your app.
Share the app publically using our third-party deployment methods.
Upload the app to the Datapane Cloud to share with your team.