# dipy_fit_fwdti

## Synopsis

Workflow for Free Water Elimination Diffusion Tensor Model.

Performs a Free Water Elimination Diffusion Tensor reconstruction [1] on the files by ‘globing’ `input_files` and saves the DTI metrics in a directory specified by `out_dir`.

## Usage

    dipy_fit_fwdti [OPTIONS] input_files bvalues_files bvectors_files mask_files

## Input Parameters

- `input_files`

  Path to the input volumes. This path may contain wildcards to process multiple inputs at once.

- `bvalues_files`

  Path to the bvalues files. This path may contain wildcards to use multiple bvalues files at once.

- `bvectors_files`

  Path to the bvectors files. This path may contain wildcards to use multiple bvectors files at once.

- `mask_files`

  Path to the input masks. This path may contain wildcards to use multiple masks at once.

## General Options

- `--fit_method`

  Controls the method used to fit the FW-DTI model. You can choose between a simpler linear approach (WLS) or a more complex non-linear approach (NLS). Both methods are described in [1]. (default: NLS)

- `--b0_threshold`

  Threshold used to find b0 volumes. (default: 50)

- `--bvecs_tol`

  Threshold used to check that norm(bvec) = 1 +/- bvecs_tol (default: 0.01)

- `--npeaks`

  Number of peaks/eigen vectors to save in each voxel. DTI generates 3 eigen values and eigen vectors. The principal eigenvector is saved by default. (default: 1)

- `--sigma`

  An estimate of the variance. Chang et al.[2] recommend to use 1.5267 * std(background_noise), where background_noise is estimated from some part of the image known to contain no signal (only noise) b-vectors are unit vectors. (default: None)

- `--save_metrics`

  List of metrics to save. Possible values: fa, ga, rgb, md, ad, rd, mode, tensor, evec, eval (default: None)

- `--nifti_tensor`

  Whether the tensor is saved in the standard Nifti format or in an alternate format that is used by other software (e.g., FSL): a 4-dimensional volume (shape (i, j, k, 6)) with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz on the last dimension. (default: True)

- `--extract_pam_values`

  Save or not to save pam volumes as single nifti files. (default: False)

## Output Options

- `--out_dir`

  Output directory. (default current directory) (default: current directory)

- `--out_tensor`

  Name of the tensors volume to be saved. Per default, this will be saved following the nifti standard: with the tensor elements as Dxx, Dxy, Dyy, Dxz, Dyz, Dzz on the last (5th) dimension of the volume (shape: (i, j, k, 1, 6)). If nifti_tensor is False, this will be saved in an alternate format that is used by other software (e.g., FSL): a 4-dimensional volume (shape (i, j, k, 6)) with Dxx, Dxy, Dxz, Dyy, Dyz, Dzz on the last dimension. (default: fwdti_tensors.nii.gz)

- `--out_fa`

  Name of the fractional anisotropy volume to be saved. (default: fwdti_fa.nii.gz)

- `--out_ga`

  Name of the geodesic anisotropy volume to be saved. (default: fwdti_ga.nii.gz)

- `--out_rgb`

  Name of the color fa volume to be saved. (default: fwdti_rgb.nii.gz)

- `--out_md`

  Name of the mean diffusivity volume to be saved. (default: fwdti_md.nii.gz)

- `--out_ad`

  Name of the axial diffusivity volume to be saved. (default: fwdti_ad.nii.gz)

- `--out_rd`

  Name of the radial diffusivity volume to be saved. (default: fwdti_rd.nii.gz)

- `--out_mode`

  Name of the mode volume to be saved. (default: fwdti_mode.nii.gz)

- `--out_evec`

  Name of the eigenvectors volume to be saved. (default: fwdti_evecs.nii.gz)

- `--out_eval`

  Name of the eigenvalues to be saved. (default: fwdti_evals.nii.gz)

- `--out_pam`

  Name of the peaks volume to be saved. (default: fwdti_peaks.pam5)

- `--out_peaks_dir`

  Name of the peaks directions volume to be saved. (default: fwdti_peaks_dirs.nii.gz)

- `--out_peaks_values`

  Name of the peaks values volume to be saved. (default: fwdti_peaks_values.nii.gz)

- `--out_peaks_indices`

  Name of the peaks indices volume to be saved. (default: fwdti_peaks_indices.nii.gz)

- `--out_sphere`

  Sphere vertices name to be saved. (default: fwdti_sphere.txt)

- `--out_qa`

  Name of the Quantitative Anisotropy to be saved. (default: fwdti_qa.nii.gz)

## References

[1] (1,2)

Rafael Neto Henriques, Ariel Rokem, Eleftherios Garyfallidis, Samuel St-Jean, Eric Thomas Peterson, and Marta Morgado Correia. [Re] Optimization of a free water elimination two-compartment model for diffusion tensor imaging. bioRxiv, 2017. doi:https://doi.org/10.1101/108795.

[2]

Lin-Ching Chang, Derek K. Jones, and Carlo Pierpaoli. RESTORE: Robust estimation of tensors by outlier rejection. Magnetic Resonance in Medicine, 53(5):1088–1095, 2005. URL: https://doi.org/10.1002/mrm.20426, doi:10.1002/mrm.20426.

Garyfallidis, E., M. Brett, B. Amirbekian, A. Rokem, S. Van Der Walt, M. Descoteaux, and I. Nimmo-Smith. Dipy, a library for the analysis of diffusion MRI data. Frontiers in Neuroinformatics, 1-18, 2014.