[ENH] bvec robustness

[mattcieslak]

As mentioned in #592 the bvec handling is terrifying and needs to be clearly communicated to the user.

I've been hesitant to add something to qsiprep that will flip bvecs on the fly for a couple reasons. The methods for auto-flipping depend on having good quality data. It's possible (though unlikely) that correct bvecs from BIDS could be flipped by qsiprep and this something I'd really like to avoid. The second is that if we flip the bvecs in qsiprep, the user's BIDS will still have the incorrect bvecs.

So the plan we came up with is for a workflow like

1. The user uses the bvecs that they got from dicom conversion
2. At the end of qsiprep dwigradcheck and dsi studio's bvec checker are run on the data
3. If alternate bvecs are suggested (i.e. a flip is detected): a. A huge warning is added to the html report describing the problem b. A warning message is printed with instructions on how to correct the problem in BIDS

The user will be directed to an executable that's something like qsiprep-correct-bvecs that will produce a .bvec file that can be added to the BIDS directory. Then the user will have to re-run qsiprep with the updated BIDS to see if the error goes away.

Would be interested to hear comments/suggestions @arokem @smeisler @araikes

[araikes]

A couple of very cursory thoughts because of my work with rodent data and the fact that it is probably the most extreme version of the weird outcomes you could get w.r.t. image-bvec discordance:

1. dwigradcheck gives output in two forms, scanner basis and image basis. Depending on the image, these may not agree with each other. If you enforce the export_grad_fsl, then I'm pretty sure it writes the bvec/bval files that correspond to the highest "image basis" output in the table. Speaking from experience with rodents, this doesn't always mean that the vectors are oriented correctly.

2. The same is true with DSI Studio's bvec checker. Plus, IIRC, DSI Studio doesn't use FSL standard bvecs but applies a flip in one of the directions by default (y, I think). That may have changed at some point, but that's my memory.

3. Given that the biggest time sink in the preprocessing is eddy (at least for my data), and given that eddy is the first step where the bvecs have the potential for substantive modification, I think I'd rather know on the front end if I need to address a problem rather than sinking in a bunch of time only to find out I have to reprocess things.

4. Just to throw in an additional option, scilpy has a version of the Schilling bvec checking approach that DSI Studio uses (https://scilpy.readthedocs.io/en/latest/scripts/scil_validate_and_correct_bvecs.html) but functions in a DIPY friendly framework, which would be closer to FSL compatibility. The downside is it outputs the corrected bvec file but doesn't necessarily report whether flipping/swapping was required. This one has actually done the best job of dealing with the flips/swaps needed for my rodent data.

From a performance standpoint, it may be more beneficial to something like:

1. Denoise, unring, generate a rough mask and run bvec checking from multiple sources
2. Determine a consensus "Do your bvecs have an issue" outcome. If no issue is detected (all/majority of sources return "All good"), then proceed as normal. Otherwise ....
3. Generate an HTML visualization of the vector orientations from the original bvecs and the corrected bvecs
4. Ask the user to assess
5. Rerun with a --correct_bvecs or --dont_correct_bvecs flag (where the default is --check-bvecs)

[smeisler]

Can these bvec checkers be meaningfully used on raw data? The dwigradcheck paper uses raw data, if I am not mistaken. If so, the easiest route might just be to make a section of documentation about checking bvecs with code examples. This gives a little more agency to the user rather than having QSIPrep possibly make a mistake in its correction, and encourages the user to explore their data before processing. It is also less coding :)

[mattcieslak]

@araikes DSI Studio recently started using the FSL default bvec format, so at least that won't be an issue.

@smeisler I agree, documentation may be the best place to address this issue

Also pinging @cookpa

[araikes]

I'll state for the record that I agree with @smeisler in reducing complexity and putting more agency on the user to validate their vector files. My suggestions were motivated from the perspective of "what could the software do in this respect."