Variables and expressions

Some experimental conditions (strain, virus species etc.) may vary across individual subjects, individual sessions, runs or sweeps.

To easily express some context-dependence within experiments, you can use variables and expressions in place of concrete objects.

Use of variables

A variable is a placeholder for an object that is defined on-site during an experiment.

For example, the following object describes a variable that can take either pairing or testing as its value.

{
    "$variable": {
        "type":  { "enum": "pairing", "testing" }
    },
    "description": "the mode of the task."
}

Another example below describes an array of values taking any number above zero:

{
    "$variable": {
        "type":  "array",
        "items": {
            "type":    "number",
            "minimum": 0
        }
    },
    "description": "array of time points when the participant started examining the place."
}

class variable

A variable object can be identified by the existence of the $variable property.

For an example, refer to Use of variables.

$variable

holds a valid schema based on JSON Schema, but it may typically be a schema for a string or a number.

description

a required human-readable description about what this variable stands for.

Use of conditions

Conditions provide a way to switch the object depending on the value of a certain variable, just like the switch statement in C, C++ and related languages.

{
    "$condition": { "$ref": "/variable/task-mode" },
    "switch": [
        {
            "case":  "pairing",
            "value": 2
        },
        {
            "case":  "testing",
            "value": 1
        }
    ],
    "default": 0,
    "description": "the task mode-dependent output value returned from Arduino."
}

In the above example, depending on the string variable being held at /variable/task-mode, the expression evaluates to a different value.

It evaluates to 2 if the task mode is pairing, 1 if the mode is testing, and 0 otherwise.

class condition

the existence of the $condition property indicates that this is a condition object.

For an example, refer to Use of conditions.

$condition

holds a reference to the variable.

description

a required human-readable description about what this variable stands for.

switch

a required array of case-expression objects.

default

an optional property holding the “default” value, when nothing in switch applies.

Caution

Make sure that you covered all the possible cases in switch, or that you set the default. Otherwise the expression is evaluated to null, and may cause an undefined behavior.

Expressions and formatters

Expressions and formatters provide a simple way of calculations based on variables.

Below is an example of a formatter:

{
    "$expression": "{{ x }}\*2 + 3",
    "where": {
        "x": { "$ref": "/variables/x" }
    },
    "description": "the amplitude depends on the value of x."
}

In the example above, if x evaluates to the number 1, for example, the whole formatter is evaluated to 5.

Another example provides another way of expressing a condition:

{
    "$expression": "{{ x }} == {{ y }}",
    "where": {
        "x": { "$ref": "/variable1" },
        "y": { "$ref": "/variable2" }
    },
    "description": "the condition depends on whether or not x and y are equal."
}

In this case, the whole formatter is evaluated to either true or false, depending on whether the two referenced variables are equal or not.

In practice, you can define the expression elsewhere as a string, and plug the values where you need:

{
    "expressions": {
        "output-calculation": "{{ start }} + {{ step }} * {{ index }}",
        ...
    },

    ...

    "pulse": {
        "amplitude": {
            "$expression": { "$ref": "/expressions/output-calculation" },
            "where": {
                "start": 0,
                "step":  10,
                "index": 2
            }
        }
    }
}

class formatter

The existence of the $expression property indicates that this is a formatter object.

For examples, see Expressions and formatters.

$expression

the expression to be evaluated. Each appearance of variable names must be wrapped inside doubled curly braces.

description

a required human-readable description about what this variable stands for.

where

the assignment specifications for the expression. The variables used within $expression must appear once in this section.

Use of templates

TODO

• $template keyword

  • object representation instead of expression
  • $ref-based reference

• where property

  • used to plug values at the root scope of the template