API Reference

$T_2$-distribution mapping

DECAES.T2mapOptions — Type
T2mapOptions(; <keyword arguments>)

Options structure for T2mapSEcorr. This struct collects keyword arguments passed to T2mapSEcorr, performs checks on parameter types and values, and assigns default values to unspecified parameters.

Arguments

  • MatrixSize: size of first 3 dimensions of input 4D image. This argument is has no default, but is inferred automatically as size(image)[1:3] when calling T2mapSEcorr(image; kwargs...)
  • nTE: number of echoes in input signal. This argument is has no default, but is inferred automatically as size(image, 4) when calling T2mapSEcorr(image; kwargs...)
  • TE: interecho spacing (Default: 10e-3, Units: seconds)
  • T1: assumed value of T1 (Default: 1.0, Units: seconds)
  • Threshold: first echo intensity cutoff for empty voxels (Default: 200.0)
  • Chi2Factor: constraint on $\chi^2$ used for regularization when Reg == "chi2" (Default: 1.02)
  • nT2: number of T2 times to use (Default: 40)
  • T2Range: min and max T2 values (Default: (10e-3, 2.0), Units: seconds)
  • RefConAngle: refocusing pulse control angle (Default: 180.0, Units: degrees)
  • MinRefAngle: minimum refocusing angle for flip angle optimization (Default: 50.0, Units: degrees)
  • nRefAngles: during flip angle optimization, goodness of fit is checked for up to nRefAngles angles in the range [MinRefAngle, 180]. The optimal angle is then determined through interpolation from these samples (Default: 32)
  • nRefAnglesMin: initial number of angles to check during flip angle optimization before refinement near likely optima; nRefAnglesMin == nRefAngles forces all angles to be checked (Default: 5)
  • Reg: regularization routine to use:
    • "no": no regularization of solution
    • "chi2": use Chi2Factor based regularization (Default)
    • "lcurve": use L-Curve based regularization
  • SetFlipAngle: instead of optimizing flip angle, use this flip angle for all voxels (Default: nothing, Units: degrees)
  • SaveResidualNorm: true/false option to include a 3D array of the $\ell^2$-norms of the residuals from the NNLS fits in the output maps dictionary (Default: false)
  • SaveDecayCurve: true/false option to include a 4D array of the time domain decay curves resulting from the NNLS fits in the output maps dictionary (Default: false)
  • SaveRegParam: true/false option to include 3D arrays of the regularization parameters $\mu$ and resulting $\chi^2$-factors in the output maps dictionary (Default: false)
  • SaveNNLSBasis: true/false option to include a 5D (or 2D if SetFlipAngle is used) array of NNLS basis matrices in the output maps dictionary (Default: false)
  • Silent: suppress printing to the console (Default: false)
Note

The 5D array that is saved when SaveNNLSBasis is set to true has dimensions MatrixSize x nTE x nT2, and therefore is typically extremely large; by default, it is nT2 = 40 times the size of the input image. However, if the flip angle is fixed via SetFlipAngle, the unique nTE x nT2 2D basis matrix is returned.

See also:

source
DECAES.T2mapSEcorr — Function
T2mapSEcorr(image; <keyword arguments>)
T2mapSEcorr(image, opts::T2mapOptions)

Uses nonnegative least squares (NNLS) to compute T2 distributions in the presence of stimulated echos by optimizing the refocusing pulse flip angle. Records parameter maps and T2 distributions for further partitioning.

Arguments

  • image: 4D array with intensity data as (row, column, slice, echo)
  • A series of optional keyword argument settings which will be used to construct a T2mapOptions struct internally, or a T2mapOptions struct directly

Outputs

  • maps: dictionary containing parameter maps with the following fields:
    • Default Fields
      • "echotimes" Echo times of time signal (length nTE 1D array)
      • "t2times" T2 times corresponding to T2-distributions (length nT2 1D array)
      • "refangleset" Refocusing angles used during flip angle optimization (length nRefAngles 1D array by default; scalar if SetFlipAngle is used)
      • "decaybasisset" Decay basis sets corresponding to "refangleset" (nTE x nT2 x nRefAngles 3D array by default; nTE x nT2 2D array if SetFlipAngle is used)
      • "gdn": Map of general density = sum(T2distribution) (MatrixSize 3D array)
      • "ggm": Map of general geometric mean of T2-distribution (MatrixSize 3D array)
      • "gva": Map of general variance (MatrixSize 3D array)
      • "fnr": Map of fit to noise ratio = gdn / sqrt(sum(residuals.^2) / (nTE-1)) (MatrixSize 3D array)
      • "snr": Map of signal to noise ratio = maximum(signal) / std(residuals) (MatrixSize 3D array)
      • "alpha": Map of optimized refocusing pulse flip angle (MatrixSize 3D array)
    • Optional Fields
      • "resnorm": $\ell^2$-norm of NNLS fit residuals; see SaveResidualNorm option (MatrixSize 3D array)
      • "decaycurve": Signal decay curve resulting from NNLS fit; see SaveDecayCurve option (MatrixSize x nTE 4D array)
      • "mu": Regularization parameter used during from NNLS fit; see SaveRegParam option (MatrixSize 3D array)
      • "chi2factor": $\chi^2$ increase factor relative to unregularized NNLS fit; see SaveRegParam option (MatrixSize 3D array)
      • "decaybasis": Decay bases resulting from flip angle optimization; see SaveNNLSBasis option (MatrixSize x nTE x nT2 5D array, or nTE x nT2 2D array if SetFlipAngle is used)
  • distributions: T2-distribution array with data as (row, column, slice, T2 amplitude) (MatrixSize x nT2 4D array)

