Tractography pipeline (tckgen)

[sina-mansour]

Following on the suggestion by @Lestropie (this commit):

RS:

• Default FOD amplitude cutoff is a compromise knowing that users could be providing either single-tissue or multi-tissue WM ODFs. Given the use of multi-tissue CSD here, as well as the use of ACT (or comparable masks), probably safe to reduce this to 0.05 (note that if ACT is used, the default FOD cutoff is automatically cut in half, in which case there would be no need to use the command-line option)
• The output of 5tt2gmwmi is generally intended to be used in conjunction with -seed_gmwmi. Providing that image via -seed_image will result in a large proportion of candidate seeds being rejected due to being in cortical GM in the case of ACT or outside of the mask image in the case of not using ACT. You should see if using -seed_gmwmi that the discrepancy between seed count and streamline count should decrease.
• If quantification of Fibre Bundle Capacity (FBC) is a priority, then I would usually advocate the use of -seed_dynamic. This would however incur the cost of FOD segmentation (which is additionally performed within SIFT(2); preferable would be to do that segmentation once and then load those pre-computed results in both instances), and it would potentially confound the interpretation of raw streamline count measures (there is some sense of known biases present in such for both homogeneous WM and GM-WM interface seeding, whereas for dynamic seeding the raw streamline count becomes slightly more comparable to FBC).
• -nthreads 1 will actually result in the use of 2 threads here: there is one dedicated thread for writing to the track file, and you are requesting one worker thread for doing the tracking itself. If you genuinely do not want the command to spawn any threads at all, use -nthreads 0. (This will also remove the need for locking as generated streamline data are passed from one thread to another)
• -trials isn't something that would typically be modified
• The other option to consider is -power. One of the reasons why iFOD2 remains unpublished is because we still don't have a robust answer for what this should be. But over and above that, even within the logic that was used to derive the current default value, there is still an error. The default is (1 / samples), whereas it should actually be (1 / (samples-1)). I would suggest running with -power 0.333333 and see if it changes execution speed substantially; it will slightly reduce the magnitude of the probabilistic "wiggle".
• In addition to testing execution speed between iFOD1 and iFOD2, you could also try iFOD2 with -samples 3 (and possibly also then with -power 0.5 as per point above), and see the extent to which that improves execution speed.
• Ideally I would like to have this algorithm: https://github.com/MRtrix3/mrtrix3/issues/2160 However I do believe that it runs slower than iFOD2. I'm not sure that I'll be able to find the time to implement it, but it's a great little project for e.g. a Masters internship in CompSci.
• For now, run with -info to get additional statistics on tractography outcomes (and this will be further augmented if ACT is used). In the future, rather than attempting to parse the stderr output here, I could add a command-line option to tckgen that would write these statistics to a file for easier access.
• Theoretically, you could do a combination of GM-WM interface seeding and homogeneous WM seeding. You could then have connectomes with half the streamline count using data from each individually, and connectomes using the concatenation of the two tractograms, which would potentially somewhat mitigate the biases present in each. FBC quantification would use the concatenation of the two. But this may be exposing a feature of the reconstruction pipeline that we explicitly don't want to explore?
• Still discussion to be had RE: requesting specific number of seeds vs. streamlines vs. selected streamlines https://github.com/MRtrix3/mrtrix3/issues/2391

[sina-mansour]

This issue thread can be used to discuss further tractography details. In the meanwhile, these are the points that I'll be implementing/testing to tune the tckgen command:

• I'll try adding the ACT option with the default FOD, which should result in a 0.05 cutoff
• I'll replace the seed with the -seed_gmwmi option
• For the sake of providing all various measures over the same generated tractograms and avoiding potential confounding of the raw streamline count measure, may be it would be better not to implement dynamic seeding. Nevertheless, I'll add relevant scripts to assign weighted contribution to each streamline (SIFT2) and also provide connectivity matrices which are weighted accordingly.
• To be added: replace the threading option to -nthreads 0 to ensure single threaded computations.
• To be tested: explicitly add the power option and investigate its impact on runtime: ( -power 0.333333)
• To be tested: changing samples to 3 (and power to 2) to test it's impact
• To be added: -info option for verbosity

[sina-mansour]

ACT and seeding from GM WM boundary added in: https://github.com/sina-mansour/UKB-connectomics/commit/cd21448d47189b085fe20860ed18d92141b0d691

This slightly increased runtime (for 100K streamlines, before act: ~40sec, after act: ~70sec)

[sina-mansour]

IFOD2 with -power 0.333333 and default samples took ~85sec

IFOD2 with -power 0.5 and -samples 3 took ~65sec

Hence the latter was included: https://github.com/sina-mansour/UKB-connectomics/commit/b908cf0effba8aaacc1f1c16c83bcf3757c099d8

verbosity was also added.