difit 1.0

Diffusion weighted models fitting

difit: A diffusion MRI models fitting software

difit is being developed as an attempt to bring in major diffusion models into one place (v1.0.0 can do DTI and DKI models). difit allows to choose b-values and b0-images from multi-shell data as the user desires. This enable the user to test different combinations easily without splitting data prior to the model fitting.

Major software packages in the background

difit’s versions of DTI and DKI models come from dipy. Nodes were built using nipype. Other dependancies are listed in the setup.cfg file.

Installation

pip install difit

Models fitting command

DTI

python -m difit 'path/to/input/dir' 'path/to/output/dir' 'path/to/work/dir' --models dti --dti_b_values 1000 --dti_b0_images 3 --mem 6 --nprocs 2

DKI

python -m difit 'path/to/input/dir' 'path/to/output/dir' 'path/to/work/dir' --models dki --dki_b_values 500 1000 3000 --dki_b0_images 4 --mem 9 --nprocs 2

Both DTI and DKI

It is possible to fit more than one model in one run. DTI followed by DKI will be fitted with the below command.

python -m difit 'path/to/input/dir' 'path/to/output/dir' 'path/to/work/dir' --models dti dki --dki_b_values 500 1000 2000 --dki_b0_images 3 --dti_b_values 1000 --dti_b0_images 3 --mem 12 --nprocs 2

Parallel Processing

difit can fit multiple subjects in parallel. If you have more than one subject, you can issue the command similar to below with the wildcard (*). If you want to fit few of the available subjects, you can use the curly bracket notaions to specify the subjects.

python -m difit 'path/to/input/sub*/data' 'path/to/output/sub*/out' 'path/to/work/dir' --models dti dki --dki_b_values 500 1000 2000 --dki_b0_images 3 --dti_b_values 1000 --dti_b0_images 3 --mem 32 --nprocs 8

Input dwi data files

difit searches for files ending with *_dwi.nii.gz, *_dwi.bval, *_dwi.bvec and *_mask.nii.gz in the input directory. Make sure to name your files with the same endings. If you use qsiprep to preprocess data, you will end up with the above format which uses BIDS convention. If you used a different software to preprocess your data, name your files to match the above convention. The * indicate any name/s before the underscore can take place.

An example for multi models and multi subjects parallel processing

Assume there are two subject directories namely sub01 and sub02 and in each directory there are data and out directories available. In this example, diffusion data have four shells (500,1000,2000,3000) and 6 b0 images. But we are going to use only one shell for DTI and three shells for DKI model. The both models will use 3 b0 images (consecutive).

projectdifit
   ├── sub01
   │   ├── data
   │   │   ├── example_dwi.bval
   │   │   ├── example_dwi.bvec
   │   │   ├── example_dwi.nii.gz
   │   │   └── example_mask.nii.gz
   │   └── out
   ├── sub02
   │   ├── data
   │   │   ├── example_dwi.bval
   │   │   ├── example_dwi.bvec
   │   │   ├── example_dwi.nii.gz
   │   │   └── example_mask.nii.gz
   │   └── out
   └── work

python -m difit '/projectdifit/sub*/data' '/projectdifit/sub*/out' '/projectdifit/work' --models dti dki --dki_b_values 500 1000 2000 --dki_b0_images 3 --dti_b_values 1000 --dti_b0_images 3 --mem 32 --nprocs 8

Output files

out
├── dki
│   ├── AK.nii.gz
│   ├── dki_AD_mosaic.png
│   ├── dki_AD.nii.gz
│   ├── dki_AK_mosaic.png
│   ├── dki_FA_mosaic.png
│   ├── dki_FA.nii.gz
│   ├── dki_kFA_mosaic.png
│   ├── dki_MD_mosaic.png
│   ├── dki_MD.nii.gz
│   ├── dki_MK_mosaic.png
│   ├── dki_RD_mosaic.png
│   ├── dki_RD.nii.gz
│   ├── dki_RK_mosaic.png
│   ├── dki_summary_plots.html
│   ├── kFA.nii.gz
│   ├── MK.nii.gz
│   └── RK.nii.gz
└── dti
    ├── dti_AD_mosaic.png
    ├── dti_AD.nii.gz
    ├── dti_FA_mosaic.png
    ├── dti_FA.nii.gz
    ├── dti_MD_mosaic.png
    ├── dti_MD.nii.gz
    ├── dti_RD_mosaic.png
    ├── dti_RD.nii.gz
    └── dti_summary_plots.html

difit creates dti and dki directories in the out directory to store the above output files for each subject.

HELP

python -m difit -h

 dmri models fitter work flow

 positional arguments:
   input_dir             Input data directory. This directory must contain *_dwi.nii.gz, *_mask.nii.gz, *_dwi.bval,
                     *_dwi.bvec. Multiple subjects can be list with wild cards e.g. ~/data/sub_*/data ; each
                     subject directory contain its own set of diffusion files.

   output_dir            The output directory for models metrices. In this directory seperate subdirectories will be
                     created for each model; For multiple subjects, output can be given with a wildcard e.g.
                     ~/data/sub_*/out

   work_dir              directory for intermediate results

optional arguments:
   -h, --help            show this help message and exit
   --models MODELS [MODELS ...]
                     Choose the model or models you want to fit to your data. Choose one or a combination from dti,
                     dki (default: None)

Options for choosing shell numbers for DTI processing:
   --dti_b_values DTI_B_VALUES [DTI_B_VALUES ...]
                     Choose a b-value/s of multishell data to use for DTI model fitting (default: None)
   --dti_b0_images DTI_B0_IMAGES
                     If dwi data contain more than one b0 images, choose how many you want to use for DTI model
                     fitting (default: 1)

Options for choosing shell numbers and b0 images for DKI processing:
   --dki_b_values DKI_B_VALUES [DKI_B_VALUES ...]
                     Choose a b-values of multishell data to use for DKI model fitting (default: None)
   --dki_b0_images DKI_B0_IMAGES
                     If dwi data contain more than one b0 images, choose how many you want to use for DKI model
                     fitting (default: 1)

Options to specify computer resources:
   --nprocs NPROCS       maximum number of cpus across all processes (default: None)
   --omp-nthreads OMP_NTHREADS
                     maximum number of threads per-process (default: None)
   --mem MEMORY_GB       upper bound memory limit (GB) for difit models fitting (default: None)
   --use-plugin FILE     nipype plugin configuration file (default: None)

Future Additions

MSMT-CSD particle filtering tractography, NODDI and FSL PROBTRACKX.

Note

This project has been set up using PyScaffold 4.1. For details and usage information on PyScaffold see https://pyscaffold.