Logo Logo

The BIDS Template File

Introduction

This article describes the BIDS template file. See the sections below to learn more about each attribute.

Namespace
Definitions
Auto Updates
- String
- Object
Rules
- Match conditions
- Initialized conditions
Upload rules
Custom project template
Custom initializers
Format
Field map IntendedFor fields
Resolvers
Template validation schema

Instruction Steps

Example BIDS Template

Below is an example of the bids-v1.json template.

{
 "namespace": "BIDS",
 "description": "Namespace for BIDS info objects in Flywheel",
 "definitions": {
  "Acq": {
   "type": "string",
   "title": "Acquisition Label",
   "default": "",
   "pattern": "^[a-zA-Z0-9]*$"
  },
  "Ce": {
   "type": "string",
   "title": "Contrast Agent Label",
   "default": "",
   "pattern": "^[a-zA-Z0-9]*$"
  },
  "Echo": {
   "type": "string",
   "title": "Echo Index",
   "default": "",
   "pattern": "^[0-9]*$"
  },
  "Filename": {
   "type": "string",
   "title": "Filename",
   "default": "",
   "minLength": 1
  },
  "IntendedFor": {
   "type": "array",
   "title": "IntendedFor",
   "default": [
    { "Folder": "anat" },
    { "Folder": "func" }
   ]
  },
  "Mod": {
   "type": "string",
   "title": "Mod Label",
   "default": "",
   "pattern": "^[a-zA-Z0-9]*$"
  },
  "Rec": {
   "type": "string",
   "title": "Reconstruction Algorithm Label",
   "default": "",
   "pattern": "^[a-zA-Z0-9]*$"
  },
  "Run": {
   "type": "string",
   "title": "Run Index",
   "default": "",
   "pattern": "^[0-9]*$"
  },
  "Task": {
   "type": "string",
   "title": "Task Label",
   "default": "",
   "pattern": "^[a-zA-Z0-9]+$"
  },

  "project": {
   "description": "BIDS project template",
   "properties": {
    "Name": {"type": "string", "title": "Name", "default": "", "auto_update": "{project.label}"},
    "BIDSVersion": {"type": "string", "title": "BIDS Version", "default": "1.0.2"},
    "License": {"type": "string", "title": "License", "default": ""},
    "Authors": {"type": "string", "title": "Authors", "default": []},
    "Acknowledgements": {"type": "string", "title": "Acknowledgements", "default": ""},
    "HowToAcknowledge": {"type": "string", "title": "How To Acknowledge", "default": ""},
    "Funding": {"type": "string", "title": "Funding Sources", "default": []},
    "ReferencesAndLinks": {"type": "string", "title":"Reference and Links", "default": []},
    "DatasetDOI": {"type": "string", "title": "Dataset DOI", "default": ""}
   },
   "required": []
  },
  "project_file": {
   "description": "BIDS project file template",
   "properties": {
    "Filename": {"$ref":"#/definitions/Filename"},
    "Folder": {"type": "string", "title": "Folder", "default": ""},
    "Path": {"type": "string", "title": "Path", "default": ""}
   },
   "required": ["Filename"]
  },
  "session": {
   "description": "BIDS session template",
   "properties": {
    "Label": {"type": "string", "title": "Label", "default": "", "auto_update": "<session.label>"},
    "Subject": {"type": "string", "title": "Subject Code", "default": "", "auto_update": "<subject.code>"}
   },
   "required": []
  },
  "session_file": {
   "description": "BIDS session file template",
   "properties": {
    "Filename": {"$ref":"#/definitions/Filename"},
    "Folder": {"type": "string", "title": "Folder", "default": "",
     "auto_update": "[ses-{session.info.BIDS.Label}]"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]"}
   },
   "required": ["Filename"]
  },
  "acquisition": {
   "description": "BIDS acquisition template",
   "properties": {
   },
   "required": []
  },
  "acquisition_file": {
   "description": "BIDS acquisition file template",
   "properties": {
    "Filename": {"$ref": "#/definitions/Filename"},
    "Folder": {"type": "string", "title": "Folder", "default": "",
     "auto_update": {
      "$process": true,
      "$value": "acq-<acquisition.label>",
      "$format": [{"$lower": true}]
     }
    },
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": {
      "$process": true,
      "$value": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/acq-<acquisition.label>",
      "$format": [{"$lower": true}]
     }
    }
   },
   "required": ["Filename"]
  },
  "anat_file": {
   "description": "BIDS template for anat files",
   "properties": {
    "Filename": {"type": "string", "title": "Filename", "default": "", "minLength": 1,
     "auto_update": "sub-{session.info.BIDS.Subject}[_ses-{session.info.BIDS.Label}][_acq-{file.info.BIDS.Acq}][_ce-{file.info.BIDS.Ce}][_rec-{file.info.BIDS.Rec}][_run-{file.info.BIDS.Run}][_mod-{file.info.BIDS.Mod}]_{file.info.BIDS.Modality}{ext}"},
    "Folder": {"type": "string", "title": "Folder", "default": "anat"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/{file.info.BIDS.Folder}"},
    "Acq": {"$ref":"#/definitions/Acq"},
    "Ce": {"$ref":"#/definitions/Ce"},
    "Rec": {"$ref":"#/definitions/Rec"},
    "Run": {"$ref":"#/definitions/Run"},
    "Mod": {"$ref":"#/definitions/Mod"},
    "Modality": {"type": "string", "title": "Modality Label", "default": "",
     "enum": [
      "T1w",
      "T2w",
      "T1rho",
      "T1map",
      "T2map",
      "FLAIR",
      "FLASH",
      "PD",
      "PDmap",
      "PDT2",
      "inplaneT1",
      "inplaneT2",
      "angio",
      "defacemask",
      "SWImagandphase"
     ]
    }
   },
   "required": ["Filename", "Modality"]
  },
  "func_file": {
   "description": "BIDS template for func files",
   "properties": {
    "Filename": {"type": "string", "title": "Filename", "default": "", "minLength": 1,
     "auto_update": "sub-{session.info.BIDS.Subject}[_ses-{session.info.BIDS.Label}]_task-{file.info.BIDS.Task}[_acq-{file.info.BIDS.Acq}][_rec-{file.info.BIDS.Rec}][_run-{file.info.BIDS.Run}][_echo-{file.info.BIDS.Echo}]_{file.info.BIDS.Modality}{ext}"},
    "Folder": {"type": "string", "title": "Folder", "default": "func"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/{file.info.BIDS.Folder}"},
    "Acq": {"$ref":"#/definitions/Acq"},
    "Task": {"$ref":"#/definitions/Task"},
    "Rec": {"$ref":"#/definitions/Rec"},
    "Run": {"$ref":"#/definitions/Run"},
    "Echo": {"$ref":"#/definitions/Echo"},
    "Modality": {"type": "string", "title": "Modality Label", "default": "bold",
     "enum": [
      "bold",
      "sbref",
      "stim",
      "physio"
     ]
    }
   },
   "required": ["Filename", "Task", "Modality"]
  },
  "task_events_file": {
   "description": "BIDS template for task events files",
   "properties": {
    "Filename": {"type": "string", "title": "Filename", "default": "", "minLength": 1,
     "auto_update": "sub-{session.info.BIDS.Subject}[_ses-{session.info.BIDS.Label}]_task-{file.info.BIDS.Task}[_acq-{file.info.BIDS.Acq}][_rec-{file.info.BIDS.Rec}][_run-{file.info.BIDS.Run}][_echo-{file.info.BIDS.Echo}]_events.tsv"},
    "Folder": {"type": "string", "title": "Folder", "default": "func"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/{file.info.BIDS.Folder}"},
    "Task": { "$ref": "#/definitions/Task" },
    "Acq": {"$ref":"#/definitions/Acq"},
    "Rec": {"$ref":"#/definitions/Rec"},
    "Run": {"$ref":"#/definitions/Run"},
    "Echo": {"$ref":"#/definitions/Echo"}
   },
   "required": ["Filename", "Task"]
  },
  "beh_events_file": {
   "description": "BIDS template for behavioral events files",
   "properties": {
    "Filename": {"type": "string", "title": "Filename", "default": "", "minLength": 1,
     "auto_update": "sub-{session.info.BIDS.Subject}[_ses-{session.info.BIDS.Label}]_task-{file.info.BIDS.Task}_events.tsv"},
    "Folder": {"type": "string", "title": "Folder", "default": "beh"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/{file.info.BIDS.Folder}"},
    "Task": {"$ref":"#/definitions/Task"}
   },
   "required": ["Filename", "Task"]
  },
  "physio_task_file": {
   "description": "BIDS template for physio files",
   "properties": {
    "Filename": {"type": "string", "title": "Filename", "default": "", "minLength": 1,
     "auto_update": "sub-{session.info.BIDS.Subject}[_ses-{session.info.BIDS.Label}]_task-{file.info.BIDS.Task}[_acq-{file.info.BIDS.Acq}][_rec-{file.info.BIDS.Rec}][_run-{file.info.BIDS.Run}][_echo-{file.info.BIDS.Echo}][_recording-{file.info.BIDS.recording}]_{file.info.BIDS.Modality}{ext}"},
    "Folder": {"type": "string", "title": "Folder", "default": "func"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/{file.info.BIDS.Folder}"},
    "Acq": {"$ref":"#/definitions/Acq"},
    "Task": {"$ref":"#/definitions/Task"},
    "Rec": {"$ref":"#/definitions/Rec"},
    "Run": {"$ref":"#/definitions/Run"},
    "Echo": {"$ref":"#/definitions/Echo"},
    "Recording": {"type": "string", "title": "Recording Label", "default": ""},
    "Modality": {"type": "string", "title": "Modality Label", "default": "physio",
     "enum": [
      "stim",
      "physio"
     ]
    }
   },
   "required": ["Filename", "Task", "Modality"]
  },
  "diffusion_file": {
   "description": "BIDS template for diffusion files",
   "properties": {
    "Filename": {"type": "string", "title": "Filename", "default": "", "minLength": 1,
     "auto_update":"sub-{session.info.BIDS.Subject}[_ses-{session.info.BIDS.Label}][_acq-{file.info.BIDS.Acq}][_run-{file.info.BIDS.Run}]_{file.info.BIDS.Modality}{ext}"},
    "Folder": {"type": "string", "title": "Folder", "default": "dwi"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/{file.info.BIDS.Folder}"},
    "Acq": {"$ref":"#/definitions/Acq"},
    "Run": {"$ref":"#/definitions/Run"},
    "Modality": {"type": "string", "title": "Modality Label", "default": "dwi",
     "enum": [
      "dwi",
      "sbref"
     ]
    }
   },
   "required": ["Filename", "Modality"]
  },
  "fieldmap_file": {
   "description": "BIDS template for field map files",
   "properties": {
    "Filename": {"type": "string", "title": "Filename", "default": "", "minLength": 1,
     "auto_update":"sub-{session.info.BIDS.Subject}[_ses-{session.info.BIDS.Label}][_acq-{file.info.BIDS.Acq}][_run-{file.info.BIDS.Run}][_dir-{file.info.BIDS.Dir}]_{file.info.BIDS.Modality}{ext}"},
    "Folder": {"type": "string", "title": "Folder", "default": "fmap"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/{file.info.BIDS.Folder}"},
    "Acq": {"$ref":"#/definitions/Acq"},
    "Run": {"$ref":"#/definitions/Run"},
    "Dir": {"type": "string", "title": "Dir Label", "default": ""},
    "IntendedFor": {"$ref":"#/definitions/IntendedFor"},
    "Modality": {"type": "string", "title": "Modality Label", "default": "fieldmap",
     "enum": [
      "phasediff",
      "magnitude1",
      "magnitude2",
      "phase1",
      "phase2",
      "magnitude",
      "fieldmap",
      "epi"
      ]
    }
   },
   "required": ["Filename", "Modality"]
  },
  "fieldmap_phase_encoded_file": {
   "description": "BIDS template for phase encoded field map files",
   "properties": {
    "Filename": {"type": "string", "label": "Filename", "default": "",
     "auto_update":"sub-{session.info.BIDS.Subject}[_ses-{session.info.BIDS.Label}][_acq-{file.info.BIDS.Acq}][_run-{file.info.BIDS.Run}]_dir-{file.info.BIDS.Dir}_{file.info.BIDS.Modality}{ext}"},
    "Folder": {"type": "string", "label": "Folder", "default": "fmap"},
    "Path": {"type": "string", "label": "Path", "default": "",
     "auto_update": "sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]/{file.info.BIDS.Folder}"},
    "Acq": {"type": "string", "label": "Acq Label", "default": ""},
    "Run": {"type": "string", "label": "Run Index", "default": ""},
    "Dir": {"type": "string", "label": "Dir Label", "default": ""},
    "IntendedFor": {"$ref":"#/definitions/IntendedFor"},
    "Modality": {"type": "string", "label": "Modality Label", "default": "epi",
     "enum": [
      "phasediff",
      "magnitude1",
      "magnitude2",
      "phase1",
      "phase2",
      "magnitude",
      "fieldmap",
      "epi"
      ]
    }
   },
   "required": ["Filename", "Folder", "Path", "Modality", "Dir"]
  },
  "dicom_file": {
   "description": "BIDS template for DICOM files",
   "properties": {
    "Filename": {"$ref":"#/definitions/Filename"},
    "Folder": {"type": "string", "title": "Folder", "default": "sourcedata"},
    "Path": {"type": "string", "title": "Path", "default": "",
     "auto_update": "{file.info.BIDS.Folder}/sub-{session.info.BIDS.Subject}[/ses-{session.info.BIDS.Label}]"}
   },
   "required": ["Filename", "Folder"]
  },
  "json_file": {
   "description": "BIDS template for JSON files",
   "properties": {
    "Filename": {"$ref":"#/definitions/Filename"},
    "Folder": {"type": "string", "title": "Folder", "default": ""},
    "Path": {"type": "string", "title": "Path", "default": ""}
   },
   "required": ["Filename"]
  }
 },
 "rules": [
  {
   "id": "bids_project",
   "template": "project",
   "where": {
    "container_type": "project"
   }
  },
  {
   "id": "bids_project_file",
   "template": "project_file",
   "where": {
    "container_type": "file",
    "parent_container_type": "project"
   }
  },
  {
   "id": "bids_session",
   "template": "session",
   "where": {
    "container_type": "session"
   }
  },
  {
   "id": "bids_session_file",
   "template": "session_file",
   "where": {
    "container_type": "file",
    "parent_container_type": "session"
   }
  },
  {
   "id": "bids_acquisition",
   "template": "acquisition",
   "where": {
    "container_type": "acquisition"
   },
   "initialize": {
    "ignore": {
     "$switch": {
      "$on": "acquisition.label",
      "$cases": [
       {
        "$regex": "(^|.*_)ignore-BIDS",
        "$value": true
       },
       {
        "$default": true,
        "$value": false
       }
      ]
     }
    }
   }
  },
  {
   "id": "bids_anat_file",
   "template": "anat_file",
   "where": {
    "container_type": "file",
    "parent_container_type": "acquisition",
    "file.type": {
     "$in": ["nifti", "NIfTI"]
    },
    "file.classification.Measurement": {
     "$in": [ "T1", "PD", "T2" ]
    },
    "file.classification.Intent": {
     "$in" : [ "Structural" ]
    }
   },
   "initialize": {
    "Task": {
     "acquisition.label": {
      "$regex": "(^|_)task-(?P<value>[^-_]+)"
     }
    },
    "Run": {
     "acquisition.label": {
      "$regex": [
       "(^|_)run-(?P<value>\\d+)",
       "(^|_)run(?P<value>[=+])"
      ]
     },
     "$run_counter": {
      "key": "anat.{file.info.BIDS.Task}"
     }
    }
   }
  },
  {
   "id": "bids_func_file",
   "template": "func_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["nifti", "NIfTI"]
    },
    "file.classification.Intent": {
     "$in" : [ "Functional" ]
    }
   },
   "initialize": {
    "Task": {
     "acquisition.label": {
      "$regex": "(^|_)task-(?P<value>[^-_]+)"
     }
    },
    "Run": {
     "acquisition.label": {
      "$regex": [
       "(^|_)run-(?P<value>\\d+)",
       "(^|_)run(?P<value>[=+])"
      ]
     },
     "$run_counter": {
      "key": "functional.{file.info.BIDS.Task}"
     }
    },
    "Modality": {
     "$switch": {
      "$on": "file.info.ImageType",
      "$cases": [
       {
        "$eq": [ "ORIGINAL", "PRIMARY", "P", "ND", "MOSAIC"  ],
        "$value": "sbref"
       },
       {
        "$eq": [ "ORIGINAL", "PRIMARY", "M", "ND", "MOSAIC"  ],
        "$value": "sbref"
       },
       {
        "$eq": [ "ORIGINAL", "PRIMARY", "M", "ND", "NORM", "MOSAIC"  ],
        "$value": "sbref"
       }
      ]
     }
    }
   }
  },
  {
   "id": "bids_task_events_file",
   "template": "task_events_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["tabular data", "Tabular Data"]
    },
    "file.classification.Intent": {
     "$in" : [ "Functional" ]
    }
   },
   "initialize": {
    "Task": {
     "acquisition.label": {
      "$regex": "(^|_)task-(?P<value>[^-_]+)"
     }
    },
    "Run": {
     "acquisition.label": {
      "$regex": [
       "(^|_)run-(?P<value>\\d+)",
       "(^|_)run(?P<value>[=+])"
      ]
     },
     "$run_counter": {
      "key": "task_events.{file.info.BIDS.Task}"
     }
    }
   }
  },
  {
   "id": "bids_task_events_file_by_name",
   "template": "task_events_file",
   "where": {
    "container_type": "file",
    "file.name": {
     "$regex": "^.*events\\.tsv$"
    }
   },
   "initialize": {
    "Task": {
     "acquisition.label": {
      "$regex": "(^|_)task-(?P<value>[^-_]+)"
     }
    },
    "Run": {
     "acquisition.label": {
      "$regex": [
       "(^|_)run-(?P<value>\\d+)",
       "(^|_)run(?P<value>[=+])"
      ]
     },
     "$run_counter": {
      "key": "task_events.{file.info.BIDS.Task}"
     }
    }
   }
  },
  {
   "id": "bids_beh_events_file",
   "template": "beh_events_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["tabular data", "Tabular Data"]
    },
    "file.classification.Custom": {
     "$in" : [ "Behavioral" ]
    }
   },
   "initialize": {
    "Task": {
     "acquisition.label": {
      "$regex": "(^|_)task-(?P<value>[^-_]+)"
     }
    }
   }
  },
  {
   "id": "bids_physio_task_file",
   "template": "physio_task_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["tabular data", "Tabular Data"]
    },
    "file.classification.Custom": {
     "$in" : [ "Physio" ]
    }
   },
   "initialize": {
    "Task": {
     "acquisition.label": {
      "$regex": "(^|_)task-(?P<value>[^-_]+)"
     }
    },
    "Run": {
     "acquisition.label": {
      "$regex": [
       "(^|_)run-(?P<value>\\d+)",
       "(^|_)run(?P<value>[=+])"
      ]
     },
     "$run_counter": {
      "key": "physio.{file.info.BIDS.Task}"
     }
    }
   }
  },
  {
   "id": "bids_diffusion_file",
   "template": "diffusion_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["nifti", "bvec", "bval", "NIfTI", "BVEC", "BVAL"]
    },
    "file.classification.Measurement": {
     "$in": [ "Diffusion" ]
    },
    "file.classification.Intent": {
     "$in" : [ "Structural" ]
    }
   },
   "initialize": {
    "Run": {
     "acquisition.label": {
      "$regex": [
       "(^|_)run-(?P<value>\\d+)",
       "(^|_)run(?P<value>[=+])"
      ]
     },
     "$run_counter": {
      "key": "diffusion"
     }
    }
   }
  },
  {
   "id": "bids_fieldmap_phase_encoded_file",
   "template": "fieldmap_phase_encoded_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["nifti", "NIfTI"]
    },
    "file.classification.Intent": {
     "$in" : [ "Fieldmap" ]
    },
    "acquisition.label": {
     "$regex": "[T|t]opup"
    }
   },
   "initialize": {
    "Dir": {
     "$comment": "Currently matching bipedal orientations",
     "acquisition.label": {
      "$regex": "([^a-zA-Z0-9]|^)(?P<value>[aprlhfAPRLHF]{2})([^a-zA-Z0-9]|$)"
     }
    },
    "Run": {
     "acquisition.label": {
      "$regex": [
       "(^|_)run-(?P<value>\\d+)",
       "(^|_)run(?P<value>[=+])"
      ]
     },
     "$run_counter": {
      "key": "field_map.{file.info.BIDS.Dir}"
     }
    }
   }
  },
  {
   "id": "bids_fieldmap_file",
   "template": "fieldmap_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["nifti", "NIfTI"]
    },
    "file.classification.Intent": {
     "$in" : [ "Fieldmap" ]
    }
   },
   "initialize": {
    "Run": {
     "acquisition.label": {
      "$regex": [
       "(^|_)run-(?P<value>\\d+)",
       "(^|_)run(?P<value>[=+])"
      ]
     },
     "$run_counter": {
      "key": "field_map"
     }
    }
   }
  },
  {
   "id": "bids_dicom_file",
   "template": "dicom_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["dicom", "DICOM"]
    },
    "file.classification.Intent": {
     "$in": [ "Structural", "Fieldmap", "Functional" ]
    }
   },
   "initialize": {
    "Filename": {
     "file.name": { "$take": true }
    }
   }
  },
  {
   "id": "bids_json_file",
   "template": "json_file",
   "where": {
    "container_type": "file",
    "file.type": {
     "$in": ["source code", "JSON"]
    }
   }
  }
 ],
 "upload_rules": [
  {
   "id": "bids_acquisition_file",
   "template": "acquisition_file",
   "where": {
    "container_type": "file",
    "parent_container_type": "acquisition"
   }
  }
 ],
 "resolvers": [
  {
   "id": "bids_intended_for",
   "templates": [ "fieldmap_file", "fieldmap_phase_encoded_file" ],
   "update": "file.info.IntendedFor",
   "filter": "file.info.BIDS.IntendedFor",
   "resolveFor": "session",
   "type": "file",
   "format": "[ses-{session.info.BIDS.Label}/]{file.info.BIDS.Folder}/{file.info.BIDS.Filename}"
  }
 ]
}

