I/O functions

spherical_mean(
    image_file::String, 
    save::Bool=true, 
    acq_files::String...
)

Perform direction average on input DWI images image_file and return an MRI object with normalized spherical mean signal and associated imaging protocol. image_file is the full path of the DWI image file; save indicates whether to save the smt and normalized smt image volumes and protocol. If saving the files, nifti and text file (.btable) will be saved in the same path as the input data. Finall, variable number of acq_files are text files that tell you acquistion parameters of each DWI in the image_file. Accepted file extensions are .bvals/.bvecs/.techo/.tdelta/.tsmalldel for b-values, gradient directions, echo times, diffusion gradient seperation and duration times.

Besides .bvals/.bvecs for conventional modelling, .tdelta/.tsmalldel files are needed for any models that estimate size, e.g. axon diameter, soma radius. .techo is needed if your data is collected with multiple echo-time and you want to do combined-diffusion relaxometry modelling. The format of a .tdelta/.tsmalldel/.techo file is similar to a .bvals file (a vector with the length equal to the number of DWI volumes). Unit in the .tdelta/.tsmalldel/.techo file is ms.

spherical_fit(
    image_file::String, 
    mask_file::String,
    Lmax::Int,
    tissue_type::String,
    save_dir::String, 
    acq_files::String...
)

spherical_fit(
    image_file::String, 
    mask_file::String,
    sigma_file::String,
    Lmax::Int,
    tissue_type::String,
    save_dir::String, 
    acq_files::String...
)

This function estimates the Spherical Harmonic (SH) coefficents of the input DW images using linear least squares and extract the rotional invariants at an order up to Lmax for later microstructure model fitting.

Arguments:

• image_file: full file path of the input DWI volumes
• mask_file: full file path of the brain mask
• sigma_file: full file path of the noise map; if provided, simple correction will be applied to the measurements to reduce Rician bias before the LLS fit of SH coefficents.
• Lmax: The maximum order to extract rotational invariants; set Lmax = 0 for models using only the spherical mean signals, e.g. SANDI, and set Lmax = 2 or 4 for models of the white matter using higher order rotional invariants, e.g. SMI.
• tissuetype: "invivo" or "ex_vivo"; this is used along with the number of gradient directions to help decide the maximum SH order of each b-shell for the SH fitting.
• save_dir: the path where outputs will be saved
• acq_files:: full file path to the acquistion files assoiated with the DWI volumes. Provide at least the .bvals/.bvecs files for standard microstructure model fitting. Accepted file extensions are .bvals/.bvecs/.techo/.tdelta/.tsmalldel for b-values, gradient directions, echo times, diffusion gradient seperation and duration times.

          The format of a .tdelta/.tsmalldel/.techo file is similar to a .bvals file (a vector with the length equal to the number of DWI volumes). Unit in the .tdelta/.tsmalldel/.techo file is ms. 
            .tdelta/.tsmalldel files are needed for any models that estimate size, e.g. axon diameter, soma radius.
            .techo is needed if your data is collected with multiple echo-time and you want to do combined diffusion-relaxometry modelling.

Returns:

• Sl_norm: a 4D Array containing the rotional invariants Sl normalized by the b=0 invariant with minimal TE
• snr_b0: a 3D Array containing the SNR map estimated from the b=0 measurements with minimal TE
• protocol: A Protocol type object containing the relevant parameters associated with each volume in Sl_norm
• mask: An MRI type object with nifti header information and Array of brain mask

Besides returning necessary variables for model fitting, files are saved under save_dir for reuse (naming examples with Lmax=2): Sllmax2norm.nii.gz: the normalized measurements that are used for model fitting snrb0.nii.gz : the SNR map that can be used in setting up neural network estimators trained with realistic noise distribution Sllmax2.btable : the protocol

Slm.nii.gz : the SH coefficents of all the shells Sllmax2.nii.gz : the rotational invariants before normalization sigmaest.nii.gz : the sigma maps estimated from SH fit for each b-shell

dMRI(nifti::MRI, 
tdelta::Vector{Float64}, 
dsmalldel::Vector{Float64}, 
techo::Vector{Float64}, 
smt::Bool,
nmeas::Vector{Int}
lmeas::Vector{Int})

Return a dMRI Type object with MRI object nifti, and additional volume-wise experimental settings tdelta, tsmalldel, techo, smt for identifing smt signals, nmeas for the number of measurements, and lmeas for the order of rotational invariants.

Protocol(
bval::Vector{Float64}
techo::Vector{Float64}
tdelta::Vector{Float64}
tsmalldel::Vector{Float64}
nmeas::Vector{Float64}
lmeas::Vector{Float64}
gvec::Vector{Float64}
bvec::Matrix{Float64}
nmeas::Vector{Float64}
)

Return a Protocol Type object to hold parameters in acquisition protocol relavent for modelling including b-values, tcho times, diffusion gradient seperation, duration, strengh, direction and the number of measurements. Unit convention: most text files use s/mm^2 for b-values and ms for time while they are converted to SI unit in the Protocol. b-values (s/m^2); time (s); size (m); G (T/m)

Protocol(
    filename::String
)

Return a Protocol Type object from a b-table file generated from spherical_mean function.

Protocol(
    bval::Vector{Float64},
    techo::Vector{Float64},
    tdelta::Vector{Float64},
    tsmalldel::Vector{Float64},
)

Calculate gvec and return a Ptotocol Type object from provided parameters; other fields are not useful

Protocol(
    dmri::dMRI
)

Return a Protocol Type object from a dMRI object.

dmri_write(dmri::dMRI, datapath::String, filename::String)

Write the nifti volume in a dMRI object to nifti file and associated protocol as b-table text files in the given datapath and filename.