KomaMRIBase

`Scanner`-related functions

julia

sys = Scanner(B0, B1, Gmax, Smax, ADC_Δt, seq_Δt, GR_Δt, RF_Δt,
    RF_ring_down_T, RF_dead_time_T, ADC_dead_time_T)

The Scanner struct. It contains hardware limitations of the MRI resonator. It is an input for the simulation.

Arguments

B0: (::Real, =1.5, [T]) main magnetic field strength
B1: (::Real, =10e-6, [T]) maximum RF amplitude
Gmax: (::Real, =60e-3, [T/m]) maximum gradient amplitude
Smax: (::Real, =500, [mT/m/ms]) gradient's maximum slew-rate
ADC_Δt: (::Real, =2e-6, [s]) ADC raster time
seq_Δt: (::Real, =1e-5, [s]) sequence-block raster time
GR_Δt: (::Real, =1e-5, [s]) gradient raster time
RF_Δt: (::Real, =1e-6, [s]) RF raster time
RF_ring_down_T: (::Real, =20e-6, [s]) RF ring down time
RF_dead_time_T: (::Real, =100e-6, [s]) RF dead time
ADC_dead_time_T: (::Real, =10e-6, [s]) ADC dead time

Returns

sys: (::Scanner) Scanner struct

Examples

julia

julia> sys = Scanner()

julia> sys.B0

source

`Phantom`-related functions

KomaMRIBase.Phantom Type

julia

obj = Phantom(name, x, y, z, ρ, T1, T2, T2s, Δw, Dλ1, Dλ2, Dθ, motion)

The Phantom struct. Most of its field names are vectors, with each element associated with a property value representing a spin. This struct serves as an input for the simulation.

Arguments

name: (::String) phantom name
x: (::AbstractVector{T<:Real}, [m]) spin x-position vector
y: (::AbstractVector{T<:Real}, [m]) spin y-position vector
z: (::AbstractVector{T<:Real}, [m]) spin z-position vector
ρ: (::AbstractVector{T<:Real}) spin proton density vector
T1: (::AbstractVector{T<:Real}, [s]) spin T1 parameter vector
T2: (::AbstractVector{T<:Real}, [s]) spin T2 parameter vector
T2s: (::AbstractVector{T<:Real}, [s]) spin T2s parameter vector
Δw: (::AbstractVector{T<:Real}, [rad/s]) spin off-resonance parameter vector
Dλ1: (::AbstractVector{T<:Real}) spin Dλ1 (diffusion) parameter vector
Dλ2: (::AbstractVector{T<:Real}) spin Dλ2 (diffusion) parameter vector
Dθ: (::AbstractVector{T<:Real}) spin Dθ (diffusion) parameter vector
motion: (::Union{NoMotion, Motion{T<:Real} MotionList{T<:Real}}) motion

Returns

obj: (::Phantom) Phantom struct

Examples

julia

julia> obj = Phantom(x=[0.0])

julia> obj.ρ

source

KomaMRIBase.brain_phantom2D Function

julia

phantom = brain_phantom2D(;axis="axial", ss=4)

Creates a two-dimensional brain Phantom struct. Default ss=4 sample spacing is 2 mm. Original file (ss=1) sample spacing is .5 mm.

References

B. Aubert-Broche, D.L. Collins, A.C. Evans: "A new improved version of the realistic digital brain phantom" NeuroImage, in review - 2006
B. Aubert-Broche, M. Griffin, G.B. Pike, A.C. Evans and D.L. Collins: "20 new digital brain phantoms for creation of validation image data bases" IEEE TMI, in review - 2006
https://brainweb.bic.mni.mcgill.ca/brainweb/tissue_mr_parameters.txt

Keywords

axis: (::String, ="axial", opts=["axial", "coronal", "sagittal"]) orientation of the phantom
ss: (::Integer or ::Vector{Integer}, =4) subsampling parameter for all axes if scaler, per axis if 2 element vector [ssx, ssy]
us: (::Integer or ::Vector{Integer}, =1) upsampling parameter for all axes if scaler, per axis if 2 element vector [usx, usy], if used ss is set to ss=1
tissue_properties: (::Dict, =Dict()) phantom tissue properties in SI units considering the available tissues

Returns

obj: (::Phantom) Phantom struct

Examples

julia

julia> obj = brain_phantom2D(; axis="sagittal", ss=1)

julia> obj = brain_phantom2D(; axis="axial", us=[1, 2])

julia> phantom_values = 
    Dict(
        # ρ, T1, T2, T2*, Δw
        "CSF"           => [1,      2.569,  0.329,  0.058,  0],
        "GM"            => [0.86,   0.833,  0.083,  0.069,  0],
        "WM"            => [0.77,   0.500,  0.070,  0.061,  0],
        "FAT1"          => [0,      0,      0,      0,      0],
        "MUSCLE"        => [0,      0,      0,      0,      0],
        "SKIN/MUSCLE"   => [0,      0,      0,      0,      0],
        "SKULL"         => [0,      0,      0,      0,      0],
        "VESSELS"       => [0,      0,      0,      0,      0],
        "FAT2"          => [0,      0,      0,      0,      0],
        "DURA"          => [0,      0,      0,      0,      0],
        "MARROW"        => [0,      0,      0,      0,      0])
julia> obj = brain_phantom2D(; tissue_properties=phantom_values)

julia> plot_phantom_map(obj, :ρ)

source

KomaMRIBase.brain_phantom3D Function

julia

obj = brain_phantom3D(; ss=4, us=1, start_end=[160,200])

Creates a three-dimentional brain Phantom struct. Default ss=4 sample spacing is 2 mm. Original file (ss=1) sample spacing is .5 mm.

References

B. Aubert-Broche, D.L. Collins, A.C. Evans: "A new improved version of the realistic digital brain phantom" NeuroImage, in review - 2006
B. Aubert-Broche, M. Griffin, G.B. Pike, A.C. Evans and D.L. Collins: "20 new digital brain phantoms for creation of validation image data bases" IEEE TMI, in review - 2006
https://brainweb.bic.mni.mcgill.ca/brainweb/tissue_mr_parameters.txt

