Finishing up¶
After a successful run of bidscoiner, the work to convert your data in a fully compliant BIDS dataset is usually not fully over and, depending on the complexity of your data-set, additional tools may need to be run to post-process (e.g. deface) your data or convert datatypes not supported by the standard BIDScoin plugins (e.g. EEG data). Below you can find some tips and additional BIDScoin tools that may help you finishing up.
Adding more meta-data¶
To make your dataset reproducable and shareable, you should add study-level meta-data in the modality agnostic BIDS files (BIDScoin saves stub versions of them). 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 *_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 option 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 OUTPUT]
[-a {PAID,TE,average}] [-w [WEIGHTS [WEIGHTS ...]]] [-f]
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 OUTPUT, --output OUTPUT
A string that determines where the output is saved. It can be the name of a BIDS
datatype folder, such as 'func', or of the derivatives folder, i.e.
'derivatives'. If output = [the name of the input datatype 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 datatype folder and the original
echo images are moved to the extra_data folder (default: )
-a {PAID,TE,average}, --algorithm {PAID,TE,average}
Combination algorithm (default: TE)
-w [WEIGHTS [WEIGHTS ...]], --weights [WEIGHTS [WEIGHTS ...]]
Weights for each echo (default: None)
-f, --force If this flag is given subjects will be processed, regardless of existing target
files already exist. Otherwise the echo-combination will be skipped (default:
False)
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 to protect the privacy of their subjects. The deface
-tool is a wrapper around pydeface that writes BIDS valid output. NB: pydeface requires FSL to be installed on the system.
usage: deface [-h] [-p PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [-o OUTPUT] [-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
For multi-echo data see `medeface`
positional arguments:
bidsfolder The bids-directory with the 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 OUTPUT, --output OUTPUT
A string that determines where the defaced images are saved. It can be the name
of a BIDS datatype 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=2gb)
-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* -c -n "-l walltime=00:60:00,mem=4gb"
deface /project/3017065.01/bids anat/*_T1w* -a '{"cost": "corratio", "verbose": ""}'
Multi-echo defacing¶
This utility is very similar to the deface utility above, except that it can handle multi-echo data.
usage: medeface [-h] [-m MASKPATTERN] [-p PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [-o OUTPUT] [-c]
[-n NATIVESPEC] [-a ARGS]
bidsfolder pattern
A wrapper around the 'pydeface' defacing tool (https://github.com/poldracklab/pydeface) that computes
a defacing mask on a (temporary) echo-combined image and then applies it to each individual echo-image.
This wrapper is fully BIDS-aware (a 'bidsapp') and writes BIDS compliant output
For single-echo data see `deface`
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/*_T2starw*'
optional arguments:
-h, --help show this help message and exit
-m MASKPATTERN, --maskpattern MASKPATTERN
Globlike search pattern (relative to the subject/session folder) to select the
images from which the defacemask is computed, e.g. 'anat/*_part-mag_*_T2starw*'.
If not given then 'pattern' is used (default: None)
-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 OUTPUT, --output OUTPUT
A string that determines where the defaced images are saved. It can be the name
of a BIDS datatype 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=2gb)
-a ARGS, --args ARGS Additional arguments (in dict/json-style) that are passed to pydeface. See
examples for usage (default: {})
examples:
medeface /project/3017065.01/bids anat/*_T1w*
medeface /project/3017065.01/bids anat/*_T1w* -p 001 003 -o derivatives
medeface /project/3017065.01/bids anat/*_T1w* -c -n "-l walltime=00:60:00,mem=4gb"
medeface /project/3017065.01/bids anat/*acq-GRE* -m anat/*acq-GRE*magnitude*"
medeface /project/3017065.01/bids anat/*_FLAIR* -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).
Note
Privacy-sensitive source data samples may be stored in [bidsfolder]/code/bidscoin/provenance
(see the -s
option in the bidsmapper).