search

NIRALUser / DTIPlayground

An integrated framework for DWI Image QC and processing
MIT License
12 stars 2 forks source link

readme

DTI Playground

DTI Playground is python based NIRAL pipeline software including DMRIPrep (dmriprep), DMRIAtlas (dmriatlas)

Documentation

For detailed information about installation and usage, please go here: Documentation

Prerequisite

Python3.8 or conda environment is required

User needs to set path of python2 like below

e.g.

$ ln -s /usr/bin/python2.7 /usr/bin/python2

Using PIP

Python 3.8.6 or above is required (Python 3.8.6 ~ 3.9.x preferred)

$ pip install dtiplayground
$ dmriplaygroundlab

For the legacy native application

$ pip install dtiplayground-native

It will automatically install dtiplayground module as well if there is no pre installed dtiplayground

Using Conda

Create the environment

$ conda create -n dtienv-py38 python=3.8
$ conda activate dtienv-py38
$ pip install --upgrade dtiplayground
$ dmriplaygroundlab

Using Docker

$ docker pull niraluser/dtiplayground

Current docker image contains all the necessary tools (FSL/DTIPlaygroundTools) and configurations initialized. To use the container, either run bash or use as below :

$ docker run -it --rm --user $(id -u):$(id -g) -e HOME=$HOME -v $HOME:$HOME -v <WORKINGDIR>:<WORKINGDIR> niraluser/dtiplayground

It will launch DTIPlaygroundLab, open the link in a browser after execution.

Install Tools (FSL/DTIPlaygroundTools)

For admins who want users to use same FSL/dtiplayground-tools preinstalled in the network, use environment variables

Then each user will be asked to use those tools when he/she initialize (or first time use) the software

$ dmriplayround install-tools

Default output directory is $HOME/.niral-dti/ if output directory option is omitted

Once installed, $HOME/.niral-dti/global_variables.yml will have information of the tools including root path of the packages, and automatically changes software paths for the current version of dmriprep unless --install-only option is present.

NOTE If installation falied, remove $HOME/.niral-dti directory and reinstall or re-init dmriplayround by $dmriplayground init

DMRIPrep (dmriprep)

dmriprep is a tool that performs quality control over diffusion weighted images. Quality control is very essential preprocess in DTI research, in which the bad gradients with artifacts are to be excluded or corrected by using various computational methods. The software and library provides a module based package with which users can make his own QC pipeline as well as new pipeline modules.

About the Preprocessing part : README about Preprocessing

GUI Mode:

Use web UI:

$ dmriplaygroundlab

From the menu, go to DMRIPrep application

To use the legacy native UI (Mac/Linux), 

$ pip install dtiplayground-native

When a user run dmriprep-ui first time, it automatically initializes.

$ dmriprep-ui

CLI Mode (Mac/Linux/Windows-WSL):

FSL/DTIPlaygroundTools required

For windows users, install WSL2 and linux packages with python >=3.8.6.

  1. init - Initialize configuration (default: $HOME/.niral-dti/dmriprep-<version>)

init command generates the configuration directory and files with following command. One just needs to execute this command only once unless a different configuration is needed. If you want to reset the initial configuration directory, you can run init again.

    $ dmriprep init

If you want to set different directory other than default one :

    $ dmriprep --config-dir my/config/dir init

Once run, config.yml and environment.yml will be in the directory.

You can manually specify the tool directory (which is generated by install-tools command) by --tools-dir option.

    $ dmriprep init --tools-dir <path/to/tool_dir>

  1. update - Update if config.yml has been changed (e.g. in case of adding user module directory). Changing config.yml file should be followed by updating environment.yml with running update command :

    $ dmriprep [--config-dir my/config/dir] update

    This will update module-specific informations such as binary locations or package location used by the corresponding module. It simply updates environment.yml

  2. make-protocols - Generating a default protocol file

The first thing to do QC is to generate default protocol file that has pipeline information.

    $ dmriprep [base options] make-protocols -i IMAGE_FILENAME [-o OUTPUT_FILENAME_] [-d MODULE1 MODULE2 ... ]

