Skip to content

Home

Jump to bottom
Michał Szczepanik edited this page Feb 2, 2018 · 20 revisions

Welcome to the osirix-bids-output wiki!

How to use

  1. Select the required studies. Click Plugins -> Database -> BIDS Output. The plugin will find all unique sequence names across the studies and list them.

  2. Fill in information telling what each study means, then click save mapping and continue.

  • If no suffix is chosen, series with a given name will be omitted during export.
  • If a series with a given name occurs more than once for a given subject (and is not a fieldmap), there are two possibilities:
    • if run label was not specified, run numbers will be automatically generated
    • if run number was specified, a re-start of acquisition will be assumed and all sessions but the last will be discarded.
  • Fieldmaps are currently assumed to come in a form of a phasediff and 2 magnitude images, all with the same series name (this is what we get from our Siemens Trio scanner). A similar logic as above is applied to the triplets of series.
  • Additionally, you can enter the minimum number of images in a bold series. The plugin will ignore bold runs with less than the given number of volumes (may be helpful in discarding re-started epi runs).
  • Keep in mind that if you gave distinct names to all runs of your task, you will have to specify the run label for each one of them. The plugin operates on sequence names and annotates them according to your input.
  • You can also set session name and rename subjects by clicking Subject & session rules. For a more datailed explanation, see the regular expressions page. These are the options for sessions:
    • fixed - given label will be assigned to all exported data
    • infer from subject name - you may specify a regular expression, which will be used to extract session label from subject name
    • infer from series name - as above, but this time series names are checked
  • Task name will be added to JSON files accompanying bold files (in the obligatory TaskName field). Task label (part of filename) will be derived from task name by removing non-alphanumeric characters, as described in the BIDS spec. All other fields should be specified as labels.
  • Keep in mind that the plugin does not perform any validation of your input.

  1. A summary of found series will be presented: Set the path to dcm2niix. If an executable is found at ~/dcm2niix, it will be filled in as default. Set the path to where BIDS root will be located. You can create new directories. Optionally check "Use compression" to write .nii.gz files. Click "Export to BIDS". Wait as DICOMs are copied and dcm2niix is being called.

  2. Behind the scenes, the plugin works in the following way. First, it creates a temporary, hidden .dicom folder in the BIDS root. Then, one series at a time, it copies dicoms there, runs dcm2niix, and removes the copy of dicoms. Finally, the temporary folder is erased.

  3. The example BIDS folder looks as follows:

  4. The result is a bare-bones BIDS dataset. The primary aim of the plugin is to help with exporting and sorting the imaging data. Although the output as it comes is likely to pass the BIDS validator without errors, some additional curation will be needed to make the dataset complete and useful. Follow the BIDS specification for the details. The most important points are listed below:

  • First and foremost, task imaging data requires event .tsv files to be included (unless it is a resting state).
  • The datset_description.json file contains only the two required fields, Name and BIDSVersion. It is worthwile to manually fill in the remaining, optional fields.
  • Task data json file contains raw dcm2niix output (i.e. the information found in dicom files), plus the TaskName field. Consider adding additional fields, in particular TaskDescription and CogAtlasID.
  • If you have multiple fieldmap runs, you should add the (optional) IntendedFor json field to link the fieldmap data to specific scans.
  • BIDS allows additional, optional, files, such as participants.tsv or README.

Known limitations

  1. Not all BIDS suffixes and terms are available in the GUI.
  2. Field maps are handled only in the case of one phasediff and two magnitude images (based on the Siemens Trio output). Phasediff and magnitude are recognized based on the DICOM ImageType (0008, 0008) tag. Magnitude 1/2 are recognized based on the DICOM EchoTime (0018, 0081) tag, with index 1 assigned to the shorter TE.
  3. With several exceptions, the json sidecars are raw dcm2niix output. The exceptions are: EchoTime field (in phasediff sidecar), TaskName field (in bold sidecar) and the deletion of sidecars for magnitude images (fieldmap).
  4. As a feature, dcm2niix updates its defaults every time it is being run. The plugin calls dcm2niix with a fixed filename, so the defaults get overwritten. Later releases of dcm2niix will most likely implement a flag to disable this behaviour.
Clone this wiki locally