difit 1.0
Diffusion weighted models fitting
License: MIT

.. image:: ../logo.png
    :width: 400
    :align: center
    :alt: ReadTheDocs
    :target: https://difit.readthedocs.io/en/stable/

*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 <https://dipy.org/>`_. Nodes were built using `nipype <https://nipype.readthedocs.io/en/latest/>`_. 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 <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.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.