User Reference:JSON Parameter Format

Synopsis

The BCI2000 JSON parameter format defines how BCI2000 parameters are represented when using JSON related parameter functions in the Programming Reference:BCI2000Remote Class, the Technical Reference:Operator Library, or User Reference:Operator Module Scripting.

Due to the fact that a Python dict object may easily be represented in JSON format, the JSON parameter format is most useful when used with Python.

This allows creating a dict object with the desired parameter properties, and then converting it to JSON representation using the json.dumps() function. Similarly, a JSON string may be converted to a Python dict object using the json.loads() function (see example below).

Properties

The following properties are used when reading a JSON string into a parameter object. Any other properties are ignored. The only mandatory properties are "Name" and "Values". If the parameter is supposed to appear in the Operator module's parameter editor dialog, the "Section" property must be provided as well.

Name

The parameter name, with an optional path, separated by slashes ("/"). The path does not refer to the filesystem but to the internal hierarchy of filters in the BCI2000 system. Typically, you will only provide a name here, or use a path obtained from one of the GetParameterJson() call.

Type

The parameter's type, which may indicate data type, such as string, float, int, and shape, such as list or matrix. Data type is not enforced, and may be omitted for list or matrix parameters.

Sections

An array of strings which describe a hierarchy of sections, with the first one indicating the tab in the Operator module's parameter editor dialog, and the second one indicating the group box inside the tab. Any number of sections may be given but only the first two will be used in the current implementation of BCI2000.

Values

An array of parameter values. For matrix valued parameters, this array is counted first by row index, and then by column index, i.e. neighboring row indices correspond to neighboring indices in the Values array.

When RowLabels and ColumnLabels are given, the size of the Values array must be consistent with the sizes of the RowLabels and ColumnLabels arrays, i.e. the number of Values must equal the product of the numbers of RowLabels and ColumnLabels.

If neither RowLabels nor ColumnLabels are given, ColumnLabels will be set to a single "1" entry, and RowLabels will be set to a list from "1" to the number of entries in the Values array.

Otherwise, reading the parameter from the JSON string will fail.

RowLabels, ColumnLabels

Arrays of row resp. column labels. For single-valued and list parameters, you may omit RowLabels and ColumnLabels as described under Values. For matrix parameters, the shape of the matrix is derived from the number of entries in row and column labels.

If no textual labels are available for rows and columns, specify a string-valued list from "1" to the number of entries in each property (a so-called trivial label).

Comment

An arbitrary text describing the parameter to the user. This is displayed in the Operator module's parameter editor, next to the parameter value.

The Comment property may also contain additional information about a parameter; see Technical Reference:Parameter Definition for details.

DefaultValue

An example value that may be provided to show how a parameter may be used. This is typically omitted.

LowRange, HighRange

Values that represent a numerical parameter's minimum and maximum values. In the context of JSON parameters, these are typically unused and thus omitted.

Example

The following is an example in Python, using the Programming Reference:BCI2000Remote Class.

import json

bci = BCI2000Remote()
print("Operator path: " + bci.OperatorPath)
bci.WindowVisible = True
bci.WindowTitle = "Python controlled"

bci.SubjectID = "pysub"
bci.Connect()

myparam = dict()
myparam["Name"] = 'foo'
myparam["Sections"] = ['blubb', 'blobb']
myparam["Type"] = 'string'
myparam["Values"] = ['bar']
myparam["Comment"] = 'This is a test parameter created from Python.'
bci.AddParameterJson(json.dumps(myparam))

myparam2 = json.loads(bci.GetParameterJson('foo'))
print(myparam2)