Namespace

At the top level of the template JSON file is a namespace attribute. This is where all of the metadata for that template will be stored. The only valid value for namespace is BIDS.

Definitions

The objects under the definitions object of the template JSON file are JSON schemas that support local referencing of other definitions using the $ref attribute. Typically, there will be a few property definitions at the top of the definitions, followed by a few templates.

A property definition may look something like this:

"Run": {
 "type": "string",
 "title": "Run Index",
 "default": "",
 "pattern": "^[0-9]*$"
}

The above example is describing the Run attribute that is commonly used for acquisitions. It is saying that the info.BIDS.Run attribute must be a string. The pattern property indicates that any characters must be digits.

A template definition simply describes the properties that are expected to be found in BIDS metadata that matches this template. Note that Acq and Run are references to common properties, and that filename and modality are required fields for this template. A template definition may look something like this:

"fieldmap_file": {
 "description": "BIDS template for field map files",
 "properties": {
  "Filename": {
   "type": "string", 
   "title": "Filename", 
   "default": "",
   "minLength": 1,
   "auto_update":"..."
  },
  "Folder": {
   "type": "string", 
   "title": "Folder", 
   "default": "fmap"
  },
  "Path": {
   "type": "string", 
   "title": "Path", 
   "default": "",
   "auto_update": "..."
  },
  "Acq": { "$ref":"#/definitions/Acq" },
  "Run": { "$ref":"#/definitions/Run" },
  "Dir": {
   "type": "string", 
   "title": "Dir Label", 
   "default": ""
  },
  "Modality": {
   "type": "string", 
   "title": "Modality Label", 
   "default": "fieldmap",
   "enum": [
    "phasediff",
    "magnitude1",
    "magnitude2",
    "phase1",
    "phase2",
    "magnitude",
    "fieldmap",
    "epi"
   ]
  }
 },
 "required": ["Filename", "Modality"]
}

