.. image:: ../logo.png
:width: 400
:align: center
:alt: ReadTheDocs
:target: https://difit.readthedocs.io/en/latest/index.htmlReadtheDocs <https://difit.readthedocs.io/en/latest/index.html>_
GitHub <https://github.com/kodiweera/difit>_
Docker Image <https://hub.docker.com/r/diffdocker/difit>_
PYPI <https://pypi.org/project/difit/>_
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 enables the user to test different combinations easily without splitting data prior to the model fitting.
difit's versions of DTI and DKI models come from dipy <https://dipy.org/>. Nodes were built using nipype <https://nipype.readthedocs.io/en/latest/>. Other dependancies are listed in the setup.cfg file.
pip install difit
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
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
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 <https://qsiprep.readthedocs.io/en/latest/installation.html> to preprocess data, you will end up with the above format which uses BIDS <https://bids.neuroimaging.io/> 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.htmldifit creates dti and dki directories in the out directory to store the above output files for each subject.
Download the docker image:
docker pull diffdocker/difit:1.0.0
Run the Docker Image:
The data , out and work directories must be mounted to the host.
For example:
docker run -it --rm -v /home/user/difit:/data -v /home/user/difit/out:/out -v /home/user/difit/work:/work difit:1.0.0 python -m difit '/data' '/out' '/work' --models dti --dti_b_values 1000 --dti_b0_images 3 --mem 6 --nprocs 2
Build a singularity imge from the docker image:
singularity build difit_1.0.0.simg docker://diffdocker/difit:1.0.0
Run the singularity Image (for example):
singularity run --cleanenv difit_1.0.0.simg python -m difit '/data' '/out' '/work' --models dti --dti_b_values 1000 --dti_b0_images 3 --mem 6 --nprocs 2
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 resultsoptional 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.