Keywords

ss: (::Integer or ::Vector{Integer}, =4) subsampling parameter for all axes if scaler, per axis if 3 element vector [ssx, ssy, ssz]
us: (::Integer or ::Vector{Integer}, =1) upsampling parameter for all axes if scaler, per axis if 3 element vector [usx, usy, usz]
start_end: (::Vector{Integer}, =[160,200]) z index range of presampled phantom, 180 is center
tissue_properties: (::Dict, =Dict()) phantom tissue properties in SI units considering the available tissues

Returns

obj: (::Phantom) 3D Phantom struct

Examples

julia

julia> obj = brain_phantom3D(; ss=5)

julia> obj = brain_phantom3D(; us=[2, 2, 1])

julia> phantom_values = 
    Dict(
        # ρ, T1, T2, T2*, Δw
        "CSF"           => [1,      2.569,  0.329,  0.058,  0],
        "GM"            => [0.86,   0.833,  0.083,  0.069,  0],
        "WM"            => [0.77,   0.500,  0.070,  0.061,  0],
        "FAT1"          => [0,      0,      0,      0,      0],
        "MUSCLE"        => [0,      0,      0,      0,      0],
        "SKIN/MUSCLE"   => [0,      0,      0,      0,      0],
        "SKULL"         => [0,      0,      0,      0,      0],
        "VESSELS"       => [0,      0,      0,      0,      0],
        "FAT2"          => [0,      0,      0,      0,      0],
        "DURA"          => [0,      0,      0,      0,      0],
        "MARROW"        => [0,      0,      0,      0,      0])
julia> obj = brain_phantom3D(; tissue_properties=phantom_values)

julia> plot_phantom_map(obj, :ρ)

source

KomaMRIBase.pelvis_phantom2D Function

julia

obj = pelvis_phantom2D(; ss=4, us=1)

Creates a two-dimensional pelvis Phantom struct. Default ss=4 sample spacing is 2 mm. Original file (ss=1) sample spacing is .5 mm.

Keywords

ss: (::Integer or ::Vector{Integer}, =4) subsampling parameter for all axes if scaler, per axis if 2 element vector [ssx, ssy]
us: (::Integer or ::Vector{Integer}, =1) upsampling parameter for all axes if scaler, per axis if 2 element vector [usx, usy]

Returns

obj: (::Phantom) Phantom struct

Examples

julia

julia> obj = pelvis_phantom2D(; ss=2])

julia> obj = pelvis_phantom2D(; us=[1, 2])

julia> pelvis_phantom2D(obj, :ρ)

source

KomaMRIBase.heart_phantom Function

julia

obj = heart_phantom(
    circumferential_strain, radial_strain, rotation_angle; 
    heart_rate, asymmetry
)

Heart-like LV 2D phantom. The variable circumferential_strain and radial_strain are for streching (if positive) or contraction (if negative). rotation_angle is for rotation.

Keywords

circumferential_strain: (::Real, =-0.3) contraction parameter. Between -1 and 1
radial_strain: (::Real, =-0.3) contraction parameter. Between -1 and 1
rotation_angle: (::Real, =15.0, [º]) maximum rotation angle
heart_rate: (::Real, =60, [bpm]) heartbeat frequency
temporal_asymmetry: (::Real, =0.2) time fraction of the period in which the systole occurs. Therefore, diastole lasts for period * (1 - temporal_asymmetry)

Returns

obj: (::Phantom) Heart-like LV phantom struct

source

`Motion`-related functions

KomaMRIBase.NoMotion Type

julia

nomotion = NoMotion()

NoMotion struct. It is used to create static phantoms.

Returns

nomotion: (::NoMotion) NoMotion struct

Examples

julia

julia> nomotion = NoMotion()

source

KomaMRIBase.Motion Type

julia

motion = Motion(action)
motion = Motion(action, time)
motion = Motion(action, time, spins)

Motion struct. It defines the motion, during a certain time interval, of a given group of spins. It is composed by three fields: action, which defines the motion itself, time, which accounts for the time during which the motion takes place, and spins, which indicates the spins that are affected by that motion.

Arguments

action: (::AbstractAction{T<:Real}) action, such as Translate or Rotate
time: (::TimeCurve{T<:Real}, =TimeRange(0.0)) time information about the motion
spins: (::AbstractSpinSpan, =AllSpins()) spin indexes affected by the motion

Returns

motion: (::Motion) Motion struct

Examples

julia

julia> motion =  Motion(
            action = Translate(0.01, 0.0, 0.02),
            time = TimeRange(0.0, 1.0),
            spins = SpinRange(1:10)
       )

source

KomaMRIBase.MotionList Type

julia

motionlist = MotionList(motions...)

MotionList struct. The other option, instead of NoMotion, is to define a dynamic phantom by means of the MotionList struct. It is composed by one or more Motion instances.

Arguments

motions: (::Vector{Motion{T<:Real}}) vector of Motion instances

Returns

motionlist: (::MotionList) MotionList struct

Examples

julia

julia>  motionlist = MotionList(
            Motion(
                action = Translate(0.01, 0.0, 0.02),
                time = TimeRange(0.0, 1.0),
                spins = AllSpins()
            ),
            Motion(
                action = Rotate(0.0, 0.0, 45.0),
                time = Periodic(1.0),
                spins = SpinRange(1:10)
            )
        )

source

KomaMRIBase.get_spin_coords Function

julia

x, y, z = get_spin_coords(motion, x, y, z, t)

Calculates the position of each spin at a set of arbitrary time instants, i.e. the time steps of the simulation. For each dimension (x, y, z), the output matrix has rows and length(t) columns.

Arguments

motion: (::Union{NoMotion, Motion{T<:Real} MotionList{T<:Real}}) phantom motion
x: (::AbstractVector{T<:Real}, [m]) spin x-position vector
y: (::AbstractVector{T<:Real}, [m]) spin y-position vector
z: (::AbstractVector{T<:Real}, [m]) spin z-position vector
t: horizontal array of time instants

Returns

x, y, z: (::Tuple{AbstractArray, AbstractArray, AbstractArray}) spin positions over time

source

`Motion`constructors