NOTE: The auto_update properties are truncated here and will be covered in the next section.

Auto Updates

There are 2 options for auto updates: string or object

String

When the template engine is running in update mode, any field in a template definition that has an auto_update property will automatically be updated by formatting the auto_update string using the current context. There are a few special rules to be aware of in the string formatting:

Normalized Substitution; Variables in angle brackets “<>” will be converted to lower camel case (removing the spaces) before being substituted in the string.
Literal Substitution: Variables in curly brackets “{}” will not be modified before being substituted in the string.
Optional Values: Square brackets “[]” indicate that a section is optional. These sections will only be present if the referenced field has a non-empty value.

For example: sub-<subject.code>[/ses-<session.label>]/{file.info.BIDS.Folder}

In the above example, subject.code is required, and will be converted to lower camel case before being substituted. session.label is optional, and if present, the section in brackets will be present, and session.label will be converted to lower camel case. Finally, file.info.BIDS.Folder is required, and will not be modified before being substituted.

Object

In addition to using a string to auto update certain fields, it is possible to set up more powerful formatting auto update using an object. For example

"Label": {
  "type": "string", "title": "Label", "default": "",
  "auto_update": {
    "$process": true,
    "$value": "{session.label}",
    "$format": [
      {"$lower": true}
    ]
  }
}

