search

brainlife / app-testflip

This app will quickly check the dwi image to see if any bvecs directions needs to be flipped. The algorithm finds bvecs that are pointing toward certain direction and find the volume slice within 4D DWI data and see how many image slices indeed seems to contain features that are orthogonal to the bvecs directions. Inconclusive output from this App usually means you have some data quality issue with your dwi.
1 stars 0 forks source link
qa

readme

Abcdspec-compliant Run on Brainlife.io

Algorithm to detect bvecs flipping

Incorrect bvecs polarity would lead to incorrect processing of DWI data. This app will quickly check the dwi image to see if any bvecs directions needs to be flipped. The algorithm find bvecs that are pointing toward certain direction and find the volume slice within 4D DWI data and see if the image indeed seems to contain features that are orthogonal to the bvecs directions.

An example of y-flipped image

[flip]

This App uses a simple algorithm to analyze directionality of the diffusion signals for each slices and determies if the image appears to have correct bvecs orientation overall. A detailed description of this algorithm is currently in the works.

By "correct" orientation, this algorithm uses the following FSL definitions for bvecs.

https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/FAQ#What_conventions_do_the_bvecs_use.3F

Authors

Project directors

Funding

NSF-BCS-1734853 NSF-BCS-1636893

Running the App

On Brainlife.io

You can submit this App online at https://doi.org/10.25663/bl.app.85 via the "Execute" tab.

Running Locally (on your machine)

  1. git clone this repo.
  2. Inside the cloned directory, create config.json with something like the following content with paths to your input files.
{
    "dwi": "./input/dwi/dwi.nii.gz",
    "bvecs": "./input/dwi/dwi.bvecs",
    "bvals": "./input/dwi/dwi.bvals"
}
  1. Launch the App by executing main
./main

Sample Datasets

If you don't have your own input file, you can download sample datasets from Brainlife.io, or you can use Brainlife CLI.

npm install -g brainlife
bl login
mkdir input
bl dataset download 5a050a00eec2b300611abff3 && mv 5a050a00eec2b300611abff3 input/dwi

Output

The App will create a file product.json on the current working directory. This file contains following information.

{
    "brainlife": [
        {
            "msg": "bvecs directions look good!",
            "type": "info"
        },
    ],
    "dwi_affine_determinant": -7.999999999999998,
    "storage_orientation": "radiological"
}

The product.json also contains plotly graph data so you can ploy them using ploytly or other similar libraries.

Example of output from high SNR image

plot

This plot shows that most slices has very low evidence of no flip.

Example of output from low SNR / low quality image.

plot

This plot shows that the image does not seem to be flipped, however, X/Y and Y/Z are close to being inconclusive. The image might be blurry, or has low SNR.

Example of output from y-flipped image.

plot

This plot shows that x/y, y/z are flipped. Since the common axis on x/y and y/z are y, we conclude that y axis is flipped in bvecs. However the flip evidence is close to inconclusiv. The image might be blurry, or has low SNR.

Other Outputs

This App also generates plotly graphs showing the arrangements of gradient vectors.

gradients

Dependencies

This App only requires singularity to run. If you don't have singularity, you will need to install following dependencies.