`tbss_skeleton` requires -s option when the target args.skeleton is given

[kcho]

tbss_skeleton requires -s option in order to project onto the given skeleton_mask

Currently in the project_skeleton.py does not support this. It would be nice to have another logic that catches args.skeleton_mask in running tbss_skeleton. (We need this for --ENIGMA)

Look at the figures below-

---

Red : ENIGMA_DTI_FA_skeleton_mask.nii.gz Blue: tbss_skeleton output with -s ENIGMA_DTI_FA_skeleton_mask.nii.gz, which overlaps with ENIGMA_DTI_FA_skeleton_mask.nii.gz Yellow: tbss_skeleton output without -s option, which creates its own skeleton.

[tashrifbillah]

Hi @kcho , can you hyperlink the line you are referring to?

[kcho]

https://github.com/pnlbwh/TBSS/blob/d4ca7b732f595b52a8901df5c7a90839e80058ec/lib/project_skeleton.py#L46-L62

Here it is!

[tashrifbillah]

I understand now. I am aware that ENIGMA people used -s below:

page 3, step 8

@oferpasternak and I had a discussion about it. We both looked at the source code and vaguely decided to omit the -s option not finding any effect of it on skeleton projection.

However, if you confidently suggest using this option, we shall do it. Let's make sure you have taken Ofer's opinion as well.

[tashrifbillah]

• [x] write custom script to correct existing results
• [x] correct the pipeline for future use
• [x] update reference data for testing and continuous integration

[tashrifbillah]

--enigma branch: templateMask is given args.templateMask = pjoin(enigmaDir, 'ENIGMA_DTI_FA_mask.nii.gz')

--fmrib and --studyTemplate branch: templateMask is not given, rather created in Lines 146-148

args.templateMask= pjoin(statsDir, 'mean_FA_mask.nii.gz')
meanFAmaskData = (meanFAdata > 0) * 1
save_nifti(args.templateMask, meanFAmaskData.astype('uint8'), target.affine, target.header)

So, by the time the pipeline advances to skeleton projection loop, all three branches assign a value to args.templateMask. So, if we are to rewrite tbss_skeleton introducing -s args.templateMask:-

(i) created masks are used for --fmrib and --studyTemplate branches (ii) while given mask is used for --engima branch.

I would like @kcho and @oferpasternak to understand the above and give it a go.

[kcho]

@tashrifbillah @oferpasternak tested above commit for --enigma flag - the skeletons are correctly projected on to that of ENIGMA skeleton.

Should I test without --enigma flag?

[tashrifbillah]

Good catch @kcho , it should be -s args.skeletonMask.

[tashrifbillah]

Putting @oferpasternak's explanation here:

if the -s flag is omitted, TBSS will generate a skeleton from the data rather than using the ENIGMA skeleton. This is okay, but, then when projecting data onto the skeleton it will use the distance function of ENIGMA rather than matching the distance function for the data-generated skeleton (the distance function is generated from the skeleton, it represents the distance of each voxel from the closest skeleton voxel). As a result the skeleton might look okay (it was generated for this data, might look even better than ENIGMA). But, the values projected onto the skeleton will not correspond with the maximal projection. Rerunning with -s is expected to change the skeleton (back to the ENIGMA skeleton), and change the projection of values onto the skeleton. This might be a very slight change, depending how similar the data generated skeleton is with the ENIGMA skeleton.

[tashrifbillah]

See below the difference in ROI statistics between results using -s skeletonMask option and not:

(base) $ python -m unittest -v tests/test_*py

Threshold for precentage relative difference: 2|a-b|/(a+b)*100 is set to 10

