Launchers overview





About Launchers

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:

image0

That would produce for them something like this:

image1




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 parmeter in the Launcher.

image2

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

image3

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

image4


Writing your code to process parameter values

When an end-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 parmeters using any standard method for reading command-line inputs. The most common techniques would be:


Python argument handling

Use sys.argv.

import sys
p1 = sys.argv[1]
p2 = sys.argv[2]
# a file upload parameter
with open(sys.argv[3], 'r') as f:
   print f.readline()

# a multi-select parameter
for part in sys.argv[4].split(","):
 print part

R argument handling

Use the commandArgs function.

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 that file parmeters will be passed into your file as the path to the file. Multi-select parameters will be passed in as the comma-separated list of all selected choices.




Full examples in R and Python

R example

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.

image5

When operational, the user will see:

image6


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.


Writing the script

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)

Building the Launcher

The Launcher itself needs 4 parameters.

image7

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:

image8


Using the Launcher

Click Launchers from the project menu then click Run.

image9

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,

image10