cuDIMOT
CUDA Diffusion Modelling Toolbox

How to fit a model using cuDIMOT:

Once a model is compiled, binaries files and a main script are generated in $FSLDEVDIR/bin.

For calling the main script that fits your model you can use:

$FSLDEVDIR/bin/cudimot_(MODELNAME).sh   subject_directory   [options]

You can create your own script (using any language) and call the model binaries.

You can concatenate the output of a fitting process with the input of other fitting process using different models.

You can use multi GPUs to fit a dataset.


Create my own script to fit a model

Fitting options of the toolbox

Concatenating models

Specifying Fixed Parameters

Fixing Parameters on the fly

Specifying the grid for Grid Search


Create my own script to fit a model

For fitting a model you need to call three binaries:

  • split_parts_$modelname. This binary split the dataset into smaller parts.
  • $modelname. This binary performs the fit.
  • merge_parts_$modelname. This binary merge the output from the different parts.

You can use as refence the main script created by CUDIMOT


Fitting options of the toolbox

Compulsory arguments:

--data Data file with measurements
--maskfile Mask file
--subjdir Subject directory
--partsdir Directory where different parts of the data/results will be stored
--outputdir Directory where to write the output file
--idPart Number of the part of the dataset to process [0..N-1]
--nParts Total number of parts of the dataset [1..N]

Optional arguments:

-h, --help Display the options of the toolbox
--ld, --logdir Log directory (default is logdir)
--forcedir Use the actual directory name given - i.e. don't add + to make a new directory
--nj, --njumps Num of jumps to be made by MCMC (default is 1250)
--bi, --burnin Total num of jumps at start of MCMC to be discarded (default is 1000)
--se, --sampleevery Num of jumps between each sample (MCMC) (default is 25)
--upe, --updateproposalevery Num of jumps for each update to the proposal density std (MCMC) (default is 40)
--no_updateproposal Do not update the proposal density std during the recording step of MCMC
--seed Seed for pseudo random number generator
--gridSearch Run gridSearch algorithm using the values specified in a file
--runMCMC Run MCMC algorithm and get distribution of estimates
--no_LevMar Do not run Levenberg-Marquardt algorithmRun MCMC algorithm and get distribution of estimates
--no_Marquardt Do not use Marquardt contribution in Levenberg algorithm
--iterLevMar Maximum number of iterations in Levenberg(-Marquardt) algorithm (default is 200)
--rician Use Rician noise modelling in MCMC
--keepTmp Do not remove the temporal directory created for storing the data/results parts
--getPredictedSignal Save the predicted signal by the model at the end
--CFP File with a list of ASCCI files for specifying the common (to all voxels) fixed parameters of the model
--FixP File with a list of NIfTI files for specifying the fixed parameters of the model
--fixed List of the Ids of the fixed parameters separated by commas. For example: --fixed=2,4
--init_params File with a list of NIfTI files for the initialization of the model parameters
--debug Specify a voxel for debugging. Some variables at certain steps of the algorithms will be printed (use few iterations)
--BIC_AIC Calculate Bayesian and Akaike Information Criteria at the end

Concatenating models

The toolbox offers the possibility of initialising the model parameters with some given values. You can use values estimated in other models.

The user can provide a NIfTI volume for each parameter of the model. The volumes must have the same dimensions as the input dataset.

The path to the NIfTI volumes needs to be specified in a text file passed as argument using the option --init_params.

The text file must contain a line for each model parameter, but a line can be empty if that parameter does not need to be initialised.

For instance, for initialising the first and third parameter of model-2 with the first and second parameters estimated in model-1:

model2 --init_params=File.txt
and File.txt containing a line for each model-2 parameter:
Initialisation

Specifying Fixed Parameters

Common Fixed Parameters, such as bvals and bvecs, and Fixed Parameters, such as T1 or S0, are specified with a list of paths to the files containing the values of these parameters.

Common Fixed Parameters files must be ASCII files and Fixed Parameters must be NIfTI volumes with the same size in the first three dimensions as the input dataset.

The paths to the ASCII Common Fixed Parameters files must be specified in a text file passed as argument using the option --CFP.

The paths to the NIfTI Fixed Parameters files must be specified in a text file passed as argument using the option --FixP.

The text files must contain a line for each Common Fixed Parameter or each Fixed Parameter.

For instance, in a model with bvals and bvecs as Common Fixed Parameters and S0 as Fixed Parameter:

model --CFP=CommonFixed_params.txt --FixP=Fixed_params.txt
CommonFixed_params.txt containing:
CFP
And Fixed_params.txt containing:
FixP

Fixing Parameters on the fly

It is possible to indicate that some of the estimated parameters of the model do not change during the fitting.

To do that, you can use the option --fixed.


Specifying the grid for Grid Search

If Grid Search is used, the combination of values for defining the grid must be specified in a file using the option --gridSearch and using the format:

search[Num_parameter]: [Value0, ..., ValueN]

For instance, if we want to define the grid with different values for the first three parameters of a model:

model --gridSearch=Grid.txt
and Grid.txt containing:
GridSearch

The toolbox will try all the combinations of these parameter values.