PlanOut Language Reference

The PlanOut language is a way to concisely define experiments. The language is designed to be simple enough to be understood by those with little programming background. It includes basic logical operators, conditional execution, and data structures.

Overview

The PlanOut language syntax is similar to JavaScript, but with a few exceptions:

  • Variables (parameters) can be assigned by writing a <- b or a = b.
  • Operator (function) arguments can be named
  • Some operators, including random assignment operators, require named arguments. The ordering of these arguments does not matter.
  • #’s are used to write comments
  • null is returned when an invalid array or dictionary key accessed.
  • The && and || logical operators always return boolean values.

PlanOut syntax and operators

The following is a reference of all the PlanOut syntax and built-in operators.

Random assignment operators

All of PlanOut’s random assignment operators are available in the language. The variable name given on the left hand side of an assignment operation is used as the salt, if no salt is specified manually, e.g.,

colors = ['#aa2200', '#22aa00', '#0022aa'];
x = uniformChoice(choices=colors, unit=userid); # 'x' used as salt
y = uniformChoice(choices=colors, unit=userid); # 'y' used as salt, generally != x
z = uniformChoice(choices=colors, unit=userid, salt='x'); # same value as x

Units can be scalars or arrays:

x = uniformChoice(choices=colors, unit=userid);
y = uniformChoice(choices=colors, unit=[userid, url]);

All random assignment operators are available via the PlanOut language:

a = uniformChoice(choices=colors, unit=userid);
b = weightedChoice(choices=colors weights=[0.2, 0.8], unit=userid);
c = bernoulliTrial(p=0.2, unit=userid);
d = randomFloat(min=1.0, max=2.0, unit=userid);
e = randomInteger(min=1, max=10, unit=userid);
f = sample(choices=colors, num_draws = 2);

Arrays

Arrays can include constants and variables, and can be arbitrarily nested, and can contain arbitrary types.

a = [4, 5, 'foo'];
b = [a, 2, 3];      # evaluates to [[1,2,'foo'], 2,3]
x = a[0];           # evaluates to 4
y = b[0][2];        # evaluates to 'foo'
z = b[22];          # evaluates to null

Dictionaries

PlanOut also has limited support for dictionaries, which may be passed in as inputs into PlanOut or expressed in terms of constant JSON literals, denoted by @:

a = @{'foo':1, 'bar': [2,3]};
x = a['bar'][0];               # evaluates to 2
y = a['bogus']                 # evaluates to null

Note that the following code is not supported:

v = 1;
a = @{'foo': v};
b = {'foo': v};

When invalid indexes are accessed, PlanOut returns null.

b = [1,2,3];
n = b[5];                     # evaluates to null
m = b[5][1];                  # evaluates to null

The null-coalescing operator, coalesce() can be used to protect against invalid indexes:

c = coalesce(b[5], 42);       # evaluates to 42
c2 = coalesce(b[5][2], 42);   # evaluates to 42

Logical operators

Logical operators include and (&&), or (||), not (!), as in:

  a = 1; b = 0; c = 1;
  x = a && b;       # evaluates to False
  y = a || b || c;  # evaluates to True
  y = !b;           # evaluates to True

Control flow

Conditional execution can be implemented via if / else if / else.

if (country == 'US') {
  p = 0.2;
} else if (country == 'UK') {
  p = 0.4;
} else {
  p = 0.1;
}

Arithmetic

PlanOut supports basic arithmetic operations.

 a = 2 + 3 + 4;  # 9
 b = 2 * 3 * 4;  # 24
 c = -2;         # -2
 d = 2 + 3 - 4;  # 1
 e = 4 % 2;      # 0
 f = 4 / 2;      # 2.0
 g = round(2.3); # 2

Note that a space is required between - and 4 in the above example.

Other operators

Other built-in operators include min, max, and the null coalescing operator, coalesce.

x = [];
a = min(1, 2, -4);                # -4
b = min(values=[1, 2, -4]);       # -4
c = coalesce(x[42], null, 0, 8);  # 0

These operators can either be written as taking an arbitrary number of unnamed arguments, or as taking a single array argument, called values.

Return

return true;   # short circuits execution
return false;  # short circuits execution, disables logging