readme.txt

Multidimensional Diffusion MRI analysis framework (MD-MRI)
----------------------------------------------------------

Authors:
Markus Nilsson
Filip Szczepankiewicz
Björn Lampinen
Daniel Topgaard
Samo Lasic
Carl-Fredrik Westin

This package contains MATLAB files to help researchers analyze multi-
dimensional diffusion MRI data, for example, data acquired with
b-tensors of varying shape. If you find this code useful, please
provide feedback to markus.nilsson@med.lu.se. We appreciate your feedback.

The following MATLAB toolboxes are useful to get the code running properly: 
- Optimization toolbox
- Image Processing toolbox

We envision the following usage scenario. The functions herein support 
step 3 and 4.

1. Define an experiental protocol by selecting b-values, echo times, 
   image resolution et c. 

   Acquisition software for Bruker is found in acq/bruker. 

   For implementations at Siemens and Philips, please contact us at 
   markus.nilsson@med.lu.se to discuss research cooperations.

2. Run the protocol and acquire data in some native format, for example, 
   DICOM. Unfortunately, all parameters needed to analyse the
   data may not be stored in the DICOM. For example, the mixing time in a
   FEXI experiment may not be in the DICOM header. The user need to find
   some way to connect this extra data to the image data. The fields needed
   for each model is listed in functions called *_check_xps.m, where
   here * is e.g. dti_nls, fexi, et c. 

   Example: In FEXI, mixing times need to be entered manually 
            as xps.mde_tm12 = [0.1 0.1 0.25];


3. Convert the data to the format supported in this framework. Image data
   in DICOM format is preferabbly converted by the dcm2nii utility
   https://www.nitrc.org/projects/dcm2nii/ 

   To convert metadata such as b-values into our format, we supply
   functions to assist in this process under the 'multidimensional
   data management' (mdm) package. 

   Example for a DTI-scan where gradient directions and b-values are stored
   in a gdir file (n_x, n_y, n_z, b)

        s.nii_fn = 'my_dti_scan.nii';
        s.xps    = mdm_xps_from_gdir('my_dti_scan_gdir.txt');

   The s-structure is now ready to enter a pipeline. The nii_fn points to 
   the 4D image data file, and the xps structure contains the experiment 
   parameters.

4. Execute a pipeline function. You find the pipelines under e.g. 
   models/dti_nls/dti_nls_pipe_example.m. The naming convention here is
   that the prefix 'dti_nls' tells something about the model/fitting, and
   the suffix about what is being done. Example:

        dti_nls_pipe_example(s, output_path);

   The pipeline generates a .mat-file with a model-fit structure (mfs). 
   This model-fit structure is generated by a function called e.g. 
   *_4d_data2fit. The pipeline may include both masking and motion 
   correction. Fitting will be performed in every voxel where the mask
   is non-zero. A manually defined mask can be supplied by setting 
   s.mask_fn. In addition, opt.i_range, opt.j_range, and opt.k_range can 
   be set to limit the loop to certain ranges in the first, second and third
   dimension of the image volume. In that case, the intersect of the mask 
   and the x_range parameter will be used as the final mask.

   From the model-fit structure, several parameter volumes can be generated
   for further analysis. This is done using functions named e.g.
   *_4d_fit2param. A pipeline typically includes this as the last step.

5. Analyze the data, stored as nii-files by drawing ROIs or using other 
   analysis packages of your choice.


We suggest you start analysing the model found in models/dti_nls to get
an understanding of the model structure.