# Anonymization Application

Application used for comparison of different anonymization tools for anatomical NIfTI images.
Input data needs to be in the [BIDS format](https://bids.neuroimaging.io/). Different sessions and runs are currently not supported.

User can figure out direct errors of different anonymization tools and also their influence on chosen anatomical preprocessing pipelines.

### Supported anonymization tools:
* [afni_refacer_deface](https://afni.nimh.nih.gov/pub/dist/doc/program_help/@afni_refacer_run.html)
* [afni_refacer_reface](https://afni.nimh.nih.gov/pub/dist/doc/program_help/@afni_refacer_run.html)
* [fsl_deface](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSL)
* [mri_reface](https://www.nitrc.org/projects/mri_reface/)
* [pydeface](https://github.com/poldracklab/pydeface)
* [quickshear](https://github.com/nipy/quickshear)
<br>

### Supported processing pipelines:
* [SPM](https://www.fil.ion.ucl.ac.uk/spm/software/spm12/)
* [fMRIPrep](https://fmriprep.org/en/stable/index.html)


## Install
**Prerequisites:** 
* [Docker](https://www.docker.com/)
* FreeSurfer license file [license.tx](https://surfer.nmr.mgh.harvard.edu/registration.html)

License file for FreeSurfer can be freely downloaded from provided link. Application needs this file to be placed under its top directory where the Dockerfile is located. The name of the license file needs to be *license.txt*. Software FreeSurfer is required for fMRIPrep.

Once you have successfully finished these steps, you are able to build the application image with this command:<br>
```console
docker build -t anon_app path/to/application/top/directory
```
Change path `path/to/application/top/directory` to absolute path of application top directory in your computer. Docker will look for the Dockerfile located in this directory and will build the image from it.

Then you can run the application with command:<br>
```console
docker run -it --rm \
-v path/to/data_dir:/data \
-v path/to/working_dir:/out \
anon_app
```
* change `path/to/data_dir` to path to the directory where BIDS dataset is stored which you want to anonymize and analyze
* change `path/to/working_dir` to path where application working directory will be mounted, when you analize data fro the first time, working directory needs to be empty

Note that image will take up 42.5GB of memory.

## Usage
After you run Docker container, you can write application commands in container's shell.

General command structure is:
```console
python3 main.py [subcommand]
```

Subcommands include:
* start
* subjects
* anonymize
* spm
* fmriprep
* statistics
* statistics_pipeline
* cost_statistics_pipeline
* orig_vols

Subcommand `start` needs to be executed always as first command when you want to analyze new BIDS dataset. It checks if input data have correct format and prepares working directory, copies there original data. 

Subcommand `subjects` lists all found participant_ids in directory.

Subcommand `anonymize` executes image anonymization.
Flags include:
* -m, --method<br>
name of anonymization tool, mandatory
* -s, --subjects<br>
participant_ids, can be multiple, default all in dataset
* -c, --cost<br>
cost function which is one of options for afni_refacer_deface, afni_refacer_reface and pydeface
* -B, --bias_correct<br>
use bias correct option in fsl_deface
* -a, --afni_mask<br>
input brain mask for quickshear is generated by 3dSkullStrip from Afni instead of BET from FSL

Subcommands `spm` and `fmriprep` execute image processing with these tools. They have same flags as subcommand `anonymize` to locate created anonymized images. Under flag `-m` we can put `original`, to also process original data, which will be used for comparison of anonymization tools.

Subcommand `statistics` computes statistics for chosen anonymization tools with certain setting.
Flags include:
* -m, --methods<br>
names of [anonymization tools](#supported-anonymization-tools) whose outputs we want to analyze, default all
* -p, --pipeline<br>
[pipeline](#supported-processing-pipelines), whose image processing is to be analyzed
* -s, --subjects<br>
participant_ids, can be multiple, default all in dataset
* -c, --cost<br>
[cost function](#cost-commands-for-afnirefacerdeface-and-afnirefacerreface-include) which is was used with afni_refacer_deface, afni_refacer_reface or pydeface
* -B, --bias_correct<br>
bias correct option was used with fsl_deface
* -a, --afni_mask<br>
input brain mask for quickshear was generated by 3dSkullStrip from Afni instead of BET from FSL

When flag -c, -B or -a is included in subcommand, under -m need to be specified only anonymization tools which support it. Subcommand expects that all needed data for analyses has already been created with `anonymize` and then `spm` or `fmriprep`, including processing of original data.

Subcommand `statistics_pipeline` combines anonymization, data processing and statistics into one call. It has same flags as subcommand `statistics`. Additionally one can use flag -skip_o, --skip_original, which tells the program to skip processing of original data. It is handy when we generate multiple statistics where original data stays the same, so we don't want to process it more times than necessary. Program then assumes that original data has already been processed.

Subcommand `cost_statistics_pipeline` combines anonymization, data processing and statistics into one call, for all the cost functions available under chosen anonymization tool.
Flags include:
* -m, --method<br>
pydeface, afni_refacer_deface, afni_refacer_reface, mandatory
* -p, --pipeline<br>
[pipeline](#supported-processing-pipelines), whose image processing is to be analyzed, mandatory
* -s, --subjects<br>
participant_ids, can be multiple, default all in dataset
* -skip_o, --skip_original<br>
skip processing of original data
* -skip_c, --skip_default_cost<br>
skip analyses of default cost

Subcommand `orig_vols` calculates original image's per voxel volumes of WM, GM and CSF identified from segmentation of processing pipeline and saves results to excel sheet. Subcommand assumes that segmentation has already been run for those subjects with `spm` or `fmriprep`.
Flags include:
* -s, --subjects<br>
participant_ids, can be multiple, default all in dataset
* -p, --pipeline<br>
[pipeline](#supported-processing-pipelines), whose image processing is to be analyzed, mandatory

#### Cost commands for afni_refacer_deface and afni_refacer_reface include:
* leastsq
* mutualinfo
* corratio_mul
* norm_mutualinfo
* hellinger
* corratio_add
* corratio_uns
* localPcorSigned
* localPcorAbs (default)
* localPcor+Others
* localPcorAbs+Others

#### Cost commands for pydeface include:
* mutualinfo (default)
* corratio
* normcorr
* normmi
* leastsq
* labeldiff
* bbr