According to the above example, the Label field would be updated to the session. label after being processed as a string according to the rules in the above section, and then formatted to be in lower case. For more information on the format field, check the format section.

Rules

Rules provide logic for matching a context to a template definition, and in some cases, they also provide logic for initializing some of the fields from the context.

An example rule:

{
    "id": "bids_fieldmap_file",
    "template": "fieldmap_file",
    "where": {
        "container_type": "file",
        "file.type": {
            "$in": ["nifti", "NIfTI"]
        },
        "file.measurements": {
            "$in": ["field_map"]
        }
    },
    "initialize": {
        "Run": {
            "acquisition.label": {
                "$regex": "_run-(?P<value>\\d+)",
      “$format”: [
          “$replace”: {
                        “$pattern”: “[^a-zA-Z0-9]”, 
“$replacement”: “NewString”
  }
                ]
            }
        }
    }
}

id: The above rule specifies an id, which is optional in custom templates but required in predefined templates. The rule id can be used to reference the rule in other areas of the template. The template field indicates what template this rule will apply if all of the conditions in the where property are true.
where: The where property is a set of conditions that must all be true for the rule to match. The general pattern is that the keys are the names of properties to check, and the values are either the value (e.g. in container_type) or further details about how to match (e.g. the special property $in in file. type indicates that the measurements field should be one of the values in the specified array). See the match and initialized conditions below for all possible rule conditions.
Initialize: The initialize property is a list of rules for initializing properties within the BIDS info object. It consists of a set of property names (the keys) and rules for initializing them (the values.) In the above case, we are initializing info.BIDS.Run from acquisition.label using a regular expression to extract the run number.

