===== 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 :abbr:`BIDS (Brain Imaging Data Structure)` 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 ====================== .. argparse:: :ref: bidsonym.run_deeid.get_parser :prog: bidsonym :nodefault: :nodefaultconst: Example Call(s) --------------- Below you'll find two examples calls that hopefully help you to familiarize yourself with ``BIDSonym`` and its options. Example 1 ~~~~~~~~~ .. code-block:: bash 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 ~~~~~~~~~ .. code-block:: bash 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.