Finishing up

After a successful run of bidscoiner, the work to convert your data in a fully compliant BIDS dataset is unfortunately not yet fully over and, depending on the complexity of your data-set, additional tools may need to be run and meta-data may need to be entered manually (not everything can be automated).

Adding meta-data

For instance, you should update the content of the dataset_description.json and README files in your bids folder and you may need to provide e.g. additional *_scans.tsv,*_sessions.tsv or participants.json files (see the BIDS specification for more information). Moreover, if you have behavioural log-files you will find that BIDScoin does not (yet) support converting these into BIDS compliant *_events.tsv/json files (advanced users are encouraged to use the bidscoiner plug-in possibility and write their own log-file parser).

Data sharing utilities

Multi-echo combination

Before sharing or pre-processing their images, users may want to combine the separate the individual echos of multi-echo MRI acquisitions. The echcombine-tool is a wrapper around mecombine that writes BIDS valid output.

usage: echocombine [-h] [-p PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                   [-o {fmap,anat,func,dwi,beh,pet,extra_data,derivatives}]
                   [-a {PAID,TE,average}] [-w [WEIGHTS [WEIGHTS ...]]]
                   bidsfolder pattern

A wrapper around the 'mecombine' multi-echo combination tool (https://github.com/Donders-Institute/multiecho).

This wrapper is fully BIDS-aware (a 'bidsapp') and writes BIDS compliant output

positional arguments:
  bidsfolder            The bids-directory with the (multi-echo) subject data
  pattern               Globlike recursive search pattern (relative to the
                        subject/session folder) to select the first echo of
                        the images that need to be combined, e.g.
                        '*task-*echo-1*'

optional arguments:
  -h, --help            show this help message and exit
  -p PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
                        Space separated list of sub-# identifiers to be
                        processed (the sub- prefix can be left out). If not
                        specified then all sub-folders in the bidsfolder will
                        be processed (default: None)
  -o {fmap,anat,func,dwi,beh,pet,extra_data,derivatives}, --output {fmap,anat,func,dwi,beh,pet,extra_data,derivatives}
                        A string that determines where the output is saved. It
                        can be the name of a BIDS modality folder, such as
                        'func', or of the derivatives folder, i.e.
                        'derivatives'. If output = [the name of the input
                        modality folder] then the original echo images are
                        replaced by one combined image. If output is left
                        empty then the combined image is saved in the input
                        modality folder and the original echo images are moved
                        to the extra_data folder (default: None)
  -a {PAID,TE,average}, --algorithm {PAID,TE,average}
                        Combination algorithm (default: TE)
  -w [WEIGHTS [WEIGHTS ...]], --weights [WEIGHTS [WEIGHTS ...]]
                        Weights for each echo (default: None)

examples:
  echocombine /project/3017065.01/bids func/*task-stroop*echo-1*
  echocombine /project/3017065.01/bids *task-stroop*echo-1* -p 001 003
  echocombine /project/3017065.01/bids func/*task-*echo-1* -o func
  echocombine /project/3017065.01/bids func/*task-*echo-1* -o derivatives -w 13 26 39 52
  echocombine /project/3017065.01/bids func/*task-*echo-1* -a PAID

Defacing

Before sharing or pre-processing their images, users may want to deface their anatomical MRI acquisitions as to protect the privacy of their subjects. The deface-tool is a wrapper around pydeface that writes BIDS valid output.

usage: deface [-h] [-p PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
              [-o {fmap,anat,func,dwi,beh,pet,extra_data,derivatives}] [-c]
              [-n NATIVESPEC] [-a ARGS]
              bidsfolder pattern

A wrapper around the 'pydeface' defacing tool (https://github.com/poldracklab/pydeface).

This wrapper is fully BIDS-aware (a 'bidsapp') and writes BIDS compliant output

positional arguments:
  bidsfolder            The bids-directory with the (multi-echo) subject data
  pattern               Globlike search pattern (relative to the
                        subject/session folder) to select the images that need
                        to be defaced, e.g. 'anat/*_T1w*'

optional arguments:
  -h, --help            show this help message and exit
  -p PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
                        Space separated list of sub-# identifiers to be
                        processed (the sub- prefix can be left out). If not
                        specified then all sub-folders in the bidsfolder will
                        be processed (default: None)
  -o {fmap,anat,func,dwi,beh,pet,extra_data,derivatives}, --output {fmap,anat,func,dwi,beh,pet,extra_data,derivatives}
                        A string that determines where the defaced images are
                        saved. It can be the name of a BIDS modality folder,
                        such as 'anat', or of the derivatives folder, i.e.
                        'derivatives'. If output is left empty then the
                        original images are replaced by the defaced images
                        (default: None)
  -c, --cluster         Flag to submit the deface jobs to the high-performance
                        compute (HPC) cluster (default: False)
  -n NATIVESPEC, --nativespec NATIVESPEC
                        DRMAA native specifications for submitting deface jobs
                        to the HPC cluster (default: -l
                        walltime=00:30:00,mem=1gb)
  -a ARGS, --args ARGS  Additional arguments (in dict/json-style) that are
                        passed to pydeface. See examples for usage (default:
                        {})

examples:
  deface /project/3017065.01/bids anat/*_T1w*
  deface /project/3017065.01/bids anat/*_T1w* -p 001 003 -o derivatives
  deface /project/3017065.01/bids anat/*_T1w* -n "-l walltime=00:60:00,mem=2gb"
  deface /project/3017065.01/bids anat/*_T1w* -a '{"cost": "corratio", "verbose": ""}'

BIDS validation

If all of the above work is done, you can (and should) run the web-based bidsvalidator to check for inconsistencies or missing files in your bids data-set (NB: the bidsvalidator also exists as a command-line tool).