The initialized values can further be formatted using regex patterns and replacement strings. The formatting rules are an ordered list that are always executed last, allowing for a procedural execution of $format commands.

A full list of possible rule conditions:

Match Conditions

In addition to matching an exact value, the following keywords are currently supported in rule matches

**$in: [<values>]** - Matches if the specified property is an exact match for any value in the list.
**$not: <rule or value>**- Negates the specified rule or value match.
$regex: “regex” - Matches if the specified regular expression is found in the value string. Use the ^ and $ operators to specify whole string matches.

Initialized Conditions

Initialization can be done one of 3 ways:

$regex: “regex” - Initializes the property using the value group of the regular expression. For example: _run-(?P\d+) will match any digit characters after the string “_run-”
**$take: true** - Initializes the property by taking the value specified.
$switch {cases}: - Allows mapping from one value to another via case statements. For example:

"$switch": {
  "$on": "file.info.ImageType",
  "$cases": [
    {
      "$eq": [ "ORIGINAL", "PRIMARY", "P", "ND", "MOSAIC"  ],
      "$value": "sbref"
    },
    {
      "$eq": [ "ORIGINAL", "PRIMARY", "M", "ND", "MOSAIC"  ],
      "$value": "sbref"
    },
    {
      "$eq": [ "ORIGINAL", "PRIMARY", "M", "ND", "NORM", "MOSAIC"  ],
      "$value": "sbref"
    },
    {
      "$default": true,
      "$value": "bold"
    }
  ]
}

