params = defaultNavParams()

Define default parameters for data loading, navigator correction and image reconstruction.

Default parameters options are

• slices::Union{Nothing, Vector} - a vector containing the number of the slices to be loaded, nothing means all slices
• echoes::Union{Nothing, Vector} - a vector containing the number of the echoes to be loaded, nothing means all echoes
• rep::Int - repetition to be loaded, the first repetition is 0. It is mandatory to select one
• comp_sensit::Bool - compute the sensitivity maps using the reference scan
• comp_centerline::Bool - use the Spinal Cord Toolbox (SCT) to find the centerlne position
• trust_SCT::Bool - trust SCT or display the resutls and wait for user feedback with the julia REPL
• use_centerline::Bool - use the spinal cord centerline information in the navigator-based correction
• corr_type::String - correction type. Options: "none", "knav", "FFT", "FFT_unwrap"
• FFT_interval::String - interval in mm to be considered for the FFT based approach
• mask_thresh::String - masking threshold: increase for reduced mask size, decrease for extended mask size

Additional required parameters are

• path_imgData::String - path to the image data file in ISMRMRD format
• path_refData::String - path to the reference data file in ISMRMRD format
• path_sensit::String - path to the file where the sensitivity maps will be saved. The file extension must be .mat
• path_noise::String - path to the file where the noise acquisition will be saved. The file extension must be .jld2
• path_results::String - path to the results folder

Additional optional parameters are

• path_niftiMap::String - path to the file where the reconstructed reference data will be saved in nifti format. The file extension must be .nii
• path_centerline::String - path to the folder where the Spinal Cord Toolbox (SCT) centerline results will be saved
• path_physio::String - path to the physiological trace recording in .mat format. The variable should be a two columns vector (1:time [ms], 2:trace) called data. The time should be expressed in seconds from the beginning of the day and contain time points before and after the image acquisiton (at least 4 s).

ISMRMRD reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.26089 SCT reference: https://spinalcordtoolbox.com

runNavPipeline(params::Dict{Symbol, Any})

Run the navigator pipeline. Return reconstructed image and navigator correction output (check NavCorr!).

Arguments

• params::Dict{Symbol, Any} - MRINavigator parameter structure, check defaultNavParams() for info

saveNoise(path_imgData::String, path_noise::String)

Extract the noise acquisition form the image data and save it. Call ExtractNoiseData!, check this function for more info.

Arguments

• path_imgData::String - path to the ISMRMRD file containing the image data
• path_noise::String - path where the noise file will be saved

ISMRMRD reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.26089

loadRawData(params::Dict{Symbol, Any})

Load the raw data file saved in ISMRMRD format in julia using MRIReco.jl Call ExtractNoiseData!, OrderSlices!, ReverseBipolar!, RemoveRef!. Check the specific functions for info.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792 ISMRMRD reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.26089

Arguments

• params::Dict{Symbol, Any} - MRINavigator parameter structure, check defaultNavParams() for info

convertRawToAcq(rawData::::RawAcquisitionData)

Convert raw data to acquisition data using MRIReco.jl, then apply small adjustments. Return acquisition data structure.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl

sensit = CompSensit(acq::AcquisitionData, thresh = 0.13)

Compute the coils sensitivity maps with masking tuned for spinal cord imaging. Use MRICoilSensitivities.jl from MRIReco.jl alternatively.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• acqData::RawAcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• tresh::Float64 - masking threshold: increase for reduced mask size, decrease for extended mask size

mask = CompRoughMask(acq::AcquisitionData, slices::Int64, thresh)

Return a rough mask for multiple slices that may not be homogeneous.

Arguments

• acqData::RawAcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• slices::Int64 - number of slices in acquisition data
• tresh::Float64 - masking threshold: increase for reduced mask size, decrease for extended mask size

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

sensit = ResizeSensit!(sensit::Array{Complex{T},4}, acqMap::AcquisitionData, acqData::AcquisitionData)

Resize and resample the coil sensitivity map to match the acquisition data field of view and resolution. This step is needed for the image reconstruction to run. Image data and reference data must have the same slice center.

Arguments

• sensit::Array{Complex{T},4} - output of CompSensit(acq::AcquisitionData, thresh)
• acqMap::RawAcquisitionData - acquisition data structure obtained converting raw reference data with MRIReco.jl
• acqData::RawAcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

CompResizeSaveSensit(acqMap::AcquisitionData, acqData::AcquisitionData, path_sensit::String)

Compute, resize to the image data dimension and save the coils sensitivity maps with masking tuned for spinal cord imaging. Use MRICoilSensitivities.jl from MRIReco.jl alternatively.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• acqMap::RawAcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• acqData::RawAcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• tresh::Float64 - masking treshold: increase for reduced mask size, decrease for extended mask size

findCenterline(params::Dict{Symbol, Any})

Reconstruct the reference data, call spinal cord toolbox and find spinal cord centerline. If trust_SCT = false in the parameters dictionary the user interaction is required in the Julia REPL.

Arguments

• params::Dict{Symbol, Any} - paramerters dictionary

SCT reference: https://spinalcordtoolbox.com

ReconstructMap(path_ref::String)

Reconstruct the coil sensitivity map using the MRIReco.jl function.

Arguments

• path_rep::String - path of reference data in ISMRMRD format
• thresh::Float64 - masking threshold: increase for reduced mask size, decrease for extended mask size

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792 ISMRMRD reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.26089

ReconstructSaveMap(path_nifti::String, path_ref::String, thresh::Float64)

Reconstruct the coil sensitivity map using the MRIReco.jl function and save it in nifti format without spatial information.

Arguments

• path_nifti::String - path of the nifti file. The file must have .nii extension
• path_rep::String - path of reference data in ISMRMRD format
• thresh::Float64 - masking threshold: increase for reduced mask size, decrease for extended mask size

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792 ISMRMRD reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.26089

callSCT(params::Dict{Symbol, Any})

Call spinal cord toolbox and find spinal cord centerline. If trust_SCT = false in the parameters dictionary the user interaction is required in the Julia REPL

Arguments

• params::Dict{Symbol, Any} - paramerters dictionary

SCT reference: https://spinalcordtoolbox.com

centerline = comp_centerline_pos(addData::additionalNavInput)

Convert and return centerline position from the reference data cordinate to the acquisition data coordinates (number of voxels).

Arguments

• addData::additionalNavInput - mandatory additional data structure obtained with the constructor: additionalNavInput

img = Reconstruct(acqd::AcquisitionData, sensit::Array{Complex{T},4}, noisemat::Union{Array{Complex{T}},Nothing} = nothing)

Call MRIReco.jl reconstruction function and return reconstructed image. Only single repetition in input.

Arguments

• acqData::RawAcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• sensit::Array{Complex{T},4} - coil sensitivity map matrix computed with CompSensit(acq::AcquisitionData, thresh = 0.135)
• noisemat::Union{Array{Complex{T}},Nothing} = nothing - noise data extracted from the raw data structure with ExtractNoiseData!(rawData::RawAcquisitionData)

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

img = directreco(acq::AcquisitionData)

Call MRIReco.jl reconstruction function and return reconstructed image. Reconstruct coils separately.

Arguments

• acqData::RawAcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

niftiSaveImg(img::AbstractArray{T}, acq::AcquisitionData, path_nifti::String)

Save the module of the reconstruction output in nifti format, without spatial information.

Arguments

• img::AbstractArray{T} - reconstruction output
• acq::AcquisitionData - reconstruction input (MRIReco.jl) needed for saving the voxel dimension
• path_nifti::String - path of the nifti file. The file must have .nii extension

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

navOutput = NavCorr!(nav::Array{Complex{T}, 4}, acqData::AcquisitionData, params::Dict{Symbol, Any}, addData::additionalNavInput) where {T}

Compute the navigator-based correction and apply it to the acquisition data. Multiple pipelines are available: "knav", "FFT" and "FFTunwrap". Return navigator trace, spinal cord centerline in the reconstructed image coordinates, Correlation between navigator and belt data for each slice and position of wrapped points for each slices. Please choose the pipeline using the corrtype filed in the params dictionary.

Arguments

• nav::Array{Complex{T}, 4} - navigator profiles obtained with the ExtractNavigator function
• acqData::AcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• params::Dict{Symbol, Any} - navigator correction paramerters dictionary
• addData::additionalNavInput - mandatory additional data structure obtained with the constructor: additionalNavInput

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

wrap_corr!(nav::Array{Float64, 4}, wrapped_points::Array{Int8, 2}, correlation::Union{Array{Float64, 1}, Matrix{Float64}}, slices::Int64)

Unwrap the wrapped points identified with the find_wrapped funtion. These functions can be used only if physiological recording is available.

Arguments

• nav::Array{T, 4} - phase estimates obtained from the navigator data
• wrapped_points::Array{Int8, 2} - position of the wrapped points, output of find_wrapped
• correlation::Union{Array{Float64, 1} - correlation values between the physiological recording the navigator estimates for each slice. Output of find_wrapped
• slices::Int64 - number of slices

find_wrapped(nav::Array{Float64, 4}, nav_time::Array{Float64, 2}, trace::Array{Float64, 2}, slices::Int64)

Identify the position of the wrapped points in the navigator phase estimates. The respiratory belt recording is necessary. Return the position of the wrapped points, the correlation between each navigator slice and the trace data, the aligned and interpolated trace data.

Arguments

• nav::Array{Float64, 4} - navigator phase estimates
• nav_time::Array{Float64, 2} - navigator data timestamps in ms from the beginning of the day, for each slice
• trace::Array{Float64, 2} - physiological trace recording. Two columns vector (1:time [ms], 2:trace). The first column contains the timestamps in ms from the beginning of the day. Include time points before and after the image acquisition (at least 2 s).
• slices::Int64 - number of slices

nav = TE_corr!(nav::Array{T, 4}, acqd::AcquisitionData, dt_nav::Float64, TE_nav::Float64, numsamples::Int64, numechoes::Int64) where {T}

Compute the phase value for the navigator correction basing on the exact acquisition time of each data sample in the line and for each echo. Return a four-dimensional navigator array.

Arguments

• nav::Array{T, 4} - phase estimates obtained from the navigator data
• acqData::AcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• dt_nav::Float64 - time interval between two samples in the frequency encoding direction
• TE_nav::Float64 - echo time of the navigator readout
• numsamples::Int64 - number of samples for each profile
• numechoes::Int64 - number of echoes

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

apply_corr!(nav::Array{T, 4}, acqd::AcquisitionData, numechoes::Int64, numlines::Int64, numsamples::Int64, numslices::Int64) where {T}

Apply the navigator-based correction to the acquisition data structure obtained loading the raw data with MRIReco.jl. After applying the correction the image should be reconstructed. Use the reconstruct function.

Arguments

• nav::Array{T, 4} - phase estimates obtained from the navigator data
• acqd::AcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• numechoes::Int64 - number of echoes
• numlines::Int64 - number of lines (profiles) for each slice and echo
• numsamples::Int64 - number of samples for each profile
• numslices::Int64 - number of slices

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

OrderSlices!(rawData::RawAcquisitionData)

Spatially order the slices in the MRIReco.jl raw data structure. The slices are ordered basing on the position coordinates saved in each profile. If these are not present the slices can not be ordered.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl

flags = ExtractFlags(rawData::RawAcquisitionData)

Extract the acquisition flags from the MRIReco.jl raw data profiles. Return a 31-element vector for each profile.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl

noisemat = ExtractNoiseData!(rawData::RawAcquisitionData, flags::Array{Int64})

Extract and return the noise acquisition from the MRIReco.jl raw data. The noise acquisition is usually the first profile with slice = 0, contrast = 0, repetition = 0. The noise profile should have the 19th flag element equal to 1. Check this with ExtractFlags if errors occur.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl

ReverseBipolar!(rawData::RawAcquisitionData)

Reflect the MRIReco.jl raw data profiles for bipolar acquisition.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl

RemoveRef!(rawData::RawAcquisitionData, slices::Union{Vector{Int64}, Nothing}, echoes::Union{Vector{Int64}, Nothing})

Remove reference data from acquisitions with phase stabilization on Siemens scanners. To be applied before the navigator-based correction. Necessary when the reference data is acquired before the image data. Make sure that this is needed on your data checking the time stamps. For Siemens: It is possible to read raw data with mapVBVD in Matlab. The reference data to be removed is called phasestabRef in mapVBVD. Not robust for sequences with concatenations > 1. Not robust to repeated calls, modifies rawData.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792 mapVBVD reference: https://github.com/CIC-methods/FID-A/blob/master/inputOutput/mapVBVD/README.md

Arguments

• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl

CopyTE!(rawData::RawAcquisitionData, acqData::AcquisitionData)

Copy the TE values from the MRIReco.jl raw data structure to the acquisition data structure.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl
• acqData::AcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl

AdjustSubsampleIndices!(acqData::AcquisitionData)

Add subsamples indices in the MRIReco.jl acquisition data structure. Needed when converting data not acquired in the first repetition.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• acqData::AcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl

(nav, nav_time) = ExtractNavigator(rawData::RawAcquisitionData, slices::Union{Vector{Int64}, Nothing})

Extract the navigator profiles from the MRIReco.jl raw data structure. These are registered with the same indices (contract, slice, encoding step) as the image data for the first echo time. Return a navigator array and a navigator time array. The navigator array has four dimensions in the following order: k-space samples, coils, k-space lines, slices. Effective only if the navigator profile was acquired after the first image profile.

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Arguments

• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl

SelectEcho!(acqd, idx_echo)

Extract one or more echoes from the acquisition data structure

Arguments

• acqd::AcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• idx_echo::Vector{Int64} - vector containing the indexes of the echoes to be selected (starting from 0)

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

SelectSlice!(acqd, nav, nav_time, idx_slice)

Extract one or more echoes from the acquisition data structure

Arguments

• acqd::AcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl
• idx_slice::Vector{Int64} - vector containing the indexes of the slices to be selected (starting from 0, downer slice)

Optional arguments with default value = nothing

• nav::Union{Array{Complex{T}, 4}, Nothin} = nothing - navigator profiles obtained with the ExtractNavigator function
• nav_time::Union{Array{Complex{Float32}, 2}, Nothing} - time stamps for the navigator data obtained with ExtractNavigator (in ms from the beginning of the day)

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792

Data = additionalNavInput(
    noisemat::Array{Complex{Float32}, 2},
    rawData::RawAcquisitionData,
    acqData::AcquisitionData,
    acqMap::Union{AcquisitionData, Nothing} = nothing,
    nav_time::Union{Array{Complex{Float32}, 2}, Nothing} = nothing,
    trace::Union{Matrix{Float64}, Nothing} = nothing,
    centerline::Union{Vector{Float64}, Nothing} = nothing)

Construct the additional data structure that is needed as input to navCorr!

Arguments

• noisemat::Array{Complex{Float32}, 2} - noise data obtained with ExtractNoiseData!
• rawData::RawAcquisitionData - raw data structure obtained loading raw data with MRIReco.jl
• acqData::AcquisitionData - acquisition data structure obtained converting raw data with MRIReco.jl

Optional arguments with default value = nothing

• acqMap::Union{AcquisitionData, Nothing} = nothing - acquisition data structure obtained converting reference data with MRIReco.jl
• nav_time::Union{Array{Complex{Float32}, 2}, Nothing} - time stamps for the navigator data obtained with ExtractNavigator (in ms from the beginning of the day)
• trace::Union{Matrix{Float64}, Nothing} - respiratory trace time stamps and values in matrix with two colunms (1:time [ms], 2:trace). Include time points before and after the image acquisition (at least 2 s).
• centerline::Union{Vector{Float64}, Nothing} - coordinates of the spinal cord ceterline obtained with callSCT

MRIReco reference: https://onlinelibrary.wiley.com/doi/epdf/10.1002/mrm.28792