The bidsmap explained¶
Structure and content¶
Generally speaking, a bidsmap is a collection of run-items that define how different source data runs (e.g. a T1w- or a T2w-scan) should map onto BIDS filenames. As illustrated in the figure below (but see also the screenshot of the edit window), a run-item consists of provenance
, attributes
, filesystem
and bids
key-value dictionaries:
- The provenance item contains the pathname of a source data sample that is representative for the run-item.
- The attributes dictionary contains keys and values that are properties of the source data itself that can identify a run-item.
- The filesystem dictionary contains keys and values that are properties of the file system that can identify a run-item.
- The bids dictionary contains key-value pairs that are used to construct the associated BIDS output filename of a run-item.
The collection of run-items is hierarchically organised in DICOM
and PAR
source modality sections, which in turn contain subsections for the anat
, func
, dwi
, fmap
, pet
, beh
and extra_data
datatypes as well as a participant_label
and session_label
subsection. The latter two are common to all run-items and contain key-value pairs that identify the subject and session labels. Next to the two source modality sections there is a general Options
and a PlugIns
section, that accommodate customized BIDScoin settings and tweaks.
BIDScoin tools are processing source data, they will take a data sample and go through the list of run-items until they come across a run-item that matches with the data sample at hand. At that point a bidsmapping is established and the bidsname can be derived.
From template to study¶
A bidsmap can either be a template bidsmap or a study bidsmap. The difference between them is that a template bidsmap is a comprehensive set of pre-defined run-items and serves as an input for the bidsmapper to automatically make a first version of a study bidsmap. The study bidsmap is thus derived from the template bidsmap and contains only those run-items that are present in the data. The study bidsmap can be interactively edited with knowledge that is specific to a study and that cannot be extracted from the data (e.g. set a task
value to “rest”). A user normally doesn’t have to interact with the template bidsmap, but it is sure possible to create your own.
Special bidsmap features¶
- Source attribute matching patterns. Source attribute values can contain Unix shell-style
*
wildcards to facilitate more liberal run matching. For instance you can useSeriesDescription: '*MPRAGE*'
to match all MPRAGE DICOM series as they come from your MRI scanner. - Source attribute list. Instead of a normal string, a source attribute value can also be a list of strings, in which case a match is positive if any of the list items matches with the source attribute of the run. For instance
SequenceName: ['\*epfid\*', 'fm2d2r']
will liberally match all DICOM sequences with that haveepfid
in theirSequenceName
and it will strictly match onfm2d2r
. - Dynamic bids value. Bids values can be static, in which case the value is just a normal string, or dynamic, when the string is enclosed with pointy brackets. In case of single pointy brackets the bids value will be replaced during bidsmapper, bidseditor and bidscoiner runtime by the value of the source attribute. For instance
acq: <MRAcquisitionType><SeriesDescription>
will be replaced byacq: 3DMPRAGE
. In case of double enclosed pointy brackets, the value will be updated only during bidscoiner runtime – this is useful for bids values that are subject/session dependent. For instancerun: <<1>>
will be replaced withrun: 1
or e.g. increased torun: 2
if a file with that bidsname already exists. - Bids value list. Instead of a normal string, a bids value can also be a list of strings, with the last list item being the (zero-based) list index that selects the final bids value. For instance the list
['mag', 'phase', 'real', 'imag', 1]
would selectphase
as a value. A bids value list is made visible in the bidseditor as a drop-down menu.
The special bidsmap features are most useful when added to template bidsmaps.