Matches the $on field, in this case file.info.ImageType and uses set comparison against each case, in order, taking the first match. If $default is true, then that case always matches. Note: Value / String comparison is also supported.

Upload Rules

A template may also include a set of rules under the field upload_rules. These rules will only used when using bids import, which does not support custom templates.

Custom Project Template

Projects can provide a custom template for BIDS curation by uploading their template as project-template.json as a file attachment to the project. The project-template.json can either be a completely new template, or it can extend from an existing template. The expected common use case for custom templates is to provide additional matching or initialization rules based on the structure of the project in question.

Here's an example of extending an existing template:

{
  "extends": "bids-v1",
  "description": "Additional rules for matching custom data",
  "exclude_rules": [ "bids_json_file" ],
  "rules": [
    {
      "template": "task_events_file",
      "where": {
        "container_type": "file",
        "file.name": {
          "$regex": ".+_run-\\d+_bold.tsv"
        }
      },
      "initialize": {
        "Folder": "func",
        "Task": {
          "acquisition.label": {
            "$regex": "_task-(?P<value>[^-_]+)"
          }
        },
        "Run": {
          "acquisition.label": {
            "$regex": "_run-(?P<value>\\d+)"
          }
        }
      }
    }
  ]
}

The only differences between this template and a full template are, the extends property, indicating what template to base this template off of, and the exclude_rules property, that allows the exclusion of rules (by id) from the parent template. Otherwise, new definitions and rules can be specified as in a normal template.

Custom Initializers

As of version 0.3.3 of the curate-bids gear, custom project templates support adding additional initializers to a rule without having to redefine the rule. For example:

{
  "extends": "bids-v1",
  "description": "Additional rules for initialization using acq label",
  "initializers": [
    {
      "rule": "bids_func_file",
      "initialize": {
        "Task": {
          "acquisition.label": {
            "$regex": "(?P<value>[^-]+[^0-9])",
            "$format": [
              {"$replace": {"$pattern": "_", "$replacement": ""}}
            ]
          }
        },
        "Run": {
          "acquisition.label": {
            "$regex": "(?P<value>\\d+)"
          }
        }
      }
    }
  ]
}