if -o option is omitted, the output protocol will be printed on terminal.-d option specifies the list of modules for the QC, with which command will generate the default pipeline and protocols of the sequence. Same module can be used redundantly. If -d option is not specified, the default pipeline will be generated from the file protocol_template.yml . You can change the default pipeline in protocol_template.yml file

  1. run - Run pipeline To run with default protocol generated from protocol_template.yml:
    $ dmriprep [base options] run -i IMAGE_FILES -o OUTPUT_DIR -d [ MODULE1 MODULE2 ... ]

-d option (default protocol) works as described in make-protocols command. But you need to specify "-d" for the default pipeline from the template. If -o option is omitted, default directory will be set to Image filename_QC. IMAGE_FILES may be a list of files to process. In case of susceptibility correction, IMAGE_FILES needs to have counterparts for the polarities. dmriprep automatically process qc for all the input images before the susceptibility correction stage.

To run with existing protocol file:

    $ dmriprep run -i IMAGE_FILES -p PROTOCOL_FILE -o output/directory/

-p option cannot be used with -d option.

[NOTE] when using 2 image files for SUSCEPTIBILITY_Correct and other multi input modules, order of files can be important. For the SUSCEPTIBILITY_Correct, AP(FH), RL, SI phased file comes first. (e.g. $ dmriprep -i AP_img.nrrd PA_img.nrrd ...)

  1. run-dir Run output directory having protocol file
    $ dmriprep run-dir output/directory

Development of a new module

Adding a module

Once initialized, users can add their custom module from scratch or existing system/user modules by following command

$ dmriprep add-module <module-name> [--base-module <base-module-name>] [--edit]

Following command will generate initial skeletal files of module

$ dmriprep add-module HELLO_World

Then you can test if the module can be loaded properly with

$ dmriprep update

You can use your module right in protocol file.

if -b , --base-module is specified, new model will copy existing code and data from the base module. e.g.

$ dmriprep add-module MYFIRST_Module -b SLICE_Check

MYFIRST_Module will have same codes and data (module definition yaml file) from SLICE_Check module with new classname and filenames.

Developer

Once module is developed and tested in the user module directory, one can just move that directory in dtiplayground/dmri/preprocessing/modules and commit. Make sure the custom module is not existing both in system module directory and user module directory.

Removing user module

User module can be removed by

$ dmriprep remove-module <module-name>

e.g.

$ dmriprep remove-module MYFIRST_Module

NOTE System module cannot be removed by this command. Only user module can be removed.

Modules in other directory

You can just copy module directory to $HOME/.niral-dti/modules/dmriprep and check with $ dmriprep update command. Same applies for removal of user modules.

DMRIAtlas (dmriatlas)

DMRIAtlas is a software to make an atlas from multiple diffusion tensor images. It performs affine/diffeomorphic registrations and finally generates the atlas for all the reference image.

CLI Mode (Mac/Linux/Windows-WSL):

DTIPlaygroundTools required

NIFTI DTI is not supported yet

Usage

The configured directory can be generated from DTIPlaygroundLab (UI)

$ dmriatlas build-dir configured/directory

GUI Mode

In DTIPlaygroundLab, ($ dmriplaygroundlab ) Goto DMRI AtlasBuilder -> configure -> Generate Output Directory or Execute.

Supported Images

Developement

Contributors

Developers
Disucssion/Test

References

Acknowlegements

This software has been supported by the following NIH grants: R01HDO55741, U54HDO79124, R01EB021391, P50HD103573.

LICENSE

MIT

Requirements

Application dependencies

[GENERAL]

[POST INSTALLATION (OPTION)] : below tools can be installed using $ dmriplayground install-tools command

[DTIPlayground]

[DTIPlaygroundNative]

Todos

Change Log

2023-02-23
2022-11-10
2022-10-13
2022-10-08
2022-09-22
2022-09-13
2022-08-19
2022-08-16
2022-08-12
2022-08-11 (0.3.8b4)
2022-08-10 (0.3.8b3)
2022-07-22
2022-07-08
2022-07-06
2022-06-19
2022-06-17
2022-06-07
2022-06-03
2022-01-26
2021-12-10
2021-12-08
2021-11-10
2021-09-02
2021-08-24
2021-08-12
2021-07-15
2021-06-8
2021-05-20
2021-05-14
2021-04-21
2021-04-18
2021-04-15
2021-04-09
2021-04-01