Test ENIGMA branch results
Test FMRIB branch results
Test studyTemplate branch results
test_enigma_AD (tests.test_enigma.TestEnigma) ... AD equivalence test
Relative difference:  7.213474787906694
ok
test_enigma_FA (tests.test_enigma.TestEnigma) ... FA equivalence test
Relative difference:  8.753190893398601
ok
test_enigma_MD (tests.test_enigma.TestEnigma) ... MD equivalence test
Relative difference:  6.309328875198945
ok
test_enigma_RD (tests.test_enigma.TestEnigma) ... RD equivalence test
Relative difference:  8.346333530577699
ok
test_fmrib_AD (tests.test_fmrib.TestFmrib) ... AD equivalence test
Relative difference:  6.6382469274880895
ok
test_fmrib_FA (tests.test_fmrib.TestFmrib) ... FA equivalence test
Relative difference:  7.89002497993019
ok
test_fmrib_MD (tests.test_fmrib.TestFmrib) ... MD equivalence test
Relative difference:  6.1419572960898385
ok
test_fmrib_RD (tests.test_fmrib.TestFmrib) ... RD equivalence test
Relative difference:  8.362892025685815
ok
test_study_AD (tests.test_study.TestStudy) ... AD equivalence test
Relative difference:  0.0
ok
test_study_FA (tests.test_study.TestStudy) ... FA equivalence test
Relative difference:  0.0
ok
test_study_MD (tests.test_study.TestStudy) ... MD equivalence test
Relative difference:  0.0
ok
test_study_RD (tests.test_study.TestStudy) ... RD equivalence test
Relative difference:  0.0
ok

----------------------------------------------------------------------
Ran 12 tests in 0.171s

OK

For --studyTemplate branch, the difference is zero since there is no provided mask. On the other hand, for other two branches --enigma and --fmrib, the difference is about 9 percent.

[kcho]

@tashrifbillah Is the FA higher when using --enigma and --fmrib branch compare to that of --studyTemplate?

[kcho]

As ENIGMA team has documented in the TBSS documentation, I also think we have to set args.THRESH = 0.049 when --enigma branch is used.

[kcho]

https://github.com/pnlbwh/TBSS/issues/12#issuecomment-527867146

As ENIGMA team has documented in the TBSS documentation, I also think we have to set args.THRESH = 0.049 when --enigma branch is used.

Actually, it makes no difference in the skeleton output.

DST_map=/data/pnl/soft/pnlpipe3/tbss/data/enigmaDTI/ENIGMA_DTI_FA_skeleton_mask_dst.nii.gz
skel_map=/data/pnl/soft/pnlpipe3/tbss/data/enigmaDTI/ENIGMA_DTI_FA_skeleton_mask.nii.gz
search=/data/pnl/Collaborators/Shanghai_Prodrome/BASELINES/scripts/ENIGMA_SCRIPTS/ENIGMA/LowerCingulum_1mm.nii.gz

tbss_skeleton \
    -i prac \
    -p 0.2 ${DST_map} ${search} prac.nii.gz skel_thresh_0.2.nii.gz \
    -s ${skel_map}

tbss_skeleton \
    -i prac \
    -p 0.049 ${DST_map} ${search} prac.nii.gz skel_thresh_0.049.nii.gz \
    -s ${skel_map}

fslmaths skel_thresh_0.2.nii.gz -sub skel_thresh_0.049.nii.gz diff.nii.gz
fslstats diff.nii.gz -M

above returns 0

[tashrifbillah]

@tashrifbillah Is the FA higher when using --enigma and --fmrib branch compare to that of --studyTemplate?

I don't know, it is not part of my designing. Note that it can be both ways: greater or smaller, since absolute value is taken

[tashrifbillah]

@kcho , do you remember where to find the source code of tbss_skeleton command?

Found it: http://ftp.nmr.mgh.harvard.edu/pub/dist/freesurfer/tutorial_packages/centos6/fsl_507/src/tbss/tbss_skeleton.cc

[oferpasternak]

It's also part of the source code within the FSL package. In my old version of fsl it is under: ./src/tbss/tbss_skeleton.cc

[tashrifbillah]

Thank you Ofer, I created this gist for better legibility already:

https://gist.github.com/tashrifbillah/7b4c52a7c0c21a7a54b00323b4e76f8c