Scripts
------------------
stdeconv
~~~~~~~~~~~~

For calculating the single-tissue response functions and the fODFs for given data run the following command [Ankele17]_:

.. code-block:: console

    $ stdeconv -i /path/to/your/data

The specified folder should contain the following files:

* :code:`bvecs`: b-vectors
* :code:`bvals`: b-values
* :code:`data.nii.gz`: The diffusion weighted data
* :code:`dti_FA.nii.gz`: Diffusion tensor Fractional Anisotropy map
* :code:`dti_V1.nii.gz`: The first eigenvector of the diffusion tensor

The :code:`dti_*` files can be generated using FSL's :code:`dtifit`. This script works if we have no T1 data.

Optional, but recommended:

* :code:`mask.nii.gz`: Binary mask, specifying brain voxels in which to estimate the model.
* :code:`fast_pve_2.nii.gz`: WM mask

Further important parameters are:

* :code:`--rank`: The rank of the computed fODF. Higher ranks lead to sharper peaks as well as higher susceptibility to noise. Default: 4. Supported: 4,6,8
* :code:`--kernel`: The single tissue response kernel used to estimate the CSD. Options are either `rank1` a single fiber rank-1 fiber corresponding to the rotational harmonic parts of the spherical harmonics up to the specified order or `delta` a single peak. `rank1` reduces the susceptibility to noise. Default: rank1


If you want to see a list of parameters type the following:

.. code-block:: console

    $ stdeconv -h

mtdeconv
~~~~~~~~~~~~

For calculating the multi-tissue response functions and the fODFs for given data run the following command [Ankele17]_:

.. code-block:: console

    $ mtdeconv -i /path/to/your/data

The specified folder should contain the following files:

* :code:`bvecs`: b-vectors
* :code:`bvals`: b-values
* :code:`data.nii.gz`: The diffusion weighted data
* :code:`dti_FA.nii.gz`: Diffusion tensor Fractional Anisotropy map
* :code:`fast_pve_0.nii.gz`: CSF mask
* :code:`fast_pve_1.nii.gz`: GM mask
* :code:`fast_pve_2.nii.gz`: WM mask
* :code:`dti_V1.nii.gz`: The first eigenvector of the diffusion tensor

The :code:`dti_*` files can be generated using FSL's :code:`dtifit`. The :code:`fast_*` files can be generated from coregistered T1 weighted images using FSL's :code:`fast`.

Optional, but recommended to greatly speed up computation:

* :code:`mask.nii.gz`: Binary mask, specifying brain voxels in which to estimate the model.

Further important parameters are:

* :code:`--rank`: The rank of the computed fODF. Higher ranks lead to sharper peaks as well as higher susceptibility to noise. Default: 4. Supported: 4,6,8
* :code:`--kernel`: The single tissue response kernel used to estimate the CSD. Options are either `rank1` a single fiber rank-1 fiber corresponding to the rotational harmonic parts of the spherical harmonics up to the specified order or `delta` a single peak. `rank1` reduces the susceptibility to noise. Default: rank1


If you want to see a list of parameters type the following:

.. code-block:: console

    $ mtdeconv -h


low-rank-k-approx
~~~~~~~~~~~~~~~~~~~~
For calculating the low-rank k approximation [Schultz08]_ of a given 4th order fODF run the following command:

.. code-block:: console

    $ low-rank-k-approx -i /path/to/your/fODF.nrrd -o path/to/output.nrrd

With additional argument

* :code:`-r`: Rank of low rank approximation. Default = 3

The output is a dim (4,r,x,y,z) array. Here the first axis contains in place 0: :math:`\lambda` the volume fraction
and in the remaining places :math:`\mathbb{v}` the unit direction.


peak-modelling
~~~~~~~~~~~~~~
Build a new model (Selection or Averaging) from given low rank k = 1,2,3 approximations [Gruen22]_ by running the following command:

.. code-block:: console

    $ peak-modelling -f path/to/fODF.nrrd -i path/to/rank-1.nrrd path/to/rank-2.nrrd path/to/rank-3.nrrd -o path/to/outfile.nrrd

Further the parameters can be set

* :code:`-t`: selection or averaging. Default averaging
* :code:`-a`: a parameter for Kumaraswarmy PDF. Default a = 1
* :code:`-b`: b parameter for Kumaraswarmy PDF. Default b = 20

The output is a dim (4,3,x,y,z) array. Here the first axis contains in place 0: :math:`\lambda` the volume fraction
and in the remaining places :math:`\mathbb{v}` the unit direction. If a voxel contains only 1 or 2 directions they are
at the first entries of the second axis.

csd-peaks
~~~~~~~~~~~~~~~~
For extracting maxima from a given 8th order fODF (These can be generated by running the mtdeconv script with additional parameters -k delta -r 8 -C nonneg) by run the following command:

.. code-block:: console

    $ csd-peaks path/to/fODF.nrrd path/to/output.nrrd

Further parameters can be set

