Skip to content

Input specification

Inputs to BIDS apps may be specified as JSON objects that map input ids to values. The objects found within the required inputs list have the following fields, described fully in https://github.com/boutiques/boutiques/blob/0.5.25/schema/README.md#inputs (source):

List of relevant inputs object properties for the BIDS Application specification

Field name Requirement Level Data type Description
id REQUIRED String The argument ID. Alphanumeric values and underscores only. CamelCase is recommended.
name REQUIRED String Plain text name of input for display. Can contain spaces.
type REQUIRED String One of {"String", "File", "Flag", "Number"}.
command-line-flag OPTIONAL String For non-positional arguments, the flag which is associated with the argument on the command-line.
list OPTIONAL Boolean Indicates whether or not the input field is a list of inputs. One of {true, false}. If omitted, it will be interpreted as false (for example non-list input).
optional OPTIONAL Boolean Indicates whether or not the input field is required. One of {true, false}. If omitted, will be interpreted as false (for example non-optional input).
value-choices OPTIONAL List List of possible values that the parameter may take.
value-key OPTIONAL String String to replace in command-line template string. If specified, this MUST NOT be either a superset or subset of the value-key attribute associated with another object in the descriptor; to ensure this, brackets are typically used (for example "[value]").

List of group object properties and their role within the BIDS Application specification

In addition to describing inputs themselves, groups of inputs and their relationships can be defined as follows:

Field name Requirement Level Data type Description
id REQUIRED String A short, unique, informative identifier containing only alphanumeric characters and underscores.
members REQUIRED List IDs of the input parameters belonging to this group.
name REQUIRED String A human-readable name for the input group.
description RECOMMENDED String Description of the input group.
all-or-none OPTIONAL Boolean True if all parameters included in this group need to be included together. .
mutually-exclusive OPTIONAL Boolean True if only one input in the group may be selected at runtime.
one-is-required OPTIONAL Boolean True if at least one of the inputs in the group must be selected.

Required arguments

BIDS Applications MUST provide the following arguments. Notes that "Argument ID" is what is required to exist as the state "id" in the Boutiques descriptor, and will be validated, while the example CLI Flag provides a possible way this could be expressed in the tool's interface.

List of custom object properties and roles within the BIDS Application specification

Argument ID CLI Flag Requirement Level Data type Description
AnalysisLevel --analysis-level REQUIRED String String with value-choices which are a subset of {run, session, subject, dataset, meta}. The app may support one or more of these analysis levels. A default may be set, and unsupported analysis levels should return an exit code of 17, consistent with the definition in Table 7.
Help --help REQUIRED Flag Flag that specifies whether or not to show the help-text that describes how the tool may be correctly used.
InputDataset --input-dataset REQUIRED List List of URIs/paths of the BIDS datasets to be processed. Whether or not the order of listed datasets is important MUST be specified in the parameter description. The tool MUST NOT reorder the user-specified list.
OutputLocation --output-location REQUIRED List One URI/path to the location where all outputs will be stored.
ToolVersion --version REQUIRED Flag Returns the version of the tool being used.

Backwards compatibility

If an app wishes to maintain backwards compatibility with BIDS-Apps 1.0, then the following command-line should be valid:

    bids-app InputDataset OutputLocation AnalysisLevel [options]

In this case, InputDataset is limited to a list of length one. It is worth noting that all legacy apps can be supported in this spec, they just need to write a descriptor which maps the inputs as they are expected and defined, here, to their associated values in the original application.

Reserved arguments

The ability to filter BIDS entities (for example subject, session, or run) allows for the selection of subsets of datasets. To be extensible as new entities are added to the BIDS specification, the reserved arguments are defined here as a rule which maps to BIDS entities, rather than specifying the moving goalpost of an exhaustive list.

The arguments may be specified as follows:

  • The argument ID SHOULD be in CamelCase, with the form <entity>Label or <entity>Index, depending on whether the associated values are constrained to be alphanumeric or numeric, respectively.

  • The argument MUST accept values referring to labels/indices, as consistent with the above, in either the form of a list or a file containing a line-delimited list. The items provided SHOULD NOT include the entity label in addition to the labels/indices.

While several examples exist within Table 5, to the following demonstrates how the above rules can be applied for the BIDS entity "subject":

ID: SubjectLabel

CLI flag: --subject-label

Acceptable and equivalent usages:

    --subject-label 01 02 03
    --subject-label subject_ids.txt

Contents of subject_ids.txt:

01
02
03

In all cases where such arguments are defined and applied, only files in the BIDS dataset that have a value for the specified entities will be subject to filtering. That is, if a file does not have a given entity (for example entity value for it is <None>), the file will be included.

Applications are not required to support these arguments, but MUST NOT assign these arguments to other meanings. To reduce conflicts, BIDS Applications SHOULD avoid using this convention except for entities that are anticipated to be standardized.

Example of an Interface descriptor: see 4.1.

For example, suppose we have an application with the following descriptor:

example_app.json:

{
    "name": "Example BIDS App",
    "command-line": "bids-app [InputDataset] [OutputLocation] [AnalysisLevel] [ParticipantLabel] [OurRandomSeed]""inputs": [
        {
            "id": "InputDataset",
            "name": "Input datasets",
            "value-key": "[InputDataset]",
            "type": "File",
            "list": true,
            "optional": false,
            "command-line-flag": "--input-datasets"
        },
        {
            "id": "OutputLocation",
            "name": "Output location",
            "value-key": "[OutputLocation]",
            "type": "File",
            "optional": false,
            "command-line-flag": "--output-location"
        },
        {
            "id": "AnalysisLevel",
            "name": "Analysis level",
            "value-key": "[AnalysisLevel]",
            "type": "String",
            "optional": false,
            "value-choices": [
                "run",
                "session",
                "subject",
                "dataset"
            ],
            "default": "session",
            "command-line-flag": "--analysis-level"
        },
        {
            "id": "SubjectLabel",
            "name": "Subject labels",
            "value-key": "[SubjectLabel]",
            "type": "String",
            "list": true,
            "optional": true,
            "command-line-flag": "--subject-label"
        },
        {
            "id": "RandomSeed",
            "name": "Seed for pseudorandom number generator",
            "value-key": "[RandomSeed]",
            "type": "Number",
            "optional": true,
            "command-line-flag": "--random-seed"
        }
    ]
}

input_params.json

{
  "InputDataset": ["/path/to/bids", "/path/to/derivatives"],
  "OutputLocation": "/path/to/output",
  "AnalysisLevel": "subject",
  "SubjectLabel": ["01", "02"],
  "RandomSeed": "0xB1D5CAF3"
}