10. File formats

  • imgfile: This is a MATLAB v7.3 (HDF5) .mat file that stores multicontrast MRI images. It contains four variables: data, resolution, spatial_dim and transform.

    Variable name

    Dimension/example & details

    data

    This variable contains the multidimensional MR image as a matrix of following dimension

    – \(N_a \times N_1 \times N_2 \times N_3\) (for 3D volume): Each \(N_3\) slice is processed sequentially

    – \(N_a \times N_1 \times N_2\) (for 2D volume)

    \(N_a\): number of acquired multicontrast MRI images

    \(N_i\): \(i\)-th spatial dimension (\(i=1,2,3\))

    resolution

    [vox_dim_1 vox_dim_2 vox_dim_3]

    vox_dim_i: pixel dimension along i-th spatial dimension

    spatial_dim

    A vector storing the spatial dimension values

    – [N1 N2 N3] or [N1 N2]

    \(N_i\): \(i\)-th spatial dimension

    Spatial dimension can’t be 1D

    transform

    4 x 4 transform matrix

  • spatmaskfile: This is a MATLAB v7.3 (HDF5) .mat file that contains contains a binary spatial mask variable im_mask.

    Variable name

    Dimension/example & details

    im_mask

    This variable contains the spatial mask for the MRI images. This matrix takes binary values - 1 indicates the spatial locations that should be considered, and 0 indicates the spatial location that are excluded. Notice that the spatial dimensions for the MRI images must match with the dimension of the mask.

    – \(N_1 \times N_2 \times N_3\) (for 3D volume)

    – \(N_1 \times N_2\) (for 2D volume)

    \(N_i\): \(i\)-th spatial dimension (\(i=1,2,3\))

  • spect_infofile: This is a MATLAB v7.3 (HDF5) .mat file containing variables that define the spectral parameters and dictionary matrix for spectroscopic image estimation. This contains variable K and a structure array variable axes (array dimension defined by the number of spectral dimension) with fields described below:

    Variable name

    Dimension/example & details

    K

    This variable defines the dictionary for spectroscopic image estimation. The matrix dimension should match the following convention, e.g.,

    – \(N_a \times M_1 \times M_2\) (for 2D spectra)

    – \(N_a \times M_1\) (for 1D spectra)

    \(N_a\): number of acquired multicontrast images

    \(M_p\): The number of spectral parameter gridpoints along the \(p\)th spectral dimension.

    spectral_dim

    A vector storing the spectral dimension values: – \([M_1 \; M_2 \; \cdots \; M_P]\) for \(P\)-dimensional spectrum \(M_i\): \(i\)-th spectral dimension.

    axes(p).sample

    This stores a vector array of spectral parameter gridpoints for \(p\)th spectral dimension, which should correspond to how the dictionary K was created. It should be a vector of dimension \(M_p \times 1\).

    axes(p).name

    This is a string variable defined by user to name the \(p\)th spectral dimension. e.g., if the user is interested in \(T_2\) relaxation data, then this value could be the string "T_2".

    axes(p).unit

    This is a string variable defined by user to store the units for the \(p\)th spectral dimension.

    axes(p).spacing

    If the dictionary is constructed using linear or logarithmic spacing of the parameter gridpoints, then this variable should be set to one of the following strings: "linear", "log" (case sensitive).

  • configfile: This is a .ini file consisting of parameters for the algorithm.

    Variable name

    Dimension/example & details

    solver.name

    string variable denoting the name of the algorithm user wants to implement. Can only be one of the following strings - "LADMM", "ADMM", "NNLS". Note that if the string is "NNLS", then the following config variables are redundant.

    solver.num_iter

    This stores an integer value denoting the number of iteration to run for (L)ADMM algorithm. Its is a required input. If this is set to a low value, the solver may not converge to global minima, and the result may not look as expected.

    solver.beta

    This is the (L)ADMM parameter. Takes a floating point number as input. Its a required input for (L)ADMM algorithm. This value tunes the convergence speed, but does not change the converged solution.

    solver.save_inter

    This stores an integer value denoting the iteration interval to show progress for Spectrum Estimation tool and to save intermediate cost function values for the beta calculation tool.

    – Default value, solver.num_iter/10.

    solver.tol

    This is a floating point value denoting the tolerance level of min-normalised succesive error. If the calculated tolerance as described below, is lower than solver.tol, then the solver stops execution.

    – For \(ij\)-th iteration, its calculated as, \(\frac{\|spectrum_{ij}-spectrum_{(i-1)j}\|}{min(\|spectrum_{ij}\|,\|spectrum_{(i-1)j}\|)}\), where \(j=\) solver.save_inter and \(i=2,3,...\).

    – Default value, \(10^{-5}\).

    – Note that if solver.save_inter is very low value, that the two spectra of interest may not change much, then also this solver.tol value might be reached but the result may not actually converge to the actual solution. So the user need to keep a balance between these two variables.

    solver.check_tol

    This stores an integer value denoting iteration number after which the tolerance value is checked. This is due to the reason that, when we start the estimated spectrum does not significantly change, so we want the solver to reach to some iteration, after which the we check the tolerance.

    – Default value, solver.num_iter/2.

    low_rank.flag

    This takes binary value, 1 if user wants to use low rank approximation of the dictionary matrix, K. This significantly increases the speed of convergence. Also, note that, this is used only for LADMM algorithm.

    low_rank.rank

    An integer value depicting the rank of the approximated matrix form of the K tensor. This value is ignored if low_rank.flag is 0. Note that on this documentation the dictionary is in a tensor form. To Approximate the rank, you need to flatten all the spectral dimension of the tensor and create a matrix of dimension \(N_a \times M_1M_2\) (for 2D spectra) or \(N_a \times M_1\) (for 1D spectra). Then you need to choose the approximate rank of the resulted matrix.

    dc_comp

    Takes either 1 or 0 as input.

    lambda

    Spatial-Regulariser value. Take floating point number as input.

  • spect_imagefile: This is a MATLAB v7.3 (HDF5) .mat file storing an estimated spectroscopic image.

    Variable name

    Dimension/example & details

    spectral_image

    This matrix variable stores the spectroscopic image. The matrix dimension should match the following convention, e.g.,

    – \(M_1 \times M_2 \times \cdots \times M_P \times N_1 \times N_2 \times N_3\) (for \(P\)-Dimensional spectrum and 3D volume)

    – \(M_1 \times M_2 \times N_1 \times N_2\) (for 3-Dimensional spectrum and 2D volume)

    Note: In this variable, spectral dimension is followed by spatial dimension.

    spectral_dim

    A vector storing the spectral dimension values:

    – \([M_1 \; M_2 \; \cdots \; M_P]\) for \(P\)-dimensional spectrum

    \(M_i\): \(i\)-th spectral dimension.

    spatial_dim

    A vector storing the spatial dimension values:

    – \([N_1 \; N_2 \; N_3]\) or \([N_1 \; N_2]\) or \([N_1]\)

    \(N_i\): \(i\)-th spatial dimension.

    axes(k).sample

    For \(k=1,2,\cdots,P\): stores a vector array of spectral sample points of the \(k\)-th spectral dimension. It should be a vector of dimension \(M_k \times 1\). This variable is directly passed from the input with a similar name. For \(k=P+1,\cdots\) it is an empty vector.

    axes(k).type

    A string variable taking value either "spectral" or "spatial" depending on the \(k\)-th dimension of the spectroscopic image.

    axes(k).name

    A string variable denoting the name of the \(k\)-th dimension of the spectroscopic image. Note: For spatial dimensions, the first spatial dimension is automatically assigned the name "x" followed by "y", "z".

    axes(k).unit

    A string variable denoting the unit for the \(k\)-th dimension of the spectroscopic image. For spatial dimensions, its value is always "mm".

    axes(k).spacing

    The spacing between the sample points of the \(k\)-th dimension of the spectroscopic image. For spatial dimensions, its value is always "linear".

    resolution

    \([vox\_dim_1 \; vox\_dim_2 \; vox\_dim_3]\) where \(vox\_dim_i\) is the pixel dimension along the \(i\)-th spatial dimension.

    transform

    A \(4 \times 4\) transform matrix.

  • spectmaskfile: This is a MATLAB v7.3 (HDF5) .mat file that stores binary spectral masks for use in visualizing microstructural component maps.

    Variable name

    Dimension/example & details

    num_comp

    This variable contain the total number of discrete components chosen (\(=N_c\)).

    spec_mask

    This variable contains the spectral mask. For \(c\)-th component, this matrix takes binary values - 1 indicates the spectral location to be summed over for that component and 0 other wise.

    – \(M_1 \times M_2 \times \cdots \times M_P \times N_c\) (for :math>`P`-dimensional spectrum )

    – \(M_1 \times M_2 \times N_c\) (2D spectra)

    – \(M_1 \times N_c\) (1D spectra)

    \(M_p\): \(p\)-th spectral dimension (\(p=1,2,3\))

  • color: This is the name of the .mat file that contains the color RGB values used to render component maps. It stores a single variable, color, and is used by Plot Component Maps tool.

    Variable name

    Dimension/example & details

    color

    RGB triplets for each component. Values are in [0, 1]. Rows correspond to channels and columns to \(N_c\) components:

    – \(3 \times N_c`\) : row 1 = R, row 2 = G, row 3 = B; column j gives the color for component j.