API Reference
$T_2$-distribution mapping
DECAES.T2mapOptions
— TypeT2mapOptions(; <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 assize(image)[1:3]
when callingT2mapSEcorr(image; kwargs...)
nTE
: number of echoes in input signal. This argument is has no default, but is inferred automatically assize(image, 4)
when callingT2mapSEcorr(image; kwargs...)
TE
: interecho spacing. This argument has no default (Units: seconds)T1
: assumed value of T1 (Default:1.0
, Units: seconds)Threshold
: first echo intensity cutoff for empty voxels (Default:0.0
)Chi2Factor
: constraint on $\chi^2$ used for regularization whenReg == "chi2"
(Default:1.02
)nT2
: number of T2 times to use. This argument has no defaultT2Range
: tuple of min and max T2 values. This argument has no default (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 tonRefAngles
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"
: useChi2Factor
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 ifSetFlipAngle
is used) array of NNLS basis matrices in the output maps dictionary (Default:false
)Silent
: suppress printing to the console (Default:false
)
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. However, if the flip angle is fixed via SetFlipAngle
, the unique nTE x nT2
2D basis matrix is returned.
See also:
DECAES.T2mapSEcorr
— FunctionT2mapSEcorr(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 aT2mapOptions
struct directly
Outputs
maps
: dictionary containing parameter maps with the following fields:- Default Fields
"echotimes"
Echo times of time signal (lengthnTE
1D array)"t2times"
T2 times corresponding to T2-distributions (lengthnT2
1D array)"refangleset"
Refocusing angles used during flip angle optimization (lengthnRefAngles
1D array by default; scalar ifSetFlipAngle
is used)"decaybasisset"
Decay basis sets corresponding to"refangleset"
(nTE x nT2 x nRefAngles
3D array by default;nTE x nT2
2D array ifSetFlipAngle
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; seeSaveResidualNorm
option (MatrixSize
3D array)"decaycurve"
: Signal decay curve resulting from NNLS fit; seeSaveDecayCurve
option (MatrixSize x nTE
4D array)"mu"
: Regularization parameter used during from NNLS fit; seeSaveRegParam
option (MatrixSize
3D array)"chi2factor"
: $\chi^2$ increase factor relative to unregularized NNLS fit; seeSaveRegParam
option (MatrixSize
3D array)"decaybasis"
: Decay bases resulting from flip angle optimization; seeSaveNNLSBasis
option (MatrixSize x nTE x nT2
5D array, ornTE x nT2
2D array ifSetFlipAngle
is used)
- Default Fields
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
— TypeT2partOptions(; <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 assize(T2distribution)[1:3]
when callingT2partSEcorr(T2distribution; kwargs...)
nT2
: number of T2 values in distribution. This argument is has no default, but is inferred automatically assize(T2distribution, 4)
when callingT2partSEcorr(T2distribution; kwargs...)
T2Range
: tuple of min and max T2 values of distribution. This argument has no default (Units: seconds)SPWin
: tuple of min and max T2 values of the short peak window. This argument has no default (Units: seconds)MPWin
: tuple of min and max T2 values of the middle peak window. This argument has no default (Units: seconds)Sigmoid
: apply sigmoidal weighting to the upper limit of the short peak window in order to smooth the hard small peak window cutoff time.Sigmoid
is the delta-T2 parameter, which is the distance in seconds on either side of theSPWin
upper limit where the sigmoid curve reaches 10% and 90% (Default:nothing
, Units: seconds)Silent
: suppress printing to the console (Default:false
)
See also:
DECAES.T2partSEcorr
— FunctionT2partSEcorr(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 aT2partOptions
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
— Functionlsqnonneg(C::AbstractMatrix, d::AbstractVector)
Returns the nonnegative least-squares (NNLS) solution, X, of the equation:
Arguments
C::AbstractMatrix
: Left hand side matrix acting onx
d::AbstractVector
: Right hand side vector
Outputs
X::AbstractVector
: NNLS solution
DECAES.lsqnonneg_reg
— Functionlsqnonneg_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:
where $\mu$ is determined by approximating a solution to the nonlinear equation
Arguments
C::AbstractMatrix
: Decay basis matrixd::AbstractVector
: Decay curve dataChi2Factor::Real
: Desired $\chi^2$ increase due to regularization
Outputs
X::AbstractVector
: Regularized NNLS solutionmu::Real
: Resulting regularization parameter $\mu$Chi2Factor::Real
: Actual increase $\chi^2(\mu)/\chi^2_{min}$, which will be approximately equal to the inputChi2Factor
DECAES.lsqnonneg_lcurve
— Functionlsqnonneg_lcurve(C::AbstractMatrix, d::AbstractVector)
Returns the regularized NNLS solution, X, of the equation
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 matrixd::AbstractVector
: Decay curve data
Outputs
X::AbstractVector
: Regularized NNLS solutionmu::Real
: Resulting regularization parameter $\mu$Chi2Factor::Real
: Resulting increase in $\chi^2$ relative to unregularized ($\mu = 0$) solution
Extended phase graph algorithm
DECAES.EPGdecaycurve
— FunctionEPGdecaycurve(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 echosflip_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 lengthETL
Main entrypoint function
DECAES.Main.main
— Functionmain(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: