Documentation: Revisit FBA instructions

[Lestropie]

This is something that has come up repeatedly in discussion, but I've just looked and realised that it's not explicitly listed.

Going to create a checklist as there's a decent amount of separate changes to make. Individual points are however open to debate.

• [ ] Merge two separate single-shell and multi-shell FBA instruction documents into one. While having two separate documents is more copy-paste-able, people are often curious about the differences between them, and it's not obvious, given that the content is almost identical. Emerging consensus is that it would be better to have a single document, with bright lights indicating where decisions may need to be made depending on the number of unique b-values present in the input data.

• [ ] More verbose discussion of "AFD" vs. "FD". Relates to #2299. That nuance may not require a whole page in its own right, but perhaps at the point at which the "-afd" command-line option is used to generate a file called "fd.mif", it could do with a paragraph explaining the distinction.

• [ ] Modifications of tracking / SIFT usage Combination of #1704 and #2273. Opportunity to combine dynamic rather than homogeneous WM seeding, and SIFT2 rather than (/ in addition to?) SIFT, for calculation of the fixel-fixel connectivity matrix. Lazy solution is to just generate 2M with dynamic seeding and then run SIFT2 and fixelconnectivity -tck_weights_in.

• [ ] Multi-contrast template I've mucked around with this a little myself with a current experiment. Not sure if there is any kind of consensus around what's best to do. @maxpietsch Care to chime in? Another little trick that can be used here in concert with the previous point is to use a three-tissue template to derive appropriate model weights for the SIFT model, down-regulating the influence of template voxels with partial volume. Not sure how much effect it has, but it can be done.

• [ ] fixelcorrespondence When the new fixelcorrespondence comes (discussion on data format in #2200; abstract here but no PR yet), this will require multiple changes:

  • [ ] Different utilisation even to achieve the same outcomes as the current code (two commands instead of one);
  • [ ] Decide whether to advocate for using one of the more advanced correspondence techniques over the legacy technique;
  • [ ] Include optional details for propagating additional correspondence information for later use as regressors.

• [ ] NaN masking There is currently a separate page here describing which steps to modify and how in the scenario where brain coverage is a problem and one wants to perform subject-wise fixel-wise exclusion from the statistical model. If the FBA instructions document is modified to follow a more choose-your-own-flavour philosophy, then possibly this should be merged into the one document also.

• [ ] Fixel "masking" This comes in two points:

  • [ ] Do not refer to the template fixel dataset as a fixel "mask". The term "fixel mask" should refer specifically to a fixel data file of boolean data type.
  • [ ] Advocate for the explicit derivation of an analysis fixel mask. Subsequently to FOD segmentation, which is performed with some peak amplitude threshold, one can use other information to determine which fixels should be included in an analysis. This could be based on factors such as integral, peak amplitude (with a higher threshold than what was used for segmentation), streamline count, fixel-fixel connection count, fixel-fixel connectivity extent, consistency of fixel correspondence, number of subjects with valid data.

[Lestropie]

• [ ] Do not use separate directories for different metrics The set of fixels is exactly the same. The fixel map is therefore just being duplicated. I believe that the justification for this was that for the input text file where the list of input images is specified, the same file could be used for each of the FD / FC / FDC metrics; but if my recommendation is going to be to not test all of those different metrics, that becomes obsolete.

[Lestropie]

• [ ] Refer to the intersection of all masks transformed to template space as "the intersection mask" rather than "the template mask", given that there may be multiple subsequent revisions to masks used for data processing / statistical inference.

• [ ] Suggest voxel mask refinement prior to fixel segmentation using:

  • [ ] Manual exclusion
  • [ ] Threshold on multi-tissue decomposition
  • [ ] Erosion

• [ ] Contemplate default value / description of heuristic revision of FMLS lobe merge ratio

• [ ] Suggest voxel mask refinement subsequent to fixel segmentation using:

  • [ ] Fixel count
  • [ ] "Complexity" measure (double-check this; didn't seem to be giving expected results)

• [ ] Tractography: Use refined voxel mask as seeding / propagation mask

• [ ] Fixel-fixel connectivity matrix construction:

  • [ ] Use refined voxel mask
  • [ ] Export count & extent per fixel
  • [ ] Refine fixel analysis mask to exclude fixels with inadequate streamlines-based connectivity

• [ ] Fixel data smoothing:

  • [ ] Constrain based on refined fixel mask
  • [ ] Consider explicitly zeroing all fixel data outside that mask if it reduces overall confusion

• [ ] Add page on omnibus -> post hoc testing

[Lestropie]

• [ ] Move those steps that can be considered "DWI pre-processing" into a separate standalone file in the "DWI pre-processing" section.