Skip to content

Computational Models

Support for the modality comp was developed as a BIDS Extension Proposal.

BIDS Computational Model files store the mathematical and computational descriptions of computational models as well as simulation results. To ensure that computational modelling results are reproducible it is necessary to store for every simulation result the used

  • mathematical model equations (including all state variables and generic parameters),
  • specific parameter settings (for example, for a certain sub, ses, task, ...)
  • structural connectivity
  • source code
  • and machine code.

Therefore, every file that contains computational model simulation results MUST reference these files in a JSON sidecar file.

To store code either the modality agnostic datatype code or publicly accessible long-term repositories can be used. To store models the datatype model MUST be used.

Caveat: To store structural connectivity the datatype connectivity developed in BEP017 is planned to be used. To store simulation results a new datatype for storing time series will be needed. The need for such a BIDS-wide datatype to store time series was identified.

The following filetree exemplifies the directory structure.

└─ comp/
   ├─ model/
   │  ├─ desc-Generic2dOscillator_eq.xml                      generic equations for all subjects
   │  ├─ desc-JansenRit_eq.xml 
   │  ├─ desc-JansenRit-healthy_param.xml                     generic parameters for all subjects
   │  └─ desc-Generic2dOscillator-healthy_param.xml 
   ├─ code/
   │  ├─ desc-Generic2dOscillator-script.py                   generic machine code for all subjects
   │  ├─ desc-JansenRit.img 
   │  └─ desc-JansenRit-Dockerfile.txt                        generic source code for all subjects
   └─ sub-01/
      ├─ model/
      │  ├─ sub-01_desc-JansenRit-stroke_param.xml            subject-specific parameters only for sub-01
      │  └─ sub-01_desc-Generic2dOscillator-stroke_param.xml 
      ├─ code/
      │  └─ sub-01_desc-preproc.py                            subject-specific code only for sub-01
      ├─ timeseries/
      │  ├─ sub-01_desc-testsim.tsv                           Datatype timeseries not yet existing, but needed: <https://github.com/bids-standard/bids-specification/issues/713>
      │  ├─ sub-01_desc-testsim.json                          every simulation result has a JSON sidecar that references the used model, code and connectivity
      │  ├─ sub-01_task-motor.tsv 
      │  ├─ sub-01_task-motor.json 
      │  ├─ sub-01_task-motor_desc-burnin.tsv 
      │  └─ sub-01_task-motor_desc-burnin.json 
      └─ connectivity/
         ├─ sub-01_conndata-network_connectivity.tsv          as per BEP017: connectivity data schema
         └─ sub-01_conndata-network_connectivity.json

Datatype: model

Template:

sub-<label>/
    [ses-<label>/]
        model/
            [sub-<label>][_ses-<label>][_task-<label>][_acq-<label>][_rec-<label>][_run-<index>][_res-<label>][_desc-<label>]_eq.xml
            [sub-<label>][_ses-<label>][_task-<label>][_acq-<label>][_rec-<label>][_run-<index>][_res-<label>][_desc-<label>]_param.xml
Legend:

  • For more information about filename elements (for example, entities, suffixes, extensions), follow the links embedded in the filename template.

  • Filename entities or directories between square brackets (for example, [_ses-<label>]) are OPTIONAL.

  • Some entities may only allow specific values, in which case those values are listed in <>, separated by |.

  • _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

  • .<extension> means that there are several (>6) valid extensions for this file type.

  • [.gz] means that both the unzipped and gzipped versions of the extension are valid.

Equations and parameters MUST be specified using the XML-based Low Entropy Model Specification (LEMS) format. LEMS provides a compact, minimally redundant, human-readable, human-writable, declarative way of expressing models of physical systems. PyLEMS is a Python implementation of the LEMS language that can both parse and simulate existing LEMS models and provides an API in Python for reading, modifying and writing LEMS files. See the original publication introducing LEMS, and its repository with examples for more information. A basic principle of LEMS is to separate equations and parameter settings such that the equations need only be stated once and can then be reused with different parameterizations.

Entity: model equations (suffix: "_eq.xml")

Every simulation result MUST link to the used equations in LEMS-formatted *_eq.xml files using the metadata keyword "ModelEq".

Entity: model parameters (suffix: "_param.xml")

Every simulation result MUST link to the used parameter settings in LEMS-formatted *_param.xml files using the keyword "ModelParam".

Datatype: code

Code involves

  • "source code" (human-readable standard programming language)

  • and "machine code" (executable program; in the case of an interpreted language like Python, machine code and source code may be identical).

Every BIDS dataset that contains simulation results MUST either directly store the source code and the executable machine code that was used to produce the result in the modality agnostic directory code or in a publicly accessible long-term repository. Every BIDS file that contains a simulation result MUST have a JSON sidecar file that links to the location of the used codes (either using URIs or relative file paths in the BIDS data set) using the metadata keys "SourceCodeRepository" and "MachineCodeRepository".

It is preferred that machine code exist in the form of self-contained container images (including the entire necessary computational environment).

Metadata

Note: currently there is no datatype for simulation results in BIDS. There are however efforts towards a datatype to store time series, which may then be accompanied by JSON sidecar files with the entities below. Furthermore, connectivity information must be referenced using the entity "Connectivity", support for which is currently developed in BEP017

Key name Requirement Level Data type Description
SourceCodeRepository REQUIRED array of strings or string Either reference to modality agnostic folder "code" or URI to a publicly accessible repository where the source code used to produce the simulation result is provided.
MachineCodeRepository REQUIRED array of strings or string Either reference to modality agnostic folder "code" or URI to a publicly accessible repository where the machine code used to produce the simulation result is provided.
ModelEq REQUIRED array of strings or string Reference to one or more _eq.xml file(s) where the computational model used to produce a simulation result is specified in LEMS format.
ModelParam REQUIRED array of strings or string Reference to one or more _param.xml file(s) where the parameter setting used to produce a simulation result is specified in LEMS format.
Connectivity REQUIRED array of strings or string Reference to one or more _conndata-network_connectivity.tsv file(s) where the structural connectivity used to produce a simulation result is specified.