KomaMRIBase.translate Function

julia

tr = translate(dx, dy, dz, time, spins)

Arguments

dx: (::Real, [m]) translation in x
dy: (::Real, [m]) translation in y
dz: (::Real, [m]) translation in z
time: (::TimeCurve{T<:Real}) time information about the motion
spins: (::AbstractSpinSpan) spin indexes affected by the motion

Returns

tr: (::Motion) Motion struct

Examples

julia

julia> tr = translate(0.01, 0.02, 0.03, TimeRange(0.0, 1.0), SpinRange(1:10))

source

KomaMRIBase.rotate Function

julia

rt = rotate(pitch, roll, yaw, spins)

Arguments

pitch: (::Real, [º]) rotation in x
roll: (::Real, [º]) rotation in y
yaw: (::Real, [º]) rotation in z
time: (::TimeCurve{T<:Real}) time information about the motion
spins: (::AbstractSpinSpan) spin indexes affected by the motion

Keywords

center: (::NTuple{3,Real} or ::CenterOfMass) center of rotation, given in global coordinates. Default is center of mass.

Returns

rt: (::Motion) Motion struct with Rotate action

Examples

julia

julia> rt = rotate(15.0, 0.0, 20.0, TimeRange(0.0, 1.0), SpinRange(1:10))

source

KomaMRIBase.heartbeat Function

julia

hb = heartbeat(circumferential_strain, radial_strain, longitudinal_strainl, time, spins)

Arguments

circumferential_strain: (::Real) contraction parameter
radial_strain: (::Real) contraction parameter
longitudinal_strain: (::Real) contraction parameter
time: (::TimeCurve{T<:Real}) time information about the motion
spins: (::AbstractSpinSpan) spin indexes affected by the motion

Returns

hb: (::Motion) Motion struct with HeartBeat action

Examples

julia

julia> hb = heartbeat(-0.3, -0.2, 0.0, TimeRange(0.0, 1.0), SpinRange(1:10))

source

KomaMRIBase.path Function

julia

pt = path(dx, dy, dz, time, spins)

Arguments

dx: (::AbstractArray{T<:Real}, [m]) displacements in x
dy: (::AbstractArray{T<:Real}, [m]) displacements in y
dz: (::AbstractArray{T<:Real}, [m]) displacements in z
time: (::TimeCurve{T<:Real}) time information about the motion
spins: (::AbstractSpinSpan) spin indexes affected by the motion

Returns

pt: (::Motion) Motion struct with Path action

Examples

julia

julia> pt = path(
          [0.01 0.02; 0.02 0.03], 
          [0.02 0.03; 0.03 0.04], 
          [0.03 0.04; 0.04 0.05], 
          TimeRange(0.0, 1.0), 
          SpinRange(1:10)
       )

source

KomaMRIBase.flowpath Function

julia

fp = flowpath(dx, dy, dz, spin_reset, time, spins)

Arguments

dx: (::AbstractArray{T<:Real}, [m]) displacements in x
dy: (::AbstractArray{T<:Real}, [m]) displacements in y
dz: (::AbstractArray{T<:Real}, [m]) displacements in z
spin_reset: (::AbstractArray{Bool}) reset spin state flags
time: (::TimeCurve{T<:Real}) time information about the motion
spins: (::AbstractSpinSpan) spin indexes affected by the motion

Returns

fp: (::Motion) Motion struct with FlowPath action

Examples

julia

julia> fp = flowpath(
          [0.01 0.02; 0.02 0.03], 
          [0.02 0.03; 0.03 0.04], 
          [0.03 0.04; 0.04 0.05], 
          [false false; false true],
          TimeRange(0.0, 1.0), 
          SpinRange(1:10)
       )

source

`AbstractAction` types

KomaMRIBase.Translate Type

julia

t = Translate(dx, dy, dz)

Translate struct. It produces a linear translation. Its fields are the final displacements in the three axes (dx, dy, dz).

Arguments

dx: (::Real, [m]) translation in x
dy: (::Real, [m]) translation in y
dz: (::Real, [m]) translation in z

Returns

t: (::Translate) Translate struct

Examples

julia

julia> t = Translate(dx=0.01, dy=0.02, dz=0.03)

source

KomaMRIBase.Rotate Type

julia

r = Rotate(pitch, roll, yaw, center=CenterOfMass())

Rotate struct. It produces a rotation in the three axes: x (pitch), y (roll), and z (yaw). We follow the RAS (Right-Anterior-Superior) orientation, and the rotations are applied following the right-hand rule (counter-clockwise):

The applied rotation matrix is obtained as follows:

Arguments

pitch: (::Real, [º]) rotation in x
roll: (::Real, [º]) rotation in y
yaw: (::Real, [º]) rotation in z
center: (::NTuple{3,Real} or ::CenterOfMass) optional center of rotation, given in global coordinates. Default is center of mass.

Notes

Rotations are applied around the point specified in center. If omitted, the rotation is centered at the phantom’s center of mass.
If center is not ::CenterOfMass, the rotation center is interpreted as a fixed point in space (absolute/global coordinates).
This design ensures that consecutive or inverse rotations behave consistently and predictably, since the rotation center does not change with object transformations.

Returns

r: (::Rotate) Rotate struct

Examples

julia

julia> r = Rotate(pitch=15.0, roll=0.0, yaw=20.0)

julia> r = Rotate(pitch=0.0, roll=45.0, yaw=0.0, center=(5e-3,0.0,0.0))
# Rotates around a point 5 mm to the right of the center of mass

source

KomaMRIBase.HeartBeat Type

julia

h = HeartBeat(circumferential_strain, radial_strain, longitudinal_strain)

HeartBeat struct. It produces a heartbeat-like motion, characterised by three types of strain: circumferential, radial and longitudinal

Arguments

circumferential_strain: (::Real) contraction parameter
radial_strain: (::Real) contraction parameter
longitudinal_strain: (::Real) contraction parameter

Returns

h: (::HeartBeat) HeartBeat struct

Examples

julia

julia> h = HeartBeat(circumferential_strain=-0.3, radial_strain=-0.2, longitudinal_strain=0.0)

source

KomaMRIBase.Path Type

julia

p = Path(dx, dy, dz)

Path struct. For this action (and for FlowPath), motion is not defined solely on the basis of three numerical parameters, one for each spatial direction, as occurs for the Translate, Rotate and HeartBeat actions.

For this action, it is necessary to define motion for each spin independently, in x (dx), y (dy) and z (dz). dx, dy and dz are now three matrixes, of () each. This means that each row corresponds to a spin trajectory over a set of discrete time instants.

Note

*When creating a motion with Flow or FlowPath, you must make sure that the number of rows of the matrices dx, dy and dz matches the number of spins that are affected by the motion.

Remember that the range of spins affected by a motion is defined by the spins field of the Motion struct

example:

julia

julia> motion = Motion(
    action = Path(
        dx=[0.01 0.02; 0.02 0.03],  # 2 rows
        dy=[0.02 0.03; 0.03 0.04], 
        dz=[0.03 0.04; 0.04 0.05]),
    time = TimeRange(0.0, 1.0),
    spins = SpinRange(1:2)          # 2 spins
)

Arguments

dx: (::AbstractArray{T<:Real}, [m]) displacements in x
dy: (::AbstractArray{T<:Real}, [m]) displacements in y
dz: (::AbstractArray{T<:Real}, [m]) displacements in z

Returns

p: (::Path) Path struct

Examples

julia

julia> p = Path(
           dx=[0.01 0.02; 0.02 0.03], 
           dy=[0.02 0.03; 0.03 0.04], 
           dz=[0.03 0.04; 0.04 0.05]
       )

source

KomaMRIBase.FlowPath Type

julia

f = FlowPath(dx, dy, dz, spin_reset)

FlowPath struct. This action is the same as Path, except that it includes an additional field, called spin_reset, which accounts for spins leaving the volume and being remapped to another input position. When this happens, the magnetization state of these spins must be reset during the simulation.

As with the dx, dy and dz matrices, spin_reset has a size of ().

Arguments

dx: (::AbstractArray{T<:Real}, [m]) displacements in x
dy: (::AbstractArray{T<:Real}, [m]) displacements in y
dz: (::AbstractArray{T<:Real}, [m]) displacements in z
spin_reset: (::AbstractArray{Bool}) reset spin state flags

Returns

f: (::FlowPath) FlowPath struct

Examples

julia

julia> f = FlowPath(
           dx=[0.01 0.02; 0.02 0.03], 
           dy=[0.02 0.03; 0.03 0.04], 
           dz=[0.03 0.04; 0.04 -0.04],
           spin_reset=[false false; false true]
       )

source

`TimeCurve` types and related functions

KomaMRIBase.TimeCurve Type

julia

timecurve = TimeCurve(t, t_unit, periodic, periods)

TimeCurve struct. It is a specialized type that defines a time curve, which represents the temporal behavior of motion. This curve is defined by two vectors: t and t_unit, which represent the horizontal (x-axis) and vertical (y-axis) axes of the curve, respectively. To some extent, this curve can be associated with animation curves, commonly found in software for video editing, 3D scene creation, or video game development.

Additionally, the TimeCurve struct contains two more fields, independent of each other: periodic is a Boolean that indicates whether the time curve should be repeated periodically. periods contains as many elements as repetitions are desired in the time curve. Each element specifies the scaling factor for that repetition.

Arguments

t: (::AbstractVector{<:Real}, [s]) time vector
t_unit: (::AbstractVector{<:Real}) y vector, it needs to be scaled between 0 and 1. 0 represents the start of the motion, while 1 represents the end. The values in between represent the intermediate states of the motion.
periodic: (::Bool, =false) indicates whether the time curve should be periodically repeated
periods: (::Union{<:Real,AbstractVector{<:Real}}, =1.0): represents the relative duration of each period with respect to the baseline duration defined by t[end] - t[1]. In other words, it acts as a scaling factor to lengthen or shorten specific periods. This allows for the creation of patterns such as arrhythmias or other variations in periodicity.

Returns

timecurve: (::TimeCurve) TimeCurve struct

Examples

Non-periodic motion with a single repetition:

julia

julia> timecurve = TimeCurve(t=[0.0, 0.2, 0.4, 0.6], t_unit=[0.0, 0.2, 0.5, 1.0])

Periodic motion with a single repetition:

julia

julia> timecurve = TimeCurve(t=[0.0, 0.2, 0.4, 0.6], t_unit=[0.0, 1.0, 1.0, 0.0], periodic=true)

Non-periodic motion with multiple repetitions:

julia

julia> timecurve = TimeCurve(t=[0.0, 0.2, 0.4, 0.6], t_unit=[0.0, 1.0, 1.0, 0.0], periods=[1.0, 0.5, 1.5])

Periodic motion with multiple repetitions:

julia

julia> timecurve = TimeCurve(t=[0.0, 0.2, 0.4, 0.6], t_unit=[0.0, 1.0, 1.0, 0.0], periods=[1.0, 0.5, 1.5], periodic=true)

source

KomaMRIBase.TimeRange Function

julia

timerange = TimeRange(t_start, t_end)

The TimeRange function is a custom constructor for the TimeCurve struct. It allows defining a simple time interval, with start and end times.

Arguments

t_start: (::Real, [s], =0.0) start time
t_end: (::Real, [s], =1.0) end time

Returns

timerange: (::TimeCurve) TimeCurve struct

Examples

julia

julia> timerange = TimeRange(t_start=0.6, t_end=1.4)

source

KomaMRIBase.Periodic Function

julia

periodic = Periodic(period, asymmetry)

The Periodic function is a custom constructor for the TimeCurve struct. It allows defining time intervals that repeat periodically with a triangular period. It includes a measure of asymmetry in order to recreate a asymmetric period.

Arguments

period: (::Real, [s], =1.0) period duration
asymmetry: (::Real, =0.5) temporal asymmetry factor. Between 0 and 1.

Returns

periodic: (::TimeCurve) TimeCurve struct

Examples

julia

julia> periodic = Periodic(period=1.0, asymmetry=0.2)

source

`AbstractSpinSpan` types

KomaMRIBase.AllSpins Type

julia

allspins = AllSpins()

AllSpins struct. It is a specialized type that inherits from AbstractSpinSpan and is used to cover all the spins of a phantom.

Returns

allspins: (::AllSpins) AllSpins struct

Examples

julia

julia> allspins = AllSpins()

source

KomaMRIBase.SpinRange Type

julia

spinrange = SpinRange(range)

SpinRange struct. It is a specialized type that inherits from AbstractSpinSpan and is used to select a certain range and number of spins.

Arguments

range: (::AbstractVector) spin id's. This argument can be a Range, a Vector or a BitVector

Returns

spinrange: (::SpinRange) SpinRange struct

Examples

julia

julia> spinrange = SpinRange(1:10)
julia> spinrange = SpinRange([1, 3, 5, 7])
julia> spinrange = SpinRange(obj.x .> 0)

source

`Sequence`-related functions

KomaMRIBase.Sequence Type

julia

seq = Sequence()
seq = Sequence(GR)
seq = Sequence(GR, RF)
seq = Sequence(GR, RF, ADC)
seq = Sequence(GR, RF, ADC, DUR)
seq = Sequence(GR::Array{Grad,1})
seq = Sequence(GR::Array{Grad,1}, RF::Array{RF,1})
seq = Sequence(GR::Array{Grad,1}, RF::Array{RF,1}, A::ADC, DUR, DEF)

The Sequence struct. It contains events of an MRI sequence. Most field names (except for the DEF field) consist of matrices or vectors, where each column index represents a sequence block. This struct serves as an input for the simulation.

Arguments

GR: (::Matrix{Grad}) gradient matrix. Rows for x-y-z amplitudes and columns are for blocks
RF: (::Matrix{RF}) RF matrix. The 1 row is for the coil and columns are for blocks
ADC: (::Array{ADC,1}) ADC block vector
DUR: (::Vector, [s]) duration block vector
DEF: (::Dict{String, Any}) dictionary with relevant information of the sequence. Possible keys could be ["AdcRasterTime", "GradientRasterTime", "Name", "Nz", "Num_Blocks", "Nx", "Ny", "PulseqVersion", "BlockDurationRaster", "FileName", "RadiofrequencyRasterTime"]

Returns

seq: (::Sequence) Sequence struct

source

KomaMRIBase.dur Function

julia

y = dur(x::Grad)
y = dur(x::Vector{Grad})
y = dur(x::Matrix{Grad})

Duration time in [s] of Grad struct or Grad Array.

Arguments

x: (::Grad or ::Vector{Grad} or ::Matrix{Grad}) Grad struct or Grad Array

Returns

y: (::Float64, [s]) duration of the Grad struct or Grad Array

source

julia

y = dur(x::RF)
y = dur(x::Vector{RF})
y = dur(x::Matrix{RF})

Duration time in [s] of RF struct or RF Array.

Arguments

x: (::RF or ::Vector{RF} or ::Matrix{RF}) RF struct or RF array

Returns

y: (::Float64, [s]) duration of the RF struct or RF array

source

julia

T = dur(x::Sequence)

The total duration of the sequence in [s].

Arguments

x: (::Sequence) Sequence struct

Returns

T: (::Real, [s]) total duration of the sequence

source

KomaMRIBase.get_block_start_times Function

julia

T0 = get_block_start_times(seq::Sequence)

Returns a vector containing the start times of blocks in a sequence. The initial time is always zero, and the final time corresponds to the duration of the sequence.

Arguments

seq: (::Sequence) Sequence struct

Returns

T0: (::Vector, [s]) start times of the blocks in a sequence

source

KomaMRIBase.get_flip_angles Function

julia

y = get_flip_angles(x::Sequence)

Returns all the flip angles of the RF pulses in the sequence x.

Arguments

x: (::Sequence) Sequence struct

Returns

y: (::Vector{Float64}, [deg]) flip angles

source

`Grad`

KomaMRIBase.Grad Type

julia

gr = Grad(A, T)
gr = Grad(A, T, rise)
gr = Grad(A, T, rise, delay)
gr = Grad(A, T, rise, fall, delay)
gr = Grad(A, T, rise, fall, delay, first, last)

The Grad struct represents a gradient of a sequence event.

Arguments

A: (::Real or ::Vector, [T/m]) amplitude of the gradient
T: (::Real or ::Vector, [s]) duration of the flat-top
rise: (::Real, [s]) duration of the rise
fall: (::Real, [s]) duration of the fall
delay: (::Real, [s]) duration of the delay

Returns

gr: (::Grad) gradient struct

Examples

julia

julia> gr = Grad(1, 1, 0.1, 0.1, 0.2)

julia> seq = Sequence([gr]); plot_seq(seq)

source

KomaMRIBase.Grad Method

julia

gr = Grad(f::Function, T::Real, N::Integer; delay::Real)

Generates an arbitrary gradient waveform defined by the function f in the interval t ∈ [0,T]. The time separation between two consecutive samples is given by T/(N-1).

Arguments

f: (::Function) function that describes the gradient waveform
T: (::Real, [s]) duration of the gradient waveform
N: (::Integer, =300) number of samples of the gradient waveform

Keywords

delay: (::Real, =0, [s]) delay time of the waveform

Returns

gr: (::Grad) gradient struct

Examples

julia

julia> gx = Grad(t -> sin(π*t / 0.8), 0.8)

julia> seq = Sequence([gx]); plot_seq(seq)

source

`RF`

KomaMRIBase.RF Type

julia

rf = RF(A, T)
rf = RF(A, T, Δf)
rf = RF(A, T, Δf, delay)

The RF struct represents a Radio Frequency excitation of a sequence event.

Arguments

A: (::Complex, [T]) RF complex amplitud modulation (AM),
T: (::Real, [s]) RF duration
Δf: (::Real or ::Vector, [Hz]) RF frequency difference with respect to the Larmor frequency. This can be a number but also a vector to represent frequency modulated signals (FM).
delay: (::Real, [s]) RF delay time
center: (::Real, [s]) RF center time
use: (::RFUse) RF use type

Returns

rf: (::RF) the RF struct

Examples

julia

julia> rf = RF(1, 1, 0, 0.2)

julia> seq = Sequence(); seq += rf; plot_seq(seq)

source

KomaMRIBase.RF Method

julia

rf = RF_fun(f::Function, T::Real, N::Int64)

Generate an RF sequence with amplitudes sampled from a function waveform.

Note

This function is not being used in this KomaMRI version.

Arguments

f: (::Function, [T]) function for the RF amplitud waveform
T: (::Real, [s]) duration of the RF pulse
N: (::Int64) number of samples of the RF pulse

Returns

rf😦::RF) RF struct with amplitud defined by the function f

source

KomaMRIBase.get_flip_angle Function

julia

α = get_flip_angle(x::RF)

Calculates the flip angle α [deg] of an RF struct. α = γ ∫ B1(τ) dτ

Arguments

x: (::RF) RF struct

Returns

α: (::Int64, [deg]) flip angle RF struct x

source

`ADC`

KomaMRIBase.ADC Type

julia

adc = ADC(N, T)
adc = ADC(N, T, delay)
adc = ADC(N, T, delay, Δf, ϕ)

The ADC struct represents the Analog to Digital Converter (ADC) of a sequence event.

Arguments

N: (::Int64) number of acquired samples
T: (::Float64, [s]) duration to acquire the samples
delay: (::Float64, [s]) delay time to start the acquisition
Δf: (::Float64, [Hz]) delta frequency. It is meant to compensate RF pulse phases
ϕ: (::Float64, [rad]) phase. It is meant to compensate RF pulse phases

Returns

adc: (::ADC) ADC struct

Examples

julia

julia> adc = ADC(16, 1, 0.1)

julia> seq = Sequence(); seq += adc; plot_seq(seq)

source

KomaMRIBase.get_adc_sampling_times Function

julia

times = get_adc_sampling_times(seq)

Returns an array of times when the samples of the sequence seq are acquired.

Arguments

seq: (::Sequence) sequence struct

Returns

times: (::Vector{Float64}, [s]) time array when samples are acquired

source

KomaMRIBase.get_adc_phase_compensation Function

julia

comp = get_adc_phase_compensation(seq)

Returns an array of phase compensation factors, , which are used to compensate the acquired signal by applying the operation after the simulation. This compensation is necessary because the signal typically exhibits a phase offset of following RF excitation with a phase of . Such pulses are commonly employed in sequences involving RF spoiling.

Arguments

seq: (::Sequence) sequence struct

Returns

comp: (::Vector{Complex}, [rad]) array of phase compensations for every acquired sample

source

`Delay`

KomaMRIBase.Delay Type

julia

delay = Delay(T)

The Delay struct is meant to add a delay to a sequence by using a sum operator.

Arguments

T: (::Real, [s]) time delay value

Returns

delay: (::Delay) delay struct

Examples

julia

julia> delay = Delay(0.5)

julia> s = Sequence([Grad(1, 1, 0.1)])

julia> seq = delay + s; plot_seq(seq)

source

Rotation matrices

KomaMRIBase.rotx Function

julia

Rx = rotx(θ::Real)

Rotates vector counter-clockwise with respect to the x-axis.

Arguments

θ: (::Real, [rad]) rotation angle

Returns

Rx: (::Matrix{Int64}) rotation matrix

source

KomaMRIBase.roty Function

julia

Ry = roty(θ::Real)

Rotates vector counter-clockwise with respect to the y-axis.

Arguments

θ: (::Real, [rad]) rotation angle

Returns

Ry: (::Matrix{Int64}) rotation matrix

source

KomaMRIBase.rotz Function

julia

Rz = rotz(θ::Real)

Rotates vector counter-clockwise with respect to the z-axis.

Arguments

θ: (::Real, [rad]) rotation angle

Returns

Rz: (::Matrix{Int64}) rotation matrix

source

Moments

KomaMRIBase.get_Mk Function

julia

Mk, Mk_adc = get_Mk(seq::Sequence, k; Δt=1)

Computes the th-order moment of the Sequence seq given by the formula .

Arguments

seq: (::Sequence) Sequence struct
k: (::Integer) order of the moment to be computed
Δt: (::Real, =1, [s]) nominal delta time separation between two time samples for ADC acquisition and Gradients

Returns

Mk: (3-column ::Matrix{Real}) th-order moment
Mk_adc: (3-column ::Matrix{Real}) th-order moment sampled at ADC times

source

KomaMRIBase.get_kspace Function

Computes the k-space trajectory of the Sequence seq. Refer to get_Mk and get_M0

source

KomaMRIBase.get_M0 Function

Computes the zero-order moment of the Sequence seq. Refer to get_Mk and get_kspace

source

KomaMRIBase.get_M1 Function

Computes the 1st-order moment of the Sequence seq. Refer to get_Mk

source

KomaMRIBase.get_M2 Function

Computes the 2nd-order moment of the Sequence seq. Refer to get_Mk

source

Event checks

KomaMRIBase.is_RF_on Function

julia

y = is_RF_on(x::Sequence)
y = is_RF_on(x::Sequence, t::Vector{Float64})

Tells if the sequence seq has elements with RF active, or active during time t.

Arguments

x: (::Sequence) Sequence struct
t: (::Vector{Float64}, [s]) time to check

Returns

y: (::Bool) boolean that tells whether or not the RF in the sequence is active

source

KomaMRIBase.is_GR_on Function

julia

y = is_GR_on(x::Sequence)

Tells if the sequence seq has elements with GR active.

Arguments

x: (::Sequence) Sequence struct

Returns

y: (::Bool) boolean that tells whether or not the GR in the sequence is active

source

KomaMRIBase.is_Gx_on Function

julia

y = is_Gx_on(x::Sequence)

Tells if the sequence seq has elements with GR active in x direction.

Arguments

x: (::Sequence) Sequence struct

Returns

y: (::Bool) boolean that tells whether or not the GRx in the sequence is active

source

KomaMRIBase.is_Gy_on Function

julia

y = is_Gy_on(x::Sequence)

Tells if the sequence seq has elements with GR active in y direction.

Arguments

x: (::Sequence) Sequence struct

Returns

y: (::Bool) boolean that tells whether or not the GRy in the sequence is active

source

KomaMRIBase.is_Gz_on Function

julia

y = is_Gz_on(x::Sequence)

Tells if the sequence seq has elements with GR active in z direction.

Arguments

x: (::Sequence) Sequence struct

Returns

y: (::Bool) boolean that tells whether or not the GRz in the sequence is active

source

KomaMRIBase.is_ADC_on Function

julia

y = is_ADC_on(x::Sequence)
y = is_ADC_on(x::Sequence, t::Union{Array{Float64,1}, Array{Float64,2}})

Tells if the sequence seq has elements with ADC active, or active during time t.

Arguments

x: (::Sequence) sequence struct
t: (::Union{Array{Float64,1}, Array{Float64,2}}, [s]) time to check

Returns

y: (::Bool) boolean that tells whether or not the ADC in the sequence is active

source

`DiscreteSequence`

KomaMRIBase.DiscreteSequence Type

julia

seqd = DiscreteSequence(Gx, Gy, Gz, B1, Δf, ADC, t, Δt)

A sampled version of a Sequence struct, containing vectors for event amplitudes at specified times. DiscreteSequence is the struct used for simulation.

Arguments

Gx: (::AbstractVector{T<:Real}, [T/m]) x-gradient vector
Gy: (::AbstractVector{T<:Real}, [T/m]) y-gradient vector
Gz: (::AbstractVector{T<:Real}, [T/m]) z-gradient vector
B1: (::AbstractVector{Complex{T<:Real}}, [T]) RF amplitude vector
Δf: (::AbstractVector{T<:Real}, [Hz]) RF carrier frequency displacement vector
ADC: (::AbstractVector{Bool}) ADC sample vector
t: (::AbstractVector{T<:Real}, [s]) time vector
Δt: (::AbstractVector{T<:Real}, [s]) delta time vector

Returns

seqd: (::DiscreteSequence) DiscreteSequence struct

source

KomaMRIBase.discretize Function

julia

seqd = discretize(seq::Sequence; sampling_params=default_sampling_params())

This function returns a sampled Sequence struct with RF and gradient time refinements based on simulation parameters.

Arguments

seq: (::Sequence) sequence

Keywords

sampling_params: (::Dict{String, Any}, =default_sampling_params()) sampling parameter dictionary

Returns

seqd: (::DiscreteSequence) DiscreteSequence struct

source

KomaMRIBase.get_samples Function

julia

samples = get_samples(seq::Sequence; off_val=0, max_rf_samples=Inf)

Returns the samples of the events in seq.

Arguments

seq: (::Sequence) Sequence struct

Keywords

off_val: (::Number, =0) offset value for amplitude. Typically used to hide points in plots by setting it to Inf
max_rf_samples: (::Integer, =Inf) maximum number of samples for the RF struct

Returns

samples: (::NamedTuple) contains samples for gx, gy, gz, rf, and adc events. Each event, represented by e::NamedTuple, includes time samples (e.t) and amplitude samples (e.A)

source

KomaMRIBase.times Function

julia

t = times(gr::Grad)
t = times(rf::RF)
t = times(adc::ADC)

Get time samples of MRI sequence event.

Arguments

gr: (::Grad) Gradient struct
rf: (::RF) RF struct
adc: (::ADC) ADC struct

Returns

t: (::Vector{Number}) vector with time samples

source

times & unit_time

source

julia

times = times(motion)

source

KomaMRIBase.ampls Function

julia

A = ampls(g::Grad)
A = ampls(r::RF)
A = ampls(d::ADC)

Get amplitude samples of MRI sequence event.

Arguments

gr: (::Grad) Gradient struct
rf: (::RF) RF struct
adc: (::ADC) ADC struct

Returns

A: (::Vector{Number}) vector with amplitude samples

source

KomaMRIBase.freqs Function

julia

f = freqs(r::RF)

Get frequency samples of MRI sequence event.

Arguments

rf: (::RF) RF struct

Returns

f: (::Vector{Number}) vector with frequency samples

source

Other functions

KomaMRIBase.trapz Function

julia

y = trapz(Δt, x)

Trapezoidal integration for every spin of a phantom.

Note

In practice, this function is used to integrate (Gx * x + Gy * y + Gz * z) * Δt for all the spins. NΔt is the length of Δt. Ns stands for the number of spins of a phantom. x is a matrix which rows represents different spins and columns are different times and the elements are the field Gx * x + Gy * y + Gz * z values.

Arguments

Δt: (1 x NΔt ::Matrix{Float64}, [s]) delta time 1-row array
x: (Ns x (NΔt+1) ::Matrix{Float64}, [T]) magnitude of the field Gx * x + Gy * y + Gz * z

Returns

y: (Ns x 1 ::Matrix{Float64}, [T*s]) vector where every element is the integral of (Gx * x + Gy * y + Gz * z) * Δt for every spin of a phantom

source

KomaMRIBase.cumtrapz Function

julia

y = cumtrapz(Δt, x)

Trapezoidal cumulative integration over time for every spin of a phantom.

Arguments

Δt: (1 x NΔt ::Matrix{Float64}, [s]) delta time 1-row array
x: (Ns x (NΔt+1) ::Matrix{Float64}, [T]) magnitude of the field Gx * x + Gy * y + Gz * z

Returns

y: (Ns x NΔt ::Matrix{Float64}, [T*s]) matrix where every column is the cumulative integration over time of (Gx * x + Gy * y + Gz * z) * Δt for every spin of a phantom

source

KomaMRIBase.kfoldperm Function

julia

array_of_ranges = kfoldperm(N, k; breaks=[])

Divides a list of indices from 1 to N into k groups.

Arguments

N: (::Integer) number of elements to be ordered
k: (::Integer) number of groups to divide the N elements.

Keywords

breaks: (::Vector{<:Integer}, =[]) array of indices where predefined breakpoints are placed.

Returns

array_of_ranges: (::Vector{UnitRange{<:Integer}}) array containing ranges of different groups. The target is k groups, but this could increase by adding elements to the breaks input array

source

Sequence Building Blocks (SBB)

KomaMRIBase.PulseDesigner Module

julia

PulseDesigner

A module to define different pulse sequences.

source

KomaMRIBase.PulseDesigner.RF_hard Function

julia

seq = RF_hard(B1, T, sys; G=[0, 0, 0], Δf=0)

Returns a sequence with a RF excitation pulse.

Arguments

B1: (::Number, [T]) RF pulse amplitude
T: (::Real, [s]) RF pulse duration
sys: (::Scanner) Scanner struct

Keywords

G: (::Vector{Real}, =[0, 0, 0], [T/m]) gradient amplitudes for x, y, z
Δf: (::Real, =0, [Hz]) RF pulse carrier frequency displacement

Returns

seq: (::Sequence) Sequence struct with a RF pulse

Examples

julia

julia> sys = Scanner(); durRF = π / 2 / (2π * γ * sys.B1);

julia> seq = PulseDesigner.RF_hard(sys.B1, durRF, sys);

julia> plot_seq(seq)

source

KomaMRIBase.PulseDesigner.RF_sinc Function

julia

seq = RF_sinc(B1, T, sys; G=[0, 0, 0], Δf=0, a=0.46, TBP=4)

Returns a sequence with a RF sinc waveform.

References

Matt A. Bernstein, Kevin F. King, Xiaohong Joe Zhou, Chapter 2 - Radiofrequency Pulse

Shapes, Handbook of MRI Pulse Sequences, 2004, Pages 35-66, https://doi.org/10.1016/B978-012092861-3/50006-6.

Arguments

B1: (::Number, [T]) RF sinc amplitude
T: (::Real, [s]) RF sinc duration
sys: (::Scanner) Scanner struct

Keywords

G: (::Vector{Real}, =[0, 0, 0], [T/m]) gradient amplitudes for x, y, z
Δf: (::Real, =0, [Hz]) RF pulse carrier frequency displacement
a: (::Real, =0.46) height appodization window parameter
TBP: (::Real, =4) width appodization window parameter

Returns

seq: (::Sequence) Sequence struct with a RF pulse

Examples

julia

julia> sys = Scanner(); durRF = π / 2 / (2π * γ * sys.B1);

julia> seq = PulseDesigner.RF_sinc(sys.B1, durRF, sys);

julia> plot_seq(seq)

source

KomaMRIBase.PulseDesigner.EPI Function

julia

seq = EPI(FOV::Real, N::Integer, sys::Scanner)

Returns a sequence with EPI gradients.

Arguments

FOV: (::Real, [m]) field of view
N: (::Integer) number of pixels in the x and y axis
sys: (::Scanner) Scanner struct

Returns

seq: (::Sequence) Sequence struct with EPI gradients

Examples

julia

julia> sys, FOV, N = Scanner(), 23e-2, 101

julia> seq = PulseDesigner.EPI(FOV, N, sys)

julia> plot_seq(seq)

julia> plot_kspace(seq)

source

KomaMRIBase.PulseDesigner.radial_base Function

julia

seq = radial_base(FOV::Real, Nr::Integer, sys::Scanner)

Returns a sequence with radial gradients for a single trajectory.

Arguments

FOV: (::Real, [m]) field of view
N: (::Integer) number of pixels along the diameter
sys: (::Scanner) Scanner struct

Returns

seq: (::Sequence) Sequence struct of a single radial trajectory

Examples

julia

julia> sys, FOV, N = Scanner(), 23e-2, 101

julia> seq = PulseDesigner.radial_base(FOV, N, sys)

julia> plot_seq(seq)

julia> plot_kspace(seq)

source

KomaMRIBase.PulseDesigner.spiral_base Function

julia

spiral = spiral_base(FOV, N, sys; S0=sys.Smax*2/3, Nint=8, λ=Nint/FOV, BW=60e3)

Definition of a spiral base sequence.

References

Glover, G.H. (1999), Simple analytic spiral K-space algorithm. Magn. Reson. Med.,

42: 412-415. https://doi.org/10.1002/(SICI)1522-2594(199908)42:2<412::AID-MRM25>3.0.CO;2-U

Arguments

FOV: (::Real, [m]) field of view
N: (::Integer) number of pixels along the radious
sys: (::Scanner) Scanner struct

Keywords

S0: (::Vector{Real}, =sys.Smax*2/3, [T/m/s]) slew rate reference
Nint: (::Integer, =8) number of interleaves
λ: (::Real, =Nint/FOV, [1/m]) kspace spiral parameter
BW: (::Real, =60e3, [Hz]) adquisition parameter

Returns

spiral: (::Function) function that returns a Sequence struct when evaluated

Examples

julia

julia> sys, FOV, N = Scanner(), 23e-2, 101

julia> spiral = PulseDesigner.spiral_base(FOV, N, sys)

julia> seq = spiral(0)

julia> plot_seq(seq)

source

KomaMRIBase.PulseDesigner.EPI_example Function

julia

seq = EPI_example(; sys=Scanner())

Returns a sequence suitable for acquiring the 2D brain example in the provided examples.

Keywords

sys: (::Scanner) Scanner struct

Returns

seq: (::Sequence) EPI example Sequence struct

Examples

julia

julia> seq = PulseDesigner.EPI_example();

julia> plot_seq(seq)

source

KomaMRIBase ​

Scanner-related functions ​

Phantom-related functions ​

Motion-related functions ​

Motionconstructors ​

AbstractAction types ​

TimeCurve types and related functions ​

AbstractSpinSpan types ​

Sequence-related functions ​

Grad ​

RF ​

ADC ​

Delay ​

Rotation matrices ​

Moments ​

Event checks ​

DiscreteSequence ​

Other functions ​

Sequence Building Blocks (SBB) ​

KomaMRIBase

`Scanner`-related functions

`Phantom`-related functions

`Motion`-related functions

`Motion`constructors

`AbstractAction` types

`TimeCurve` types and related functions

`AbstractSpinSpan` types

`Sequence`-related functions

`Grad`

`RF`

`ADC`

`Delay`

Rotation matrices

Moments

Event checks

`DiscreteSequence`

Other functions

Sequence Building Blocks (SBB)