The above template will match acquisition labels such as red_green1 and extract a task (removing disallowed characters) and a run number, such that the task would be redgreen and the run number would be 1.

Format

Allow a pipeline of string formatting. The format field should be an array of the above operations, the order is preserved and is the order in which the operations are executed:

Replace: {“$replace”: {“$pattern”: “[a-z]”, “$replacement”: “Character”}}
Lower case: {“$lower”: {“$pattern”: “[a-z]”} or {“$lower”: true}
Upper case: {“$upper”: {“$pattern”: “[a-z]”} or {“$upper”: true}
Camel case: {“$camelCase”: {“$pattern”: “[a-z]”} or {“$camelCase”: true}

Field map `IntendedFor` fields

Within the BIDS specification, field maps should have an IntendedFor field in their sidecar that indicates (via list of local filenames) what MRI scans the field maps are intended to correct. On Flywheel, this is done by setting metadata (also called "Custom Information") on a field map NIfTI file that is a list called file.info.IntendedFor.

The template processing engine sets what the BIDS specification requires, file.info.IntendedFor, by using information provided infile.info.BIDS.IntendedFor (note the "BIDS" part). The latter, a list of lists, acts as a set of filters on files at the session level that the current field map is intended to correct. If the first filter (list 0) is a list of only one item that is "Folder" = " anat" like this:

It means that all files in the BIDS anat folder will be included in the file.info.IntendedFor list on the field map. To filter the list of files more narrowly, for instance if you wanted to target a single fMRI run, you could specify something like this:

Here the file.info.BIDS.IntendedFor list also has "Run" = "1" so only the files in the anat folder that also have "run-1" in their BIDS name will be included. The next item further filters the list to only the files that also have "task-redgreen" in their BIDS file names. Additional filters (more than one list of lists) can cause the same field map to be applied to multiple BIDS directories (anat, dwi, func).

For projects that have consistent sessions, it is best practice to configure a custom template to initialize the file.info.IntendedForfield for each field map in the protocol. The custom initializers mentioned above also support conditional matching the same as other rules, so specific initialization can be done based on rule matching. For example:

{
  "extends": "bids-v1",
  "description": "Additional rules for initializing fieldmaps",
  "initializers": [
    {
      "rule": "bids_fieldmap_phase_encoded_file",
      "where": {
        "file.info.ImageType": {
          "$in": ["DIFFUSION"]
        }
      },
      "initialize": {
        "Acq": "dti",
        "IntendedFor": [
          {"Folder": "dwi"}
        ]
      }
    },
    {
      "rule": "bids_fieldmap_phase_encoded_file",
      "where": {
        "file.info.ImageType": {
          "$in": ["M"]
        }
      },
      "initialize": {
        "IntendedFor": [
          {"Folder": "func"}
        ]
      }
    }
  ]
}

Resolvers

The information in file.info.BIDS.IntendedFor is set by rules in the project curation template that recognize and initialize field maps. This information is then used by " resolvers" to determine file.info.IntendedFor:

    "resolvers": [  
        {  
            "id": "bids\_intended\_for",  
            "templates": [  
                "fieldmap\_file",  
                "fieldmap\_phase\_encoded\_file"  
            ],  
            "update": "file.info.IntendedFor",  
            "filter": "file.info.BIDS.IntendedFor",  
            "resolveFor": "session",  
            "type": "file",  
            "format": "[ses-{session.info.BIDS.Label}/]{file.info.BIDS.Folder}/{file.info.BIDS.Filename}"  
        }  
    ]

Resolvers represent a final additional pass through the context after everything else is done. That is, all of the containers and files have been examined by the rules of the template in the first pass and all of the BIDS metadata fields have been determined by the information in the context. For example, the "Run" attribute has been filled out along with "Task", "Acq", etc. and each NIfTI file's BIDS folder and filename have been determined,and file.info.BIDS.IntendedForhas been set.

Resolvers are a way to figure out a piece of information that can only be known after the initial pass. Currently, the only example is the "IntendedFor" field as shown above. It says to "update" the metadata file.info.IntendedFor for anything in the context that is a fieldmap_file using the "filter" information found in file.info.BIDS.IntendedFor.

If, for a particular field map filter, file.info.BIDS.IntendedFor lists "func" as the folder and "2" for the run, the resolver finds all files in the "func" folder that have "Run" = "2" and the result might look like this:

That is, the "format" of the resolver combines the session label, the BIDS folder, and the BIDS filename to produce the relative paths to the files that a particular field map is to modify as required by the BIDS specification.

This is repeated for each of the listed "templates" which are definitions found at the top of the project curation template json file, so any fieldmap_phase\_encoded\_file found in the context are resolved after any fieldmap_file are found.

Just to be clear, note that a field map file.info.BIDS.IntendedFor is in the "BIDS" name space while the results, file.info.IntendedFor are in the "file.info" name space similar to DICOM tag values and will therefore end up in the json sidecar for the field map when BIDS formatted data is exported. The "BIDS" name space is only used during project curation template processing and is not exported in the json sidecar.

Template Validation Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "definitions": {
    "match-condition": {
      "type": "object",
      "properties": {
        "$in": {
          "oneOf": [
            {"type": "string"},
            {"type": "array", "item": "string"}
          ]
        },
        "$not": {"$ref": "#/definitions/match-condition"},
        "$regex": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "where-clause": {
      "type": "object",
      "properties": {
        "$or": {"$ref": "#/definitions/where-clause"},
        "$and": {"$ref": "#/definitions/where-clause"}
      },
      "patternProperties": {
        "^\\w+(\\.\\w+)*$": {
          "oneOf": [
            {"type": "string"},
            {"$ref": "#/definitions/match-condition"}
          ]
        }
      },
      "additionalProperties": false
    },
    "switch-case": {
      "type": "object",
      "properties": {
        "$eq": {"type":["string", "object", "array", "number"]},
        "$value": {"type": ["string", "object", "array", "number"]},
        "$default": {"type": "boolean"}
      },
      "additionalProperties": false,
      "required": ["$value"]
    },
    "switch": {
      "type": "object",
      "properties": {
        "$on": {
          "type": "string"
        },
        "$cases": {
          "type": "array",
          "items": {"$ref": "#/definitions/switch-case"}
        }
      },
      "additionalProperties": false
    },
    "regex": {
      "type": "string"
    },
    "regexes": {
      "type": "array",
      "items": {"$ref": "#/definitions/regex"}
    },
    "format-replace": {
      "type": "object",
      "properties": {
        "$pattern": {"$ref": "#/definitions/regex"},
        "$replacement": {"type": "string"}
      },
      "additionalProperties": false
    },
    "format-lower": {
      "type": "object",
      "properties": {
        "$pattern": {"$ref": "#/definitions/regex"}
      },
      "additionalProperties": false
    },
    "format-letter-case": {
      "type": "object",
      "properties": {
        "$pattern": {"$ref": "#/definitions/regex"}
      },
      "additionalProperties": false
    },
    "format": {
      "type": "object",
      "properties": {
        "$replace": {"$ref": "#/definitions/format-replace"},
        "$lower": {
          "oneOf": [
            {"type": "boolean"},
            {"$ref": "#/definitions/format-letter-case"}
          ]
        },
        "$upper": {
          "oneOf": [
            {"type": "boolean"},
            {"$ref": "#/definitions/format-letter-case"}
          ]
        },
        "$camelCase": {"type": "boolean"}
      },
      "additionalProperties": false
    },
    "context-initializer": {
      "type": "object",
      "patternProperties" : {
        "^\\w+(\\.\\w+)*$": {
          "type": "object",
          "properties": {
            "$regex": {
              "oneOf": [
                {"$ref": "#/definitions/regexes"},
                {"$ref": "#/definitions/regex"}
              ]
            },
            "$take": {
              "type": "boolean"
            },
            "$format": {
              "type": "array",
              "items": {"$ref": "#/definitions/format"}
            }
          }
        }
      },
      "properties": {
        "$run_counter": {
          "type": "object",
          "properties": {
            "key": {"type": "string"}
          }
        },
        "$comment": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "initializer": {
      "type": "object",
      "patternProperties": {
        ".+": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "$switch": {"$ref": "#/definitions/switch"}
              },
              "additionalProperties": false,
              "required": ["$switch"]
            },
            {
              "type": "object",
              "properties": {
              },
              "additionalProperties": false,
              "required": ["$run_counter"]
            },
            {"$ref": "#/definitions/context-initializer"},
            {"type": ["string", "array"]}
          ]
        }
      },
      "additionalProperties": false
    },
    "rule": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "template": {
          "type": "string"
        },
        "where": {"$ref": "#/definitions/where-clause"},
        "initialize": {"$ref": "#/definitions/initializer"}
      },
      "required": ["id", "template", "where"]
    },
    "rules": {
      "type": "array",
      "items": {"$ref": "#/definitions/rule"}
    },
    "upload_rules": {
      "type": "array",
      "items": {"$ref": "#/definitions/rule"}
    },
    "definitions": {"$ref": "http://json-schema.org/draft-04/schema#/properties/definitions"},
    "resolver": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "templates": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "update": {
          "type": "string",
          "pattern": "^\\w+(\\.\\w+)*$"
        },
        "filter": {
          "type": "string",
          "pattern": "^\\w+(\\.\\w+)*$"
        },
        "resolveFor": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "format":{
          "type": "string"
        }
      },
      "required": ["id", "templates", "update", "filter", "resolveFor", "type", "format"],
      "additionalProperties": false
    },
    "resolvers": {
      "type": "array",
      "item": {"$ref": "#/definitions/resolver"}
    },
    "initializers": {
      "type": "array",
      "item": {"$ref": "#/definitions/initializer"}
    }
  },
  "type": "object",
  "title": "Rules",
  "properties": {
    "description": {"type": "string"},
    "namespace": {"type": "string"},
    "rules": {"$ref": "#/definitions/rules"},
    "definitions": {"$ref": "#/definitions/definitions"},
    "upload_rules": {"$ref": "#/definitions/rules"},
    "resolvers": {"$ref": "#/definitions/resolvers"},
    "initializers": {"$ref": "#/definitions/initializers"},
    "extends": {
      "type": "string"
    },
    "exclude-rules": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}