Addition of a LORIS tool to deface structural images and register the defaced images back into LORIS #366

cmadjar · 2018-12-14T22:08:18Z

Description

This PR adds a new tool that will allow defacing of the structural images listed in the Config module under the imaging pipeline section in the new field called modalities_to_deface (See PR aces/Loris#4232 on the LORIS side for the SQL patch).

Note that the script deface_minipipe.pl in uploadNeuroDB/bin has been taken out of the BIC EZminc GitHub repo (https://github.com/BIC-MNI/EZminc/tree/ITK4/scripts).

Screenshot of a defaced scan:

How to use the tool

Make sure to populate the configuration modalities_to_deface in the imaging pipeline section of the Configuration module with all scan types that you wish to deface (typically, T1W, T2W, T2*, FLAIR and other 3D structural images)
To run the tool, go to the tools directory and run:
perl run_defacing_script.pl -profile <profile> [ -sessionIDs <list of sessionIDs> ]
Note that if the -sessionIDs is not passed to the script, it will deface images from all sessions with the modalities to deface.

Note that the defaced images will be registered in LORIS as modality-defaced (where modality is replaced by t1, t2, flair...). The new MRI scan type called modality-defaced is automatically created in the mri_scan_type table by run_defacing_script.pl based on the name of the modality to deface.

Special notes for multi-contrast acquisitions:

At the top of the script, 2 variables have been implemented and can be customized:

1. %SPECIAL_ACQUISITIONS_FILTER:

For acquisitions such as fieldmaps, a phase and two magnitude files are available. We only want to deface the magnitude files as the phase file does not have a face and we don't want to alter the phase image. To differentiate between the phase and magnitude files, we need to use the acquisition:image_type MINC header for which the value will be:

ORIGINAL\\PRIMARY\\M\\ND for the magnitude files
ORIGINAL\\PRIMARY\\P\\ND for the phase file

Therefore, to only deface the magnitude fieldmap images, we need to specify the value of acquisition:image_type in the constant variable %SPECIAL_ACQUISITIONS_FILTER at the top of the script like that:

my %SPECIAL_ACQUISITIONS_FILTER = (
    'fieldmap'      => 'ORIGINAL\\PRIMARY\\M\\ND'
);

In the script, this constant variable also shows examples for MP2RAGE and multi-echo acquisitions.

2. @MULTI_CONTRAST_ACQUISITIONS_BASE_NAMES

The @MULTI_CONTRAST_ACQUISITIONS_BASE_NAMES variable will store the base names of multi-contrast acquisitions such as MP2RAGE, qT2star or fieldmap. These will allow to call the deface_minipipe.pl tool properly for multi-contrast acquisition (a.k.a. fieldmap_file1,fieldmap_file2). Calling deface_minipipe.pl with images separated by , will tell the script not to create 2 XFMs (one for each fieldmap file) but instead reuse the XFM from fieldmap_file1 to register fieldmap_file2.

Notes for existing projects

If you desire to use this new tool, make sure you have:

downloaded and installed the bic-mni-models anatomical template library and the beast library from the MINC tools in /opt/minc/ (https://bic-mni.github.io/#data-files-and-models)
added the two following variables to your environment file so that the scripts can find the MNI models (replace %MINC_TOOLKIT_DIR% by the path to your MINC toolkit install):

# for the defacing scripts
export BEASTLIB=%MINC_TOOLKIT_DIR%/../share/beast-library-1.1
export MNI_MODELS=%MINC_TOOLKIT_DIR%/../share/icbm152_model_09c

sourced the SQL patch from the [Configuration] Adding configuration fields needed for imaging defacing tool Loris#4232 LORIS PR
adapted the constant variables (%SPECIAL_ACQUISITIONS_FILTER, @MULTI_CONTRAST_ACQUISITIONS_BASE_NAMES) at the top of the tools/run_defacing_script.pl script to your project's need.

Additional checks before running the script:

make sure which deface_minipipe.pl is returning the following $LORIS-MRI/uploadNeuroDB/bin/deface_minipipe.pl script and not the one present in the MINC toolkit (/opt/minc/$VERSION) as LORIS-MRI is using the version of deface_minipipe.pl under development (which have not yet been released with the MINC tools). If which deface_minipipe.pl is not pointing to the correct script, you will need to update your $PATH bash variable to make sure $LORIS-MRI/uploadNeuroDB/bin is the first path mentioned in the variable.

One note, you commented on the script I copied from the EZminc BIC repo so I did not integrate all your comments (like the exit code for example which is not implemented on the MINC tool side I believe). Since there are portions of the script I modified to make it more generic (it got merge before the holidays on the EZminc repo), I included your feedback on the parts I modified and will commit the changes to the EZminc repo so they can have it as well.

However, if you could review the script in the tools directory called run_deface_script.pl, that would be awesome!

Thank you so much!!

uploadNeuroDB/bin/deface_minipipe.pl

cmadjar · 2019-01-04T17:20:21Z

uploadNeuroDB/bin/deface_minipipe.pl

+                                         # (arguments without ,)
+
+# create the directory where the final outputs will be saved
+mkdir($output_dir) unless (-e $output_dir);


…ng tool (#4232) This adds to the imaging_pipeline section of the Config module 2 fields needed for the imaging defacing tool: - reference_scan_type_for_defacing: the reference image that will be used for registration (typically the t1w modality) - modalities_to_deface: multi-line options to list all 3D modalities that need to be defaced (for example t1w, flair, pd, t2w...) This goes with the LORIS-MRI PR: aces/Loris-MRI#366

tools/run_defacing_script.pl

cmadjar

@nicolasbrossard Thank you very much for your review. I included your feedback in the next commit. Ready for another review! :)

tools/run_defacing_script.pl

cmadjar

@PapillonMcGill Thank you for the comments. They should all be fixed in the last commit.

tools/run_defacing_script.pl

…scripts_md directory

docs/scripts_md/run_defacing_script.md

cmadjar

@PapillonMcGill thank you for the review. It should be taken care of in the last commit.

docs/scripts_md/run_defacing_script.md

PapillonMcGill · 2019-01-28T14:14:54Z

LGTM

…nts for defacing scripts

README.md

… the README.md

PapillonMcGill · 2019-02-12T15:00:19Z

no more objection!

cmadjar · 2019-02-14T16:00:24Z

@nicolasbrossard all your previous comments have been taken care of. Please re-review at your convenience. Thanks!

nicolasbrossard · 2019-02-19T13:36:34Z

uploadNeuroDB/NeuroDB/MRI.pm

@@ -1280,7 +1280,9 @@ sub compute_hash {
 	$ctx->add($file->getParameter('patient:birthdate'));          # Patient DOB
 	$ctx->add($file->getParameter('study_instance_uid'));         # StudyInstanceUID
 	$ctx->add($file->getParameter('series_description'));         # SeriesDescription
-    $ctx->add($file->getParameter('processing:intergradient_rejected')); 
+    if ($file->getParameter('processing:intergradient_rejected')) {


I do not know if this is possible but if parameter processing:intergradient_rejected exists and is either '' or 0, then this test evaluates to false. Is this what you want?

good catch!!! Should be corrected in the next commit.

nicolasbrossard

LGTM but I do have a question (see comments above).

…ng tool (aces#4232) This adds to the imaging_pipeline section of the Config module 2 fields needed for the imaging defacing tool: - reference_scan_type_for_defacing: the reference image that will be used for registration (typically the t1w modality) - modalities_to_deface: multi-line options to list all 3D modalities that need to be defaced (for example t1w, flair, pd, t2w...) This goes with the LORIS-MRI PR: aces/Loris-MRI#366

cmadjar added 9 commits December 5, 2018 18:45

first iteration of the defacing LORIS script

3b904ad

pipeline works fully and register defaced images in LORIS for simple …

cc92143

…acquisitions like t1, t2, flair etc... Need to work on multi-echo acquisitions and MP2RAGE now

perldoc of the functions

7042404

check that the files of the session were not already defaced

17020e0

updated queries for fileIDs so that it queries only the right file fo…

354eaea

…r special acquisition types such as MP2RAGE base on the minc header acquisition:image_type

added documentation for function check_if_deface_files_already_in_db

f225453

added latest development version of deface_minipipe.pl

afca912

finished tool script to deface and register defaced images in LORIS

86680ab

fixed use of unitialized value in File.pm and MRI.pm when running the…

c23a93d

… script

cmadjar added New Feature Needs Work Before Merging [branch] minor labels Dec 14, 2018

nicolasbrossard requested changes Dec 17, 2018

View reviewed changes

cmadjar mentioned this pull request Jan 4, 2019

[Configuration] Adding configuration fields needed for imaging defacing tool aces/Loris#4232

Merged

2 tasks

cmadjar removed the Needs Work Before Merging label Jan 4, 2019

cmadjar added 2 commits January 4, 2019 12:19

updated comments on top of constant variables of the tool script

0463e0f

Nicolas' feedback on deface_minipipe.pl

6353243

cmadjar commented Jan 4, 2019

View reviewed changes

nicolasbrossard requested changes Jan 7, 2019

View reviewed changes

nicolasbrossard requested changes Jan 8, 2019

View reviewed changes

Nicolas' feedback

3943c40

cmadjar commented Jan 10, 2019

View reviewed changes

PapillonMcGill reviewed Jan 14, 2019

View reviewed changes

tools/run_defacing_script.pl Outdated Show resolved Hide resolved

tools/run_defacing_script.pl Outdated Show resolved Hide resolved

tools/run_defacing_script.pl Outdated Show resolved Hide resolved

cmadjar commented Jan 14, 2019

View reviewed changes

tools/run_defacing_script.pl Outdated Show resolved Hide resolved

tools/run_defacing_script.pl Outdated Show resolved Hide resolved

tools/run_defacing_script.pl Outdated Show resolved Hide resolved

Mélanie's comment and added the MD file for the new tool in the docs/…

4b83fb6

…scripts_md directory

PapillonMcGill reviewed Jan 15, 2019

View reviewed changes

docs/scripts_md/run_defacing_script.md Outdated Show resolved Hide resolved

docs/scripts_md/run_defacing_script.md Outdated Show resolved Hide resolved

docs/scripts_md/run_defacing_script.md Outdated Show resolved Hide resolved

Melanie's feedback

61295ee

cmadjar commented Jan 15, 2019

View reviewed changes

docs/scripts_md/run_defacing_script.md Outdated Show resolved Hide resolved

docs/scripts_md/run_defacing_script.md Outdated Show resolved Hide resolved

christinerogers added the Add to release notes label Jan 18, 2019

christinerogers added the Documentation label Jan 18, 2019

cmadjar assigned nicolasbrossard Jan 18, 2019

cmadjar added the Priority high - my LORIS friend got merged! label Feb 6, 2019

cmadjar added 2 commits February 6, 2019 16:57

modified deface_minipipe.pl so that by default it uses the t1 model

4b28b43

added the mni models and beast library to the README in the requireme…

70fef00

…nts for defacing scripts

PapillonMcGill reviewed Feb 11, 2019

View reviewed changes

README.md Outdated Show resolved Hide resolved

Removed version from the bic-mni-models and beast-library packages in…

bbec09f

… the README.md

cmadjar added this to the 20.3 milestone Feb 14, 2019

nicolasbrossard reviewed Feb 19, 2019

View reviewed changes

great catch from Nicolas :)

838c04b

nicolasbrossard approved these changes Feb 19, 2019

View reviewed changes

cmadjar merged commit 2bb7def into aces:minor Feb 19, 2019

cmadjar deleted the addition_of_defacing_tool branch February 19, 2019 20:47

cmadjar added the Caveat for Existing Projects label May 23, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Addition of a LORIS tool to deface structural images and register the defaced images back into LORIS #366

Addition of a LORIS tool to deface structural images and register the defaced images back into LORIS #366

cmadjar commented Dec 14, 2018 •

edited

Loading

nicolasbrossard Dec 17, 2018

cmadjar Jan 4, 2019

cmadjar left a comment

cmadjar Jan 4, 2019

cmadjar left a comment

cmadjar left a comment

cmadjar left a comment

PapillonMcGill commented Jan 28, 2019

PapillonMcGill commented Feb 12, 2019

cmadjar commented Feb 14, 2019

nicolasbrossard Feb 19, 2019 •

edited

Loading

cmadjar Feb 19, 2019

nicolasbrossard left a comment •

edited

Loading

Addition of a LORIS tool to deface structural images and register the defaced images back into LORIS #366

Addition of a LORIS tool to deface structural images and register the defaced images back into LORIS #366

Conversation

cmadjar commented Dec 14, 2018 • edited Loading

Description

How to use the tool

Special notes for multi-contrast acquisitions:

Notes for existing projects

See also

nicolasbrossard Dec 17, 2018

Choose a reason for hiding this comment

cmadjar Jan 4, 2019

Choose a reason for hiding this comment

cmadjar left a comment

Choose a reason for hiding this comment

cmadjar Jan 4, 2019

Choose a reason for hiding this comment

cmadjar left a comment

Choose a reason for hiding this comment

cmadjar left a comment

Choose a reason for hiding this comment

cmadjar left a comment

Choose a reason for hiding this comment

PapillonMcGill commented Jan 28, 2019

PapillonMcGill commented Feb 12, 2019

cmadjar commented Feb 14, 2019

nicolasbrossard Feb 19, 2019 • edited Loading

Choose a reason for hiding this comment

cmadjar Feb 19, 2019

Choose a reason for hiding this comment

nicolasbrossard left a comment • edited Loading

Choose a reason for hiding this comment

cmadjar commented Dec 14, 2018 •

edited

Loading

nicolasbrossard Feb 19, 2019 •

edited

Loading

nicolasbrossard left a comment •

edited

Loading