* :code:`-r`: Count of fibers to extract. Default 3
* :code:`-sa`: Minimum separation angle in degrees. Default 0
* :code:`-m`: Minimum height of peak. Default 0

The output is a dim (4,r,x,y,z) array. Here the first axis contains in place 0: :math:`\lambda` the volume fraction
and in the remaining places :math:`\mathbb{v}` the unit direction.

prob-tracking
~~~~~~~~~~~~~~~~~~
Within the generated multivectorfields, which are an output of either low-rank-approx, peak-modelling or csd-peaks,
running the following command

.. code-block:: console

    $ prob-tracking --i /path/to/inputs -o /path/to/output.ply

generates streamlines for each seed point. Depending on the parameters, this script performs a basic form of streamline tractography, uses model averaging over fiber estimates with different numbers of compartments [Gruen22]_, or spatial regularization via joint approximation or an Unscented Kalman Filter [Gruen23]_.

If not further specified, the input folder has to contain the following:

- rank3.nrrd
    Multidirectionfield, where the first dimension defines the length and the
    unit direction of the vector, second dimension defines different directions
    and remaining dimensions diffine the coordinate.

    If the file is named differently, use the `\--infile` argument

- wmvolume.nrrd
    The white matter mask, which is an output of mtdeconv.

    If the file is named differently, use the `\--wmmask` argument

- seedpoint.pts
    The seed point file in world coordinates. First 3 dimensions of row give
    world coordinates. Additionally a initial direction can be set by appending
    3 columns to each row denoting the direction in (x,y,z) space.

    If the file is named differently, use the `\--seedpoint` argument.

If the -ukf flag is set, the input folder should also contain:

- bvals
    A text file which contains the bvals for each gradient direction.

    If the file is namend differenty, use the `\--ukf_bvals` argument

- bvecs
    A text file which contains all gradient directions in the format Ax3
    If the file is named differently, use the `\--ukf_bvecs` argument
- data.nrrd
    The file with the data. If the `\--ukfmethod` flag is set to

    - MultiTensor it should be the raw data.

    - LowRank it should be the fodf.nrrd output from mtdeconv

    If the file is named differently, use the `\--ukf_data` argument.

- baseline.nrrd
    File with b0 measurements

    If the file is named differently, use the `\--ukf_baseline` argument

If the -disk flag is set and we want to append to a file, the inputfolder should contain
    - output.txt
        A textfile with the streamlines generated so far.
        If the file is named differently, use the `\--disk_append` argument.


The output file is in ply format, which contain the vertex coordinates and the length of each streamline.

Further parameters can be set:

* :code:`--infile`: 5D (4,3,x,y,z) Multivectorfield, where the first dimension gives the length and the direction of the vector, the second dimension denotes different directions.
* :code:`--wmvolume`: WM Mask - output of mtdeconv
* :code:`--act`: 5tt output of 5ttgen. Will perform act if supplied.
* :code:`--seedpoints`: Seedspointfile: Each row denotes a seed point, where the first  3 columns give the seed point in (x,y,z). Further 3 additional columns can specified to define a initial direction. Columns should be seperated by whitespace.
* :code:`--wmmin`: Minimum WM density before tracking stops, default=0.15
* :code:`--sw_save`: Only each x step is saved. Reduces memory consumption greatly, default=1
* :code:`--sw`: Stepwidth for integration, default=0.9
* :code:`--o`: Filename for output file in ply or tck format. Only ply is fully supported.
* :code:`--mtlength`: Maximum track steps, default=300
* :code:`--samples`: Samples per seed, default=1
* :code:`--max_angle`: Max angle over the last 30 mm of the streamline, default=130
* :code:`--var`: Variance for probabilistic direction selection, default=1
* :code:`--exp`: Expectation for probabilistic direction selection, default=0
* :code:`--interpolation`: decide between FACT interpolation and Trilinear interpolation.', default='Trilinear'
* :code:`--sigma_1`: Only useful if interpolation is set to TrilinearFODF and dist>0. Controls sigma1 for low-rank, default=1
* :code:`--data`: Only useful if interpolation is set to TrilinearFODF and dist>0. Controls sigma1 for low-rank
* :code:`--sigma_2`: Only useful if interpolation is set to TrilinearFODF and dist>0. Controls sigma2 for low-rank, default=1
* :code:`--dist`: Only useful if interpolation is set to TrilinearFODF. Radius of points to include, default=0
* :code:`--rank`: Only useful if interpolation is set to TrilinearFODF. Rank of low-rank approx.', default=3
* :code:`--integration`: Decide between Euler integration, Trilinear and TrilinearFODF integration, default='TrilinearFODF'
* :code:`--prob`: Decide between Laplacian, Gaussian, Scalar, ScalarNew, Deterministic and Deterministic2, default='ScalarNew')
* :code:`--disk`: Write streamlines to file instead of using ram, default=True
* :code:`--disk_file`: Name of disk file. If not set a random filename is chosen.
* :code:`--disk_delete`: Delete file after finish. Otherwise further Streamlines can be appended if more streamlines are needed.
* :code:`--ukf`: The following arguments are just important if the --ukf flag is set to MultiTensor or LowRank
* :code:`--ukf_data`: File containing the raw data for ukf.
* :code:`--ukf_bvals`: File containg the bvals for each gradient direction
* :code:`--ukf_bvecs`: File containg the bvecs
* :code:`--ukf_baseline`: File containg the baseline'
* :code:`--ukf_fodf_order`: order of fODF. Only 4 and 8 are supported, default=4
* :code:`--ukf_dim_model`: Dimensions of model
* :code:`--ukf_pnoise`: Process noise
* :code:`--ukf_mnoise`: Measurement noise

For a set of possible directions :math:`v_i` and a given current direction :math:`w`, the probability of the next direction is given either by
Gaussian

.. math::

    p \left( v_i \right) = \exp \left(  -1/2 \left(\frac{  \theta_i - b }{\sigma } \right)^2 \right)

Laplacian

.. math::

    p \left( v_i \right) = 1/2 \exp \left( - \left| \frac{  \theta_i - b } { \sigma } \right| \right)

ScalarOld

.. math::

    p \left( v_i \right) =  \mathbb{1}_{ \lbrace \theta_i < \frac{1}{3}\pi \rbrace }  \lambda_i \cos \left( \left( \frac{3}{\sqrt{2 \pi}} \theta_i \right)^2 \right)^2

ScalarNew

.. math::

    p \left( v_i \right) =  \mathbb{1}_{ \lbrace \theta_i < \frac{1}{3}\pi \rbrace }  \lambda_i \cos \left( \left( \frac{3}{\sqrt{2 \pi}} \theta_i \right)^2 \right)^2 \exp \left( - \frac{\left( \| v_i \| - \| w \| \right)^2}{\sigma} \right)

where :math:`\theta_i` denotes the angle between :math:`\pm v_i` and :math:`w` (Select :math:`\pm v_i` such
that :math:`\theta_i \leq 90`) and :math:`b` is set via :code:`-exp` and :math:`\sigma` is set via :code:`-var`.
Then the next direction is chosen by an random draw.

The output file is in ply format, which contains two elements. Firstly, vertices:
contains spatial information about the streamlines, e.g. coordinates in 3D. Further the seed-coordinate is marked by a 1.
These are saved in the properties: x, y, z, seedpoint.
Secondly, fiber. Contains the property endindex, which denotes the end index of a streamline.


bundle-filtering
~~~~~~~~~~~~~~~~
The generated streamlines can be filtered by running the following command:

.. code-block:: console

    $ bundle-filtering -i path/to/trackingResults.ply -m path/to/fODF.nrrd -o path/to/outfile.ply

It has been used for filtering tractography results in [Gruen22]_ and [Gruen23]_.
If this script is applied to self generated ply data, it is important that this ply file contains the following:
Firstly, vertices:
contains spatial information about the streamlines, e.g. coordinates in 3D. Further the seed-coordinate is marked by a 1.
These are saved in the properties: x, y, z, seedpoint.
Secondly, fiber. Contains the property endindex, which denotes the end index of a streamline.

Further several filter parameters can be set:

* :code:`--mask`: Minimal streamline density. Creates a voxel mask and cuts of each streamline at the first intersection with the complement of the mask. Default 5
* :code:`--exclusion`: Filters out all streamlines which intersect with a given plane e.g. x<10. Several planes can be seperated with white spaces. Default ""
* :code:`--exclusionc`: Filters out all streamlines which intersect with a given cube e.g. 10<x<20,5<y90,40<z<100. Several cubes can be seperated by a white space Default ""
* :code:`--minlen`: Filters out all streamlines which not at least minlen long. Default 0.

kurtosis
~~~~~~~~
Fits the diffusional kurtosis (DKI) model using quadratic cone programming to guarantee a minimum diffusivity. This increases robustness of the fit, and is described in the methods section of [Groeschel16]_. The script also computes a number of measures based on the result, including mean, axial, and radial kurtosis.

If not specified otherwise, the input folder has to contain the following files:

* :code:`data.nii.gz`: The diffusion weighted data
* :code:`mask.nii.gz`: A binary brain mask for the diffusion weighted data

and the output is written to the same folder:

* :code:`da.nii`: Axial diffusivity
* :code:`dr.nii`: Radial diffusivity
* :code:`dm.nii`: Mean diffusivity
* :code:`fa.nii`: Fractional Anisotropy
* :code:`ka.nii`: Axial kurtosis
* :code:`kr.nii`: Radial kurtosis
* :code:`km.nii`: Mean kurtosis

Moreover, the following parameters can be set:

* :code:`-d`: to specify a different filename for the diffusion weighted data
* :code:`-m`: to specify a different filename for the brain mask
* :code:`-o`: to specify a different folder for the output files
* :code:`-t`: to specify a threshold for b-values that should be treated as zero (default: 0)
* :code:`-R`: to only fit the DKI model, without computing invariants
