Skip to content

Home

Jump to bottom
Michał Szczepanik edited this page May 11, 2022 · 20 revisions

Welcome to the horos-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 series (scan) name means, then click save mapping and continue.

  • The list of possible suffixes is scrollable.
  • 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.
  • 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.
  • BIDS describes four cases for field maps, and we support two of them, selectable through the suffix list:
    • (fmap) corresponds to one phasediff and two magnitude images, all three saved with the same series name (this is what we get from our Siemens Trio scanner). If there are multiple such runs, a similar logic as above is applied to the triplets of series to generate run numbers.
    • dir-AP_epi and dir-PA_epi correspond to multiple phase encoded directions ("pepolar"), also known as blip-up and blip-down. In this case AP and PA are expected to have different series names, and you need to choose which is which. For multiple runs, they are handled like any other series.
  • The content of the Task Name column will be added verbatim to the 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.
  • Using task names from Coginitive Atlas whenever possible is recommended.
  • You can save or load this mapping. For details go to Saving and loading the general mapping, essentials are below.
    • If you plan to export more subjects from a given experiment in the future, you can save the mapping you entered by clicking Store mapping for later. The plugin will prompt for a file name and location, and save the mapping in a JSON file. You can perform this step both before and after clicking Save mapping and continue.
    • If you have a JSON file with a mapping, you can load it by clicking Use stored mapping. The plugin will take the information from this file, use it to annotate the series from the selected studies, and proceed to the next step.
  • 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 functional runs).
  • Clicking Subject & session rules will let you set session names and rename subjects. For a more detailed explanation, see the subject and session rules page.
  • Clicking Dataset description will show a popover where you can fill in all fields of the obligatory dataset_description.json file. Of those fields, only two (Name and BIDS version) are required. You can skip writing the dataset_description.json file (e.g. when you are adding files to an already existing dataset) by ticking don't create in the popover. In the JSON file, Authors and References and Links fields should contain lists; you can separate the elements with a semi-colon (and no additional spaces).
  • Keep in mind that the plugin does not perform any validation of your input.
  1. A summary of found series will be presented:

If you see that something is wrong, you can close the summary, change the input in the previous window (General Mapping Window) and click Save mapping and continue once again.

After checking the summary, set the path to dcm2niix (it will be used to do the conversion) and the path of BIDS root (the folder in which your file structure will be created). If an executable is found at ~/dcm2niix, it will be filled in as default. You can create new directories when setting BIDS root.

Additionally, there are two options you can use. Check "Use compression" to write .nii.gz files. Check "Create scans file" to create scans.tsv files.

The scans file contains relative file name and acquisition date/time of each imaging sequence within a subject or session. If you wish to shift the dates for anonymization purposes, you will have to do it after the export (the plugin provides no such functionality). Consult the BIDS specification for more details.

Click "Export to BIDS". Wait as DICOMs are copied and dcm2niix is being called.

The table you see will be saved in a .csv file under ~/HorosBidsOutput/export_YYYY-MM-DD_hhmmss.csv (~/ is your home directory, and the name of the file contains a date and time of the export) to allow inspection in the future. The ~/HorosBidsOutput directory will be created if needed.

In some cases, most notably when dcm2niix exits with a non-zero exit code (meaning that there was an error during export), the plugin will skip processing of a given series and proceed to the next one. At the end, ~/HorosBidsOutput/errors_YYYY-MM-DD_hhmmss file listing all troublesome series will be created and the popup window will tell you that the export finished with errors.

  1. Behind the scenes, the plugin works in the following way. First, it creates a temporary dicom folder in the ~/HorosBidsOutput folder. Then, one series at a time, it creates symbolic links to dicom files in this location, runs dcm2niix, and removes the symlinks. Finally, the temporary folder is erased.

  2. The example BIDS folder looks as follows:

  3. 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).
  • 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 two cases (out of four described in BIDS): phasediff & magnitude, or multiple phase encoded directions. In the first case, 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. These rules were determined based on the Siemens Trio output. In the second case, AP/PA directions need to be chosen manually.
  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, up to (and including) version 1.0.20171215 (December 15th 2017), dcm2niix updated its defaults every time it was being run. Version 1.0.20180328 (pre-release, March 28th 2018) introduced a flag to modify this behaviour, and by default the defaults are no longer changed. The plugin calls dcm2niix with a fixed filename, so with older dcm2niix versions the defaults will get overwritten by the last exported file. Consider using the latest dcm2niix release.
Clone this wiki locally