Usage

Execution and the BIDS format

The general input of BIDSonym is a path to the dataset that should be de-identified. The input dataset is required to be in valid BIDS format. We highly recommend that you validate your dataset before you run BIDSonym with the free, online BIDS Validator. However, the BIDS Validator is also run at the beginning of BIDSonym and will you make you aware of possible problems and/or inconsistencies. The exact command to run BIDSonym depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Here’s a very conceptual example:

bidsonym data/bids_root/ analysis_level optional_arguments

However, it is important to note that BIDSonym is a special case of a BIDS-App in that it doesn’t create a folder under the derivatives/ directory within which its outputs are written. As BIDSonym is intended to be run after conversion (from e.g. DICOM) but before any other processing step (e.g., quality control, preprocessing, etc.), the original files (non-defaced images and complete JSON) will be moved to sourcedata/bidsonym and copied back to the bids_root directory after de-indentification. Based on this approach de-identified data will enter the processing stream, but in case the defacing was not successful (too much or too little cut out) the non-defaced images can be re-used, without the necessity to run the conversion again.

Command-Line Arguments

a BIDS app for de-identification of neuroimaging data

usage: bidsonym [-h]
                [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [--session SESSION [SESSION ...]]
                [--deid {pydeface,mri_deface,quickshear,mridefacer}]
                [--deface_t2w] [--check_meta CHECK_META [CHECK_META ...]]
                [--del_meta DEL_META [DEL_META ...]]
                [--brainextraction {bet,nobrainer}] [--bet_frac BET_FRAC]
                [--skip_bids_validation] [-v]
                bids_dir {participant,group}

Positional Arguments

bids_dir

The directory with the input dataset formatted according to the BIDS standard.

analysis_level

Possible choices: participant, group

Level of the analysis that will be performed. Multiple participant level analyses can be run independently (in parallel) using the same output_dir.

Named Arguments

--participant_label

The label(s) of the participant(s) that should be pseudonymized. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“). If this parameter is not provided all subjects will be pseudonymized. Multiple participants can be specified with a space separated list.

--session

The label(s) of the session(s) that should be pseudonymized. The label corresponds to ses-<participant_label> from the BIDS spec (so it does not include “ses-“). If this parameter is not provided all sessions will be pseudonymized. Multiple sessions can be specified with a space separated list.

--deid

Possible choices: pydeface, mri_deface, quickshear, mridefacer

Approach to use for de-identifictation.

--deface_t2w

Deface T2w images by using defaced T1w image as deface-mask.

--check_meta

Indicate which information from the image and .json meta-data files should be check for potentially problematic information. Indicate strings that should be searched for. The results will be saved to sourcedata/

--del_meta

Indicate if and which information from the .json meta-data files should be deleted. If so, the original .json files will be copied to sourcedata/

--brainextraction

Possible choices: bet, nobrainer

What algorithm should be used for pre-defacing brain extraction (outputs will be used in quality control).

--bet_frac

In case BET is used for pre-defacing brain extraction, provide a Frac value.

--skip_bids_validation

Assume the input dataset is BIDS compliant and skip the validation (default: False).

-v, --version

show program’s version number and exit

Example Call(s)

Below you’ll find two examples calls that hopefully help you to familiarize yourself with BIDSonym and its options.

Example 1

bidsonym \
/home/peer/bids/ \
participant \
--participant_label 01 \
--deid pydeface \
--brainextraction bet \
--bet_frac 0.5 \
--del_meta 'InstitutionAddress' \

Here’s what’s in this call:

  • The 1st positional argument is the BIDS directory (/home/peer/bids)

  • The 2nd positional argument specifies whether we are running participant- or group-level mode. In more detail, if only a certain or all participants should be de-identified. You can choose between participant and group. Here we choose participant.

  • The 3rd positional argument defines the subject id, thus which specific participant should be de-identified. In this case, we choose 01.

  • The 4th positional argument specifies which defacing algorithm should be run. You can choose between mri_deface, pydeface, quickshear and mridefacer. In this example we choose pydeface.

  • The 5th positional argument specifies the algorithm that should be used for brain extraction (which will be used for quality control purposes). You have the options bet or nobrainer. Here we chose bet.

  • The 6th position argument specifies the fractional intensity threshold used for bet. The value can range between 0 and 1, here we chose the default of 0.5. Please note, that this argument is only necessary when bet was chosen as brain extraction tool.

  • The 7th argument indicates which metadata fields of the sidecar JSON file(s) should be deleted. This can be any of those included in the BIDS specification, if it exists in the JSON sidecar files of your BIDS dataset.

Example 2

bidsonym \
/home/peer/bids/ \
group \
--deid mridefacer \
--brainextraction nobrainer \

Here’s what’s in this call:

  • The 1st positional argument again is the BIDS directory (/home/peer/bids)

  • The 2nd positional argument once more specifies whether we are running participant- or group-level mode. In more detail, if only a certain or all participants should be de-identified. You can choose between participant and group. Here we choose group. Hence, all participants will be de-identified and we don’t need to specific a --participant_label as in Example 1.

  • The 3rd positional argument specifies which defacing algorithm should be run. You can choose between mri_deface, pydeface, quickshear and mridefacer. This time we choose mridefacer.

  • The 4th positional argument specifies the algorithm that should be used for brain extraction (which will be used for quality control purposes). You have the options bet or nobrainer. Here we chose nobrainer.

  • Contrary to Example 1, we don’t delete any metadata field(s) of the sidecar JSON files.

Support and communication

The documentation of this project is found here: https://peerherholz.github.io/BIDSonym.

All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/peerherholz/bidsonym/issues.

If you have a problem or would like to ask a question about how to use BIDSonym, please submit a question to NeuroStars.org with an bidsonym tag. NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.

All previous BIDSonym questions are available here: http://neurostars.org/tags/bidsonym/

Not running on a local machine? - Data transfer

If you intend to run BIDSonym on a remote system, you will need to make your data available within that system first.

Please contact you local system administrator regarding possible and favourable transfer options (e.g., rsync or FileZilla).

A very comprehensive approach would be Datalad, which will handle data transfers with the appropriate settings and commands. Datalad also performs version control over your data.