API Reference
DECAES.T2mapOptions
DECAES.T2partOptions
DECAES.EPGdecaycurve
DECAES.T2mapSEcorr
DECAES.T2partSEcorr
DECAES.lcurve_corner
DECAES.lsqnonneg
DECAES.lsqnonneg_chi2
DECAES.lsqnonneg_gcv
DECAES.lsqnonneg_lcurve
DECAES.main
$T_2$-distribution mapping
DECAES.T2mapOptions
— TypeT2mapOptions(; kwargs...)
T2mapOptions(image::Array{T,4}; kwargs...) where {T}
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
legacy::Bool
Perform T2-mapping using legacy algorithms. Default: false
Threaded::Bool
Perform T2-mapping using multiple threads. Default: Threads.nthreads() > 1
MatrixSize::Tuple{Int64, Int64, Int64}
Size of first 3 dimensions of input 4D image. This argument has no default, but is inferred automatically as
size(image)[1:3]
when callingT2mapSEcorr(image; kwargs...)
.nTE::Int64
Number of echoes in input signal. This argument is has no default, but is inferred automatically as
size(image, 4)
when callingT2mapSEcorr(image; kwargs...)
.TE::Real
Interecho spacing (Units: seconds). This argument has no default.
nT2::Int64
Number of T2 times to estimate in the multi-exponential analysis. This argument has no default.
T2Range::Tuple{T, T} where T<:Real
Tuple of min and max T2 values (Units: seconds). This argument has no default.
T1::Real
Assumed value of T1 (Units: seconds). Default: 1.0
Threshold::Real
First echo intensity cutoff for empty voxels. Default: if !legacy 0.0 else 200.0 end
MinRefAngle::Real
Minimum refocusing angle for flip angle optimization (Units: degrees). Default: 50.0
nRefAngles::Int64
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: if !legacy 32 else 8 endnRefAnglesMin::Int64
Initial number of angles to check during flip angle optimization before refinement near likely optima. Setting
nRefAnglesMin
equal tonRefAngles
forces all angles to be checked. Default: if !legacy min(5, nRefAngles) else nRefAngles endReg::String
Regularization routine to use. One of "none", "chi2", "gcv", or "lcurve", representing no regularization,
Chi2Factor
-based Tikhonov regularization, Generalized Cross-Validation method, or L-Curve based regularization, respectively.Chi2Factor::Union{Nothing, T} where T<:Real
Constraint on $\chi^2$ used for regularization when
Reg == "chi2"
. Default: nothingRefConAngle::Real
Refocusing pulse control angle (Units: degrees). Default: 180.0
SetFlipAngle::Union{Nothing, T} where T<:Real
Instead of optimizing flip angle, use
SetFlipAngle
for all voxels (Units: degrees). Default: nothingSaveResidualNorm::Bool
Boolean flag 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::Bool
Boolean flag to include a 4D array of the time domain decay curves resulting from the NNLS fits in the output maps dictionary. Default: false
SaveRegParam::Bool
Boolean flag to include 3D arrays of the regularization parameters $\mu$ and resulting $\chi^2$-factors in the output maps dictionary. Default: false
SaveNNLSBasis::Bool
Boolean flag to include a 5D (or 2D if
SetFlipAngle
is used) array of NNLS basis matrices in the output maps dictionary. Default: falseSilent::Bool
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. If the flip angle is fixed via SetFlipAngle
, however, this is not an issue as only the unique nTE x nT2
2D basis matrix is saved.
See also:
DECAES.T2mapSEcorr
— FunctionT2mapSEcorr(image::Array{T,4}; <keyword arguments>)
T2mapSEcorr(image::Array{T,4}, opts::T2mapOptions{T})
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, nT2 = 40, T2Range = (10e-3, 2.0), Reg = "lcurve", Silent = true); # compute the T2-maps and T2-distribution
julia> maps
Dict{String, Any} with 10 entries:
"echotimes" => [0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09,…
"t2times" => [0.01, 0.0114551, 0.013122, 0.0150315, 0.0172188, 0.01…
"refangleset" => [50.0, 54.1935, 58.3871, 62.5806, 66.7742, 70.9677, 75…
"gdn" => [1.3787e5 177386.0 … 1.95195e5 1.3515e5; 1.8281e5 1.54…
"fnr" => [188.642 204.698 … 216.84 242.163; 183.262 199.053 … 2…
"alpha" => [180.0 180.0 … 180.0 180.0; 180.0 180.0 … 180.0 180.0;…
"gva" => [0.48029 0.554944 … 0.65303 0.595152; 0.510848 0.54559…
"ggm" => [0.0521713 0.0510269 … 0.0494394 0.0503616; 0.052195 0…
"snr" => [152.536 164.471 … 171.872 192.296; 147.898 161.285 … …
"decaybasisset" => [0.0277684 0.0315296 … 0.0750511 0.0751058; 0.0469882 …
See also:
$T_2$-parts and the myelin water fraction
DECAES.T2partOptions
— TypeT2partOptions(; kwargs...)
T2partOptions(t2dist::Array{T,4}; kwargs...) where {T}
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
legacy::Bool
Calculate T2-parts using legacy algorithms. Default: false
Threaded::Bool
Perform T2-parts using multiple threads. Default: Threads.nthreads() > 1
MatrixSize::Tuple{Int64, Int64, Int64}
Size of first 3 dimensions of input 4D T2 distribution. This argument is has no default, but is inferred automatically as
size(t2dist)[1:3]
when callingT2partSEcorr(t2dist; kwargs...)
.nT2::Int64
Number of T2 times to use. This argument has no default.
T2Range::Tuple{T, T} where T<:Real
Tuple of min and max T2 values (Units: seconds). This argument has no default.
SPWin::Tuple{T, T} where T<:Real
Tuple of min and max T2 values of the short peak window (Units: seconds). This argument has no default.
MPWin::Tuple{T, T} where T<:Real
Tuple of min and max T2 values of the middle peak window (Units: seconds). This argument has no default.
Sigmoid::Union{Nothing, T} where T<:Real
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% (Units: seconds). Default: nothingSilent::Bool
Suppress printing to the console. Default: false
See also:
DECAES.T2partSEcorr
— FunctionT2partSEcorr(T2distributions::Array{T,4}; <keyword arguments>)
T2partSEcorr(T2distributions::Array{T,4}, opts::T2partOptions{T})
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; T2Range = (10e-3, 2.0), SPWin = (10e-3, 25e-3), MPWin = (25e-3, 200e-3), Silent = true); # compute T2-parts maps
julia> maps
Dict{String, Any} with 4 entries:
"sgm" => [0.0120849 0.0103704 … 0.01 0.0114649; 0.0107563 0.0110531 … 0.0…
"mfr" => [0.907028 0.869309 … 0.854094 0.898737; 0.889522 0.855133 … 0.86…
"sfr" => [0.0929724 0.130691 … 0.145906 0.101263; 0.110478 0.144867 … 0.1…
"mgm" => [0.0608452 0.0623255 … 0.063191 0.0613871; 0.0621637 0.0632261 ……
See also:
NNLS analysis
DECAES.lsqnonneg
— Functionlsqnonneg(A::AbstractMatrix, b::AbstractVector)
Returns the nonnegative least-squares (NNLS) solution, X, of the equation:
\[X = \mathrm{argmin}_{x \ge 0} ||Ax - b||_2^2\]
Arguments
A::AbstractMatrix
: Left hand side matrix acting onx
b::AbstractVector
: Right hand side vector
Outputs
X::AbstractVector
: NNLS solution
DECAES.lsqnonneg_chi2
— Functionlsqnonneg_chi2(A::AbstractMatrix, b::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} ||Ax - b||_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
A::AbstractMatrix
: Decay basis matrixb::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_gcv
— Functionlsqnonneg_gcv(A::AbstractMatrix, b::AbstractVector)
Returns the regularized NNLS solution, X, of the equation
\[X = \mathrm{argmin}_{x \ge 0} ||Ax - b||_2^2 + \mu^2 ||L x||_2^2\]
where $L$ is the identity matrix and $\mu$ is chosen by the Generalized Cross-Validation (GCV) method.
Details of the GCV method and L-curve theory can be 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
A::AbstractMatrix
: Decay basis matrixb::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
DECAES.lsqnonneg_lcurve
— Functionlsqnonneg_lcurve(A::AbstractMatrix, b::AbstractVector)
Returns the regularized NNLS solution, X, of the equation
\[X = \mathrm{argmin}_{x \ge 0} ||Ax - b||_2^2 + \mu^2 ||L x||_2^2\]
where $L$ is the identity matrix and $\mu$ is chosen by locating the corner of the "L-curve".
Details of L-curve theory and the Generalized Cross-Validation (GCV) method 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
A::AbstractMatrix
: Decay basis matrixb::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
DECAES.lcurve_corner
— Functionlcurve_corner(f, xlow, xhigh)
Find the corner of the L-curve via curvature maximization using Algorithm 1 from:
A. Cultrera and L. Callegaro, “A simple algorithm to find the L-curve corner in the regularization of ill-posed inverse problems”. IOPSciNotes, vol. 1, no. 2, p. 025004, Aug. 2020, doi: 10.1088/2633-1357/abad0d
Extended phase graph algorithm
DECAES.EPGdecaycurve
— FunctionEPGdecaycurve(ETL::Int, α::Real, TE::Real, T2::Real, T1::Real, β::Real)
Computes the normalized echo decay curve for a multi spin echo sequence using the extended phase graph algorithm using the given input parameters.
The sequence of flip angles used is slight generalization of the standard 90 degree excitation pulse followed by 180 degree pulse train. Here, the sequence used is A*90, A*180, A*β, A*β, ...
where A = α/180
accounts for B1 inhomogeneities. Equivalently, the pulse sequence can be written as α/2, α, α * (β/180), α * (β/180), ...
. Note that if α = β = 180
, we recover the standard 90, 180, 180, ...
pulse sequence.
Arguments
ETL::Int
: echo train length, i.e. number of echosα::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)β::Real
: value of Refocusing Pulse Control Angle (Units: degrees)
Outputs
decay_curve::AbstractVector
: normalized echo decay curve with lengthETL
Main entrypoint function
DECAES.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: