Launchers let you turn your analyses into self-service web forms that less technical colleagues can interact with. They are great for creating templatized reports and analyses, so stakeholders can answer questions without bothering data scientists.

You can build a Launcher to let consumers of your project upload data and specify parameters that are neatly consumed by your code to produce consumer-visible results. For example, you could give your users something like this:

try

That would produce for them something like this:

scatter

Basics

A Launcher is essentially a web form on top of any script you could run in Domino. Any arguments your script or executable expects can be exposed as UI elements in the web form.

The command

When you create a Launcher, you specify a command that runs under the hood. This command serves as a template: when an end-user runs the Launcher through the web form, parameters in your command template will be replaced with the user’s input values, and the resulting command will run.

Outputs

When your code runs, it runs just like anything else in Domino. Namely, Domino will detect new files your code produces and treat those as the results. Whoever runs your Launcher will get a link to those results to view on the web, and they’ll get an email when the results are ready. Your code can produce rich images, even interactive HTML dashboards, dynamically based on a user’s input.

Parameters

Like any other script you run through Domino, your command can take parameters/arguments. Anything in your command of the form ${param_name} will be treated as a parameter in the Launcher.

changeparameters

Your parameters can be of the following types:

Text: normal text field
Select: drop down where you can select one value from a list
File: button to select and upload files
Multiselect: list where you can select multiple values

launchertypeoptions

An end user would see those parameters rendered like this in the final web form:

4parameters

Note

Write your code to process parameter values

When a user runs your Launcher through the web form, the user’s input values will be passed into your command in place of the corresponding placeholders you specified, and that final command will be run as though it were a command-line executable. That means your underlying code can access parameters using any standard method for reading command-line inputs. The most common techniques would be:

Argument handling

For R, use the commandArgs function.
For Python, use sys.argv.

args <- commandArgs(trailingOnly=TRUE)
p1 <- args[1]
p2 <- args[2]

# a file upload parameter
print(readLines(args[3], n = 1))

# a multi-select parameter
for (each in strsplit(args[4],",")) {
  cat(each, sep="\n")
}

Note

Full examples in R and Python

R

Our simple R example lets users input two numbers, and behind the scenes, we run some R code that adds them and prints the sum. Our script is in a file called launcher.R, and we could tell Domino to run launcher.R 10 20, so our Launcher’s command will be launcher.R ${A} ${B}.

args <- commandArgs(trailingOnly = TRUE)
a <- as.integer(args[1])
b <- as.integer(args[2])
if (is.na(a)) {
  print("A is not a number")
} else if (is.na(b)){
  print("B is not a number")
} else {
  paste("The sum of", a, "and", b, "is:", a+b)
}

The example Launcher is set up to take A and B as parameters.

editsumlauncher

When operational, the user will see:

editsumlauncher

Python

This Python example uses a script that creates an interactive scatter plot, using Bokeh, from a CSV file that anyone can upload using a web form. The user provides (a) a file (b) what to put on the X- and Y- axes and (c) some information how to color the data points. The Python script generates an interactive Bokeh scatterplot.

This is the complete code of the Python script itself.

from bokeh.plotting import show, output_file
from bokeh.charts import Scatter
import pandas as pd
import sys

output_file("scatter.html")

data = pd.read_csv(sys.argv[1])
scatter = Scatter(data, x = sys.argv[2], y = sys.argv[3], color = sys.argv[4], legend = "top_left")
show(scatter)

Build the Launcher

The Launcher itself needs 4 parameters.

changeparameters

Their exact names aren’t important for the script. The parameter names are human-readable guidance for the users of the Launcher. The order of the parameters is directly linked to the script. Rename them to File, X, Y, Color.

After renaming the parameters, you should change their types. In the overview of the parameters, click File and use the dropdown next to Type to select Upload File. X, Y and Color can remain type Text.

Make sure to put in a clear name for the Launcher. Your result should look something like this:

newlauncher

Use the Launcher

Click Launchers from the project menu then click Run.

createdlauncher

As a sample dataset, use scanvote.csv containing the percentage of a population voting “Yes” per district in Finland, Sweden and Norway.

With this data I would like to create a scatter plot with population (Pop) as X, “Yes” vote percentage as Y (Yes), and the points colored based on the country (Country)

Putting this in the launcher form will give the picture below. Click Run and wait for the result.

try

Launchers Overview