Examples

julia> image = DECAES.mock_image(MatrixSize = (100,100,1), nTE = 32); # mock image with size 100x100x1x32

julia> maps, dist = T2mapSEcorr(image; TE = 10e-3, Silent = true); # compute the T2-maps and T2-distribution

julia> maps
Dict{String,Array{Float64,N} where N} with 10 entries:
  "echotimes"     => [0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09, 0.1  …  0.23, …
  "t2times"       => [0.01, 0.0114551, 0.013122, 0.0150315, 0.0172188, 0.0197244, 0.022594…
  "refangleset"   => [50.0, 54.1935, 58.3871, 62.5806, 66.7742, 70.9677, 75.1613, 79.3548,…
  "gdn"           => [1.86624e5 1.1901e5 … 1.3624e5 1.72367e5; 1.49169e5 1.24536e5 … 1.623…
  "fnr"           => [479.252 451.153 … 492.337 522.685; 328.645 440.903 … 473.648 416.366…
  "alpha"         => [165.011 164.049 … 163.291 164.945; 164.849 166.599 … 163.674 165.679…
  "gva"           => [0.485815 0.401323 … 0.340727 0.436184; 0.321887 0.317154 … 0.278256 …
  "ggm"           => [0.0494864 0.0506017 … 0.0518207 0.0501371; 0.0530299 0.052983 … 0.05…
  "snr"           => [368.732 349.29 … 384.417 406.59; 258.914 349.542 … 373.792 331.304; …
  "decaybasisset" => [0.0277684 0.0315296 … 0.0750511 0.0751058; 0.0469882 0.0536334 … 0.1…

See also:

$T_2$-parts and the myelin water fraction

DECAES.T2partOptions — Type
T2partOptions(; <keyword arguments>)

Options structure for T2partSEcorr. This struct collects keyword arguments passed to T2partSEcorr, performs checks on parameter types and values, and assigns default values to unspecified parameters.

Arguments

  • MatrixSize: size of first 3 dimensions of input 4D T2 distribution. This argument is has no default, but is inferred automatically as size(T2distribution)[1:3] when calling T2partSEcorr(T2distribution; kwargs...)
  • nT2: number of T2 values in distribution. This argument is has no default, but is inferred automatically as size(T2distribution, 4) when calling T2partSEcorr(T2distribution; kwargs...)
  • T2Range: min and max T2 values of distribution (Default: (10e-3, 2.0), Units: seconds)
  • SPWin: min and max T2 values of the short peak window (Default: (10e-3, 25e-3), Units: seconds)
  • MPWin: min and max T2 values of the middle peak window (Default: (25e-3, 200e-3), Units: seconds)
  • Sigmoid: apply sigmoidal weighting to the upper limit of the short peak window in order to smooth the hard small pool window cutoff time. Sigmoid is the delta-T2 parameter, which is the distance in seconds on either side of the SPWin upper limit where the sigmoid curve reaches 10% and 90% (Default: nothing, Units: seconds)
  • Silent: suppress printing to the console (Default: false)

See also:

source
DECAES.T2partSEcorr — Function
T2partSEcorr(T2distributions; <keyword arguments>)
T2partSEcorr(T2distributions, opts::T2partOptions)

Analyzes T2 distributions produced by T2mapSEcorr to produce data maps of a series of parameters.

Arguments

  • T2distributions: 4D array with data as (row, column, slice, T2 amplitude)
  • A series of optional keyword argument settings which will be used to construct a T2partOptions struct internally, or a T2partOptions struct directly

Ouputs

  • maps: a dictionary containing the following 3D data maps as fields:
    • "sfr": small pool fraction, e.g. myelin water fraction (MatrixSize 3D array)
    • "sgm": small pool geometric mean T2 (MatrixSize 3D array)
    • "mfr": medium pool fraction, e.g. intra/extracellular water fraction (MatrixSize 3D array)
    • "mgm": medium pool geometric mean T2 (MatrixSize 3D array)

Examples

julia> dist = DECAES.mock_T2_dist(MatrixSize = (100,100,1), nT2 = 40); # mock distribution with size 100x100x1x40

julia> maps = T2partSEcorr(dist; Silent = true); # compute T2-parts maps

julia> maps # MWF is contained in maps["sfr"]
Dict{String,Array{Float64,3}} with 4 entries:
  "sgm" => [0.0159777 0.0156194 … 0.0149169 0.0121455; 0.015296 0.0143854 … 0.018459 0.01627…
  "mfr" => [0.852735 0.814759 … 0.808621 0.859088; 0.830943 0.804878 … 0.836248 0.816681; … …
  "sfr" => [0.147265 0.185241 … 0.191379 0.140912; 0.169057 0.195122 … 0.163752 0.183319; … …
  "mgm" => [0.0600928 0.0581919 … 0.0612683 0.0563942; 0.0606434 0.0584615 … 0.0569397 0.054…

See also:

NNLS analysis

DECAES.lsqnonneg — Function
lsqnonneg(C::AbstractMatrix, d::AbstractVector)

Returns the nonnegative least-squares (NNLS) solution, X, of the equation:

\[X = \mathrm{argmin}_{x \ge 0} ||Cx - d||_2^2\]

Arguments

  • C::AbstractMatrix: Left hand side matrix acting on x
  • d::AbstractVector: Right hand side vector

Outputs

  • X::AbstractVector: NNLS solution
DECAES.lsqnonneg_reg — Function
lsqnonneg_reg(C::AbstractMatrix, d::AbstractVector, Chi2Factor::Real)

Returns the regularized NNLS solution, X, that incurrs an increase in $\chi^2$ approximately by a factor of Chi2Factor. The regularized NNLS problem solved internally is:

\[X = \mathrm{argmin}_{x \ge 0} ||Cx - d||_2^2 + \mu^2 ||x||_2^2\]

where $\mu$ is determined by approximating a solution to the nonlinear equation

\[\frac{\chi^2(\mu)}{\chi^2_{min}} = \mathrm{Chi2Factor} \quad \text{where} \quad \chi^2_{min} = \chi^2(\mu = 0)\]

Arguments

  • C::AbstractMatrix: Decay basis matrix
  • d::AbstractVector: Decay curve data
  • Chi2Factor::Real: Desired $\chi^2$ increase due to regularization

Outputs

  • X::AbstractVector: Regularized NNLS solution
  • mu::Real: Resulting regularization parameter $\mu$
  • Chi2Factor::Real: Actual increase $\chi^2(\mu)/\chi^2_{min}$, which will be approximately equal to the input Chi2Factor
DECAES.lsqnonneg_lcurve — Function
lsqnonneg_lcurve(C::AbstractMatrix, d::AbstractVector)

Returns the regularized NNLS solution, X, of the equation

\[X = \mathrm{argmin}_{x \ge 0} ||Cx - d||_2^2 + \mu^2 ||H x||_2^2\]

where $H$ is the identity matrix and $\mu$ is chosen by the L-curve theory using the Generalized Cross-Validation method. Details of L-curve and GCV methods can be found in: Hansen, P.C., 1992. Analysis of Discrete Ill-Posed Problems by Means of the L-Curve. SIAM Review, 34(4), 561-580

Arguments

  • C::AbstractMatrix: Decay basis matrix
  • d::AbstractVector: Decay curve data

Outputs

  • X::AbstractVector: Regularized NNLS solution
  • mu::Real: Resulting regularization parameter $\mu$
  • Chi2Factor::Real: Resulting increase in $\chi^2$ relative to unregularized ($\mu = 0$) solution

Extended phase graph algorithm

DECAES.EPGdecaycurve — Function
EPGdecaycurve(ETL::Int, flip_angle::Real, TE::Real, T2::Real, T1::Real, refcon::Real)

Computes the normalized echo decay curve for a MR spin echo sequence using the extended phase graph algorithm using the given input parameters.

Arguments

  • ETL::Int: echo train length, i.e. number of echos
  • flip_angle::Real: angle of refocusing pulses (Units: degrees)
  • TE::Real: inter-echo time (Units: seconds)
  • T2::Real: transverse relaxation time (Units: seconds)
  • T1::Real: longitudinal relaxation time (Units: seconds)
  • refcon::Real: value of Refocusing Pulse Control Angle (Units: degrees)

Outputs

  • decay_curve::AbstractVector: normalized echo decay curve with length ETL

Main entrypoint function

DECAES.main — Function
main(command_line_args = ARGS)

Entry point function for command line interface, parsing the command line arguments ARGS and subsequently calling one or both of T2mapSEcorr and T2partSEcorr with the parsed settings. See the Arguments section for available options.

See also: