MRIBuilder.jl internal API
MRIBuilder
— ModuleBuilds and optimises NMR/MRI sequences.
Type diagram
AbstractBlock
├─ ContainerBlock
│ ├─ AbstractAlternativeBlocks
│ │ └─ AlternativeBlocks
│ ├─ BaseBuildingBlock
│ │ ├─ BuildingBlock
│ │ ├─ BaseTrapezoid
│ │ │ ├─ LineReadout
│ │ │ ├─ SliceSelect
│ │ │ └─ Trapezoid
│ │ │ ├─ Trapezoid1D
│ │ │ └─ Trapezoid3D
│ │ ├─ SpoiltSliceSelect
│ │ └─ Wait
│ └─ BaseSequence
│ ├─ EPIReadout
│ ├─ Repeat
│ ├─ Sequence
│ └─ SliceSelectRephase
├─ BaseComponent
│ ├─ EventComponent
│ │ ├─ InstantGradient
│ │ │ ├─ InstantGradient1D
│ │ │ └─ InstantGradient3D
│ │ ├─ RFPulseComponent
│ │ │ ├─ CompositePulse
│ │ │ ├─ ConstantPulse
│ │ │ ├─ GenericPulse
│ │ │ ├─ InstantPulse
│ │ │ └─ SincPulse
│ │ └─ ReadoutComponent
│ │ ├─ ADC
│ │ └─ SingleReadout
│ └─ GradientWaveform
│ ├─ ChangingGradient
│ │ ├─ ChangingGradient1D
│ │ └─ ChangingGradient3D
│ ├─ ConstantGradient
│ │ ├─ ConstantGradient1D
│ │ └─ ConstantGradient3D
│ └─ NoGradient
└─ Pathway
Sequence components
MRIBuilder.Components.AbstractTypes.BaseComponent
— TypeSuper-type for all individual components that form an MRI sequence (i.e., RF pulse, gradient waveform, or readout event).
RF pulses, instant gradients, and readouts are grouped together into EventComponent
.
These all should have a variables.duration
in addition to any other relevant variables
.
MRIBuilder.Components.AbstractTypes.EventComponent
— TypeSuper-type for all RF pulses, instant gradients and readouts that might play out during a gradient waveform.
These all have an variables.effective_time
, which should quantify at what single time one can approximate the RF pulse or readout to have taken place.
MRIBuilder.Components.AbstractTypes.GradientWaveform
— TypeSuper-type for all parts of a gradient waveform.
N should be 1 for a 1D gradient waveform or 3 for a 3D one.
MRIBuilder.Components.AbstractTypes.RFPulseComponent
— TypeSuper type for all RF pulses.
MRIBuilder.Components.AbstractTypes.ReadoutComponent
— TypeSuper type for all readout events.
MRIBuilder.Components.AbstractTypes.edge_times
— Methodedge_times(container/component; tol=1e-6)
Returns all the edge times during a sequence in ms.
Edges are defined as any time, when:
- the edge of a building block
- the slope of the gradient profile changes suddenly
- an RF pulse starts or ends
Edges that are within tol
ms of each other are considered to be one edge (default: 1 ns).
MRIBuilder.Components.AbstractTypes.split_timestep
— Methodsplit_timestep(component, precision)
Indicates the maximum timestep that a component can be linearised with and still achieve the required precision
.
Typically, this will be determined by the maximum second derivative:
$\sqrt{\frac{2 \epsilon}{max(|d^2y/dx^2|)}}$
It should be infinite if the component is linear.
MRIBuilder.Variables.variables.amplitude
— Functionamplitude(pulse)
Return the amplitude of an RFPulseComponent
in kHz.
MRIBuilder.Variables.variables.bandwidth
— Functionbandwidth(pulse)
Return the bandwidth of an RFPulseComponent
in kHz.
MRIBuilder.Variables.variables.flip_angle
— Functionflip_angle(pulse)
Return the flip angle of an RFPulseComponent
in degrees.
MRIBuilder.Variables.variables.frequency
— Functionfrequency(pulse)
Return the off-resonance frequency of an RFPulseComponent
in kHz.
MRIBuilder.Variables.variables.gradient_strength
— Functiongradient_strength(gradient)
Maximum 3D gradient strength of the gradient in kHz/um.
MRIBuilder.Variables.variables.phase
— Functionphase(pulse)
Return the phase of an RFPulseComponent
in degrees.
MRIBuilder.Variables.variables.slew_rate
— Functionslew_rate(gradient)
Maximum 3D slew rate of the gradient in kHz/um/ms.
MRIBuilder.Components.GradientWaveforms
— ModuleModule defining sub-types of the GradientWaveform
.
There are only three types of [GradientBlock
] objects:
ChangingGradient
: any gradient changing linearly in strength.ConstantGradient
: any gradient staying constant in strength. These can overlap with a pulse (SliceSelectPulse
).NoGradient
: any part of the gradient waveform when no gradient is active.
These parts are combined into a full gradient waveform in a BuildingBlock
.
Each part of this gradient waveform can compute:
gradient_strength
: maximum gradient strength in each dimension.slew_rate
: maximum slew rate in each dimension.qval
/qvec
: area under curvebmat_gradient
: diffusion weighting (scalar in 1D or matrix in 3D).
MRIBuilder.Components.GradientWaveforms.NoGradientBlocks.NoGradient
— TypeNoGradient(duration)
Part of a gradient waveform when there is no gradient active.
Usually, you do not want to create this object directly, use a BuildingBlock
instead.
MRIBuilder.Components.GradientWaveforms.ConstantGradientBlocks.ConstantGradient
— TypeConstantGradient(gradient_strength_vector, duration, group=nothing)
ConstantGradient(gradient_strength_scalar, orientation, duration, group=nothing)
Underlying type for any flat part in a 3D (first constructor) or 3D (second constructor) gradient waveform.
Usually, you do not want to create this object directly, use a BuildingBlock
instead.
MRIBuilder.Components.GradientWaveforms.ChangingGradientBlocks.ChangingGradient
— TypeChangingGradient(grad1_scalar, slew_rate_scalar, orientation, duration, group=nothing)
ChangingGradient(grad1_vec, slew_rate_vec, duration, group=nothing)
Underlying type for any linearly changing part in a 1D (first constructor) or 3D (second constructor) gradient waveform.
Usually, you do not want to create this object directly, use a BuildingBlock
instead.
MRIBuilder.Components.GradientWaveforms.ChangingGradientBlocks.split_gradient
— Methodsplit_gradient(constant/changing_gradient_block, times...)
Split a single gradient at a given times.
All times are relative to the start of the gradient block (in ms). Times are assumed to be in increasing order and between 0 and the duration of the gradient block.
For N times this returns a vector with the N+1 replacement ConstantGradient
or ChangingGradient
objects.
MRIBuilder.Components.InstantGradients.InstantGradient
— TypeInstantGradient(; orientation=nothing, group=nothing, variables...)
If the orientation
is set an InstantGradient1D
is returned, otherwise an InstantGradient3D
.
Parameters
orientation
sets the gradient orientation as a length-3 vector. If not set, the gradient can be in any direction.group
: name of the group to which this gradient belongs (used for scaling and rotating).
Variables
variables.qvec
: Spatial frequency on which spins will be dephased due to this pulsed gradient in rad/um.variables.spoiler
: Length-scale on which spins will be dephased by exactly 2π in mm.
MRIBuilder.Components.InstantGradients.InstantGradient1D
— TypeAn InstantGradient
with a fixed orientation.
MRIBuilder.Components.InstantGradients.InstantGradient3D
— TypeAn InstantGradient
with a variable orientation.
MRIBuilder.Components.Pulses.GenericPulses.GenericPulse
— TypeGenericPulse(time, amplitude, phase, effective_time=<halfway>)
GenericPulse(time, amplitude; phase=0., frequency=0., effective_time=<halfway>)
Create a Pulse profile that has been fully defined by N control point.
All arguments should be arrays of the same length N defining these control points.
This pulse has no free variables.
time
: time since the start of thisBuildingBlock
in ms.amplitude
: amplitude of the RF pulse at every timepoint in kHz.phase
: phase of the RF pulse at every timpoint in degrees. If not set explicitly it will be determined by the provided startingphase
(degrees) and thefrequency
(kHz).effective_time
: the time that the RF pulse should be considered to have taken place when computing aPathway
(defaults: whenever half of the final flip angle has been achieved for on-resonance spins).
MRIBuilder.Components.Pulses.GenericPulses.GenericPulse
— MethodGenericPulse(pulse, t1, t2)
Creates a new GenericPulse
by slicing another pulse between t1
and t2
MRIBuilder.Components.Pulses.InstantPulses.InstantPulse
— TypeInstantPulse(; flip_angle=nothing, phase=nothing, group=nothing)
Return an instant RF pulse that rotates all spins by flip_angle
around an axis that has an angle of phase
with the X-Y plane.
Parameters
group
: name of the group to which this pulse belongs. This is used for scaling or adding phases/off-resonance frequencies.
Variables
variables.flip_angle
: angle by which spins are rotated in degrees.variables.phase
: angle of axis around which spins are rotated in degrees.
MRIBuilder.Components.Pulses.ConstantPulses.ConstantPulse
— TypeConstantPulse(; variables...)
Represents an radio-frequency pulse with a constant amplitude and frequency (i.e., a rectangular function).
Parameters
group
: name of the group to which this pulse belongs. This is used for scaling or adding phases/off-resonance frequencies.
Variables
variables.flip_angle
: rotation expected for on-resonance spins in degrees.variables.duration
: duration of the RF pulse in ms.variables.amplitude
: amplitude of the RF pulse in kHz.variables.phase
: phase at the start of the RF pulse in degrees.variables.frequency
: frequency of the RF pulse relative to the Larmor frequency (in kHz).
MRIBuilder.Components.Pulses.SincPulses.SincPulse
— TypeSincPulse(; Nzeros=3, apodise=true, variables...)
Represents a radio-frequency pulse with a sinc-like amplitude and constant frequency.
Parameters
Nzeros
: Number of zero-crossings on each side of the sinc pulse. Can be set to a tuple with two values to have a different number of zero crossings on the left and the right of the sinc pulse.apodise
: if true (default) applies a Hanning apodising window to the sinc pulse.group
: name of the group to which this pulse belongs. This is used for scaling or adding phases/off-resonance frequencies.
Variables
variables.flip_angle
: rotation expected for on-resonance spins in degrees.variables.duration
: duration of the RF pulse in ms.variables.amplitude
: amplitude of the RF pulse in kHz.variables.phase
: phase at the start of the RF pulse in degrees.variables.frequency
: frequency of the RF pulse relative to the Larmor frequency (in kHz).variables.bandwidth
: width of the rectangular function in frequency space (in kHz). If theduration
is short (compared with 1/bandwidth
), this bandwidth will only be approximate.
MRIBuilder.Variables.variables.N_left
— FunctionN_left(sinc_pulse)
Number of zero-crossings of the SincPulse
before the maximum.
Also, see variables.N_right
MRIBuilder.Variables.variables.N_right
— FunctionN_left(sinc_pulse)
Number of zero-crossings of the SincPulse
after the maximum.
Also, see variables.N_left
MRIBuilder.Variables.variables.lobe_duration
— Functionlobe_duration(sinc_pulse)
Time between two zero-crossings of a SincPulse
.
MRIBuilder.Components.Pulses.CompositePulses.CompositePulse
— TypeCompositePulse(; base_pulse, nweights, variables...)
A composite RF pulse formed by repeating a base RF pulse.
Parameters
base_pulse
: The base RF pulse that will be repeated.nweights
: The number of repeated pulses. This will be ignored if a vector ofweights
is explicitly provided.
Variables
weights
: The weight of each of the base RF pulses.interpulse_delay
: Time between the center of the RF pulses. If not otherwise constrained, it will be minimised.scale_amplitude
: How strongly one should scale the amplitude versus the duration to achieve the desired weights. If set to 1 only the RF pulse amplitude will be scaled. If set to 0 only the RF pulse duration will be scaled.
MRIBuilder.Components.Pulses.CompositePulses.BinomialPulse
— MethodBinomialPulse(; base_pulse, npulses, flip=true, variables...)
Creates a CompositePulse
of npulses
repeats of base_pulse
, where the weights
are set by the biomial distribution.
If flip
is true (default) every other pulse will be flipped (so that the total excitation is canceled). The variables
are defined in CompositePulse
.
MRIBuilder.Components.Readouts.ADCs.ADC
— TypeADC(; center_halfway=true, oversample=1, variables...)
Adds a readout event.
Parameters
center_halfway
: by default thetime_to_center
is assumed to be half of theduration
. Set this to false to disable this assumption.oversample
: by how much the ADC should oversample (minimum of 1).
Variables
resolution
: number of voxels in the readout direction. This can be a non-integer value during optimisation.nsamples
: number of samples in the readout. This can be a non-integer value during optimisation.dwell_time
: Time between each readout sample in ms.duration
: Total duration of the ADC event in ms.time_to_center
: time till the center of k-space from start of ADC in ms.effective_time
: same astime_to_center
.
MRIBuilder.Variables.variables.dwell_time
— Functiondwell_time(adc)
The dwell time of the ADC readout in ms.
MRIBuilder.Variables.variables.nsamples
— Functionnsamples(adc)
Number of samples in an ADC.
MRIBuilder.Variables.variables.oversample
— Functionoversample(adc)
The oversampling rate of the ADC readout.
MRIBuilder.Variables.variables.resolution
— Functionresolution(readout)
Resolution of the readout.
MRIBuilder.Variables.variables.time_to_center
— Functiontime_to_center(adc)
The time of the ADC readout to reach the center of k-space.
MRIBuilder.Components.Readouts.SingleReadouts.SingleReadout
— TypeSingleReadout()
Represents an instantaneous Readout
of the signal.
It has no parameters or variables to set.
Containers for sequence components
MRIBuilder.Containers.Abstract.ContainerBlock
— TypeParent type for BuildingBlock
or BaseSequence
, i.e., any building block that contains other MRI components/blocks.
Iterate over them to get the individual components.
MRIBuilder.Containers.Abstract.amplitude
— Functionamplitude(sequence, time)
Returns the RF amplitude at a particular time within the sequence in kHz.
MRIBuilder.Containers.Abstract.end_time
— Methodend_time(container, indices...)
Returns the start time of component with given indices
with respect to the start of the ContainerBlock
.
Also see variables.duration
, start_time
, and variables.effective_time
MRIBuilder.Containers.Abstract.frequency
— Functionfrequency(sequence, time)
Returns the RF frequency at a particular time within the sequence in kHz.
NaN is returned if there is no pulse activate at that time
.
MRIBuilder.Containers.Abstract.gradient_strength
— Functiongradient_strength(sequence, time)
Returns the gradient strength at a particular time within the sequence.
MRIBuilder.Containers.Abstract.iter
— Methoditer(sequence, get_type)
Helper functions for any iter_*
functions.
MRIBuilder.Containers.Abstract.iter_blocks
— Methoditer_blocks(sequence)
Returns all the building blocks in the sequence with the time they will start
MRIBuilder.Containers.Abstract.iter_instant_gradients
— Methoditer_instant_gradients(sequence)
Returns all the InstantGradient
within the sequence with their timings
MRIBuilder.Containers.Abstract.iter_instant_pulses
— Methoditer_instant_pulses(sequence)
Returns all the InstantPulse
within the sequence with their timings
MRIBuilder.Containers.Abstract.phase
— Functionphase(sequence, time)
Returns the RF phase at a particular time within the sequence in degrees.
NaN is returned if there is no pulse activate at that time
.
MRIBuilder.Containers.Abstract.start_time
— Methodstart_time(container, indices...)
Returns the start time of component with given indices
with respect to the start of the ContainerBlock
.
Also see variables.duration
, end_time
, and variables.effective_time
MRIBuilder.Variables.get_gradient
— Functionget_gradient(container, time)
Gets the gradient running at a particular time
(in ms) during a sequence of building block.
This function will return a tuple with 2 elements:
- The
GradientWaveform
itself (which could be aNoGradient
object). - The time since the start of the gradient
MRIBuilder.Variables.get_pulse
— Functionget_pulse(container, time)
Gets the pulse running at a particular time
(in ms) during a sequence of building block.
If there is a RF pulse, this function will return a tuple with 2 elements:
- The
RFPulseComponent
itself - The time since the start of the pulse
If there is no active RF pulse, nothing
is returned.
MRIBuilder.Variables.variables.effective_time
— Functioneffective_time(container, indices...)
Returns the start time of component with given indices
with respect to the start of the ContainerBlock
.
This will crash if the component does not have an variables.effective_time
(e.g., if it is (part of) a gradient waveform).
Also see variables.duration
, start_time
, and end_time
MRIBuilder.Variables.variables.readout_times
— Functionreadout_times(sequence)
Returns all the times that the sequence will readout.
MRIBuilder.Containers.BuildingBlocks
— ModuleDefines BaseBuildingBlock
, BuildingBlock
and Wait
.
MRIBuilder.Containers.BuildingBlocks.BaseBuildingBlock
— TypeBasic BuildingBlock, which can consist of a gradient waveforms with any number of RF pulses/readouts overlaid
Main interface:
- iteration will give the gradient waveforms interspersed by RF pulses/readouts.
- Indiviual indices can be accessed using
keys(building_block)
- Indiviual indices can be accessed using
waveform_sequence
returns just the gradient waveform as a sequence ofGradientWaveform
objects.waveform
returns just the gradient waveform as a sequence of (time, gradient_strength) tuples.events
returns the RF pulses and readouts.variables.qvec
returns area under curve for (part of) the gradient waveform.
Sub-types need to implement:
Base.keys
: returns sequence of keys to all the components.Base.getindex
: returns the actual component for each key. Forevents
(readout/pulses) this should return a tuple with(time delay till start, event)
.
MRIBuilder.Containers.BuildingBlocks.BuildingBlock
— TypeBuildingBlock(waveform, events; duration=nothing, orientation=nothing, group)
Generic BaseBuildingBlock
that can capture any overlapping gradients, RF pulses, and/or readouts. The gradients cannot contain any free variables.
Scanner constraints are automatically applied.
Arguments
waveform
: Sequence of 2-element tuples with (time, (Gx, Gy, Gz)). Iforientation
is set then the tuple is expected to look like (time, G). This cannot contain any free variables.events
: Sequence of 2-element tuples with (time, pulse/readout). Thetime
is the start time of the pulse/readout.duration
: duration of thisBuildingBlock
. If not set then it will be assumed to be the time of the last element inwaveform
.orientation
: orientation of the gradients in the waveform. If not set, then the full gradient vector should be given explicitly.group
: group of the gradient waveform
MRIBuilder.Containers.BuildingBlocks.BuildingBlock
— MethodBuildingBlock(pulse/readout)
Creates a BuildingBlock
with no gradients and just the single [EventComponent
]@(ref).
MRIBuilder.Containers.BuildingBlocks.Wait
— TypeAn empty BuildingBlock representing dead time.
It only has a single variable, namely its variables.duration
.
MRIBuilder.Containers.BuildingBlocks.events
— Methodevents(building_block)
Returns just the non-gradient (i.e., RF pulses/readouts) events as a sequence of EventComponent
objects (with their keys).
MRIBuilder.Containers.BuildingBlocks.waveform
— Methodwaveform(building_block)
Returns the gradient waveform of any BaseBuildingBlock
as a sequence of control points.
Each control point is stored as a tuple with the time in ms and the gradient as a length-3 vector. The gradient is linearly interpolated between these points (see waveform_sequence
).
MRIBuilder.Containers.BuildingBlocks.waveform_sequence
— Methodwaveform_sequence(building_block, first, last)
Gets the sequence of GradientWaveform
from the event with key first
till the event with key last
.
Setting first
to nothing indicates to start from the beginning of the building_block
. Similarly, setting last
to nothing indicates to continue till the end of the building_block
.
MRIBuilder.Containers.BuildingBlocks.waveform_sequence
— Methodwaveform_sequence(building_block)
Returns just the gradient waveform as a sequence of GradientWaveform
objects (with their keys).
MRIBuilder.Variables.variables.bmat_gradient
— Functionbmat_gradient(overlapping, qstart[, first_event, last_event])
Computes the addition to the variables.bmat
contributed by a specific building block or gradient.
qstart
represents the variables.qvec
at the start of this component.
If first_event
is set to something else than nothing
, only the gradient waveform after this RF pulse/Readout will be considered. Similarly, if last_event
is set to something else than nothing
, only the gradient waveform up to this RF pulse/Readout will be considered.
MRIBuilder.Variables.variables.qvec
— Functionqvec(overlapping[, first_event, last_event])
Computes the area under the curve for the gradient waveform in BaseBuildingBlock
.
If first_event
is set to something else than nothing
, only the gradient waveform after this RF pulse/Readout will be considered. Similarly, if last_event
is set to something else than nothing
, only the gradient waveform up to this RF pulse/Readout will be considered.
MRIBuilder.Containers.BaseSequences
— ModuleDefines BaseSequence
and Sequence
MRIBuilder.Containers.BaseSequences.BaseSequence
— TypeSuper-type of any sequence of non-overlapping building blocks that should be played after each other.
It contains N
ContainerBlock
objects (e.g., building blocks or other sequences).
Main interface:
- Acts as an iterable containing the blocks and sequences.
- Indiviual blocks/sequences can be obtained using indexing.
- If there is a finite number of repeats, the iteration will continue over all repeats.
Sub-types need to implement:
get_index_single_TR
: return the index assuming it is between 1 and N
MRIBuilder.Containers.BaseSequences.Sequence
— TypeSequence(blocks; name=:Sequence, variables...)
Sequence(blocks...; name=:Sequence, variables...)
Defines an MRI sequence from a vector of building blocks.
Arguments
blocks
: The actual building blocks that will be played in sequence. All the building blocks must be of typeContainerBlock
, which means that they cannot only contain actualBaseBuildingBlock
objects, but also otherBaseSequence
objects. Objects of a different type are converted into aContainerBlock
internally:- numbers/
nothing
/:min
/:max
: replaced with aWait
block with the appropriate constraint/objective added to itsvariables.duration
. - RF pulse or readout: will be embedded within a
BuildingBlock
of the appropriate length
- numbers/
Specific named sequences might define additional variables.
MRIBuilder.Containers.BaseSequences.get_index_single_TR
— Methodget_index_single_TR(sequence, index)
Used internally by any BaseSequence
to get a specific block. The index
should be between 1 and N. It should be implemented for any sub-classes of BaseSequence
.
MRIBuilder.Containers.BaseSequences.nrepeat
— Methodnrepeat(sequence)
How often sequence should be repeated.
MRIBuilder.Containers.BaseSequences.to_block
— Methodto_block(block_like)
Converst object into something that can be included in the sequence:
- :min/:max/number/variable/nothing =>
Wait
. building_block
orsequence
=> no change.- RF pulse/readout => will be embedded within a
BuildingBlock
.
MRIBuilder.Containers.Alternatives.AbstractAlternativeBlocks
— TypeParent type for all blocks that can take different MR sequence components between multiple repetitions of the sequence.
They can be extended into their individual components using adjust(<name>=:all)
.
Each subtype of AbstractAlternativeBlock
needs to implement two methods:
get_alternatives_name
: returns thename
used to identify this block inadjust
get_alternatives_options
: returns a dictionary mapping the name of the different options to aContainerBlock
with the actual sequence building block.
MRIBuilder.Containers.Alternatives.AlternativeBlocks
— TypeAlternativeBlocks(name, blocks)
Represents a part of the sequence where there are multiple possible alternatives.
Variables can be matched across these alternatives using match_blocks!
.
The name
is a symbol that is used to identify this AlternativeBlocks
in the broader sequence (as in adjust
).
MRIBuilder.Containers.Alternatives.get_alternatives_name
— Methodget_alternatives_name(alternative_block)
Get the name with which any AbstractAlternativeBlocks
will be identified in a call to adjust
.
MRIBuilder.Containers.Alternatives.get_alternatives_options
— Methodget_alternatives_options(alternative_block)
Get the options available for a AbstractAlternativeBlocks
.
MRIBuilder.Containers.Alternatives.match_blocks!
— Methodmatch_blocks!(alternatives, function)
Matches the outcome of given function
on each of the building blocks in AlternativeBlocks
.
For example, match_blocks!(alternatives, duration)
will ensure that all the alternative building blocks have the same duration.
Pre-defined sequence parts
There are helper functions available to actually add these to a sequence.
MRIBuilder.Parts.Trapezoids
— ModuleDefines a set of different options for MRI gradients.
MRIBuilder.Parts.Trapezoids.BaseTrapezoid
— TypeParent type for any BuildingBlock
that has a trapezoidal gradient waveform.
Sub-types:
The N
indicates whether the gradient has a fixed orientation (N=1) or is free (N=3).
MRIBuilder.Parts.Trapezoids.LineReadout
— TypeLineReadout(adc; ramp_overlap=1., orientation=nothing, group=nothing, variables...)
Defines a trapezoidal gradient with an ADC readout overlaid.
Parameters and variables are identical as for Trapezoid
with the addition of:
Parameters
adc
:ADC
object that describes the readout.ramp_overlap
: how much the gradient ramp should overlap with the ADC. 0 for no overlap, 1 for full overlap (default: 1). Can be set tonothing
to become a free variable.
Variables
variables.fov
: FOV of the output image along this single k-space line in mm.variables.voxel_size
: size of each voxel along this single k-space line in mm.
MRIBuilder.Parts.Trapezoids.SliceSelect
— TypeSliceSelect(pulse; orientation=nothing, group=nothing, variables...)
Defines a trapezoidal gradient with a pulse played out during the flat time.
Parameters and variables are identical as for Trapezoid
with the addition of:
Parameters
pulse
: sub-type ofRFPulseComponent
that describes the RF pulse.
Variables
slice_thickness
: thickness of the selected slice in mm
MRIBuilder.Parts.Trapezoids.Trapezoid
— TypeTrapezoid(; orientation=nothing, group=nothing, variables...)
Defines a trapezoidal pulsed gradient
Parameters
orientation
sets the gradient orientation (completely free by default). Can be set to a vector for a fixed orientation.group
: assign the trapezoidal gradient to a specific group. This group will be used to scale or rotate the gradients after optimisation.
Variables
Variables can be set during construction or afterwards as an attribute. If not set, they will be determined during the sequence optimisation.
Timing variables
variables.rise_time
: Time of the gradient to reach from 0 to maximum in ms. If explicitly set to 0, the scanner slew rate will be ignored.variables.flat_time
: Time that the gradient stays at maximum strength in ms.variables.δ
: effective pulse duration (rise_time
+flat_time
) in ms.variables.duration
: total pulse duration (2 *rise_time
+flat_time
) in ms.
Gradient variables
variables.gradient_strength
: Maximum gradient strength achieved during the pulse in kHz/umvariables.qvec
: Spatial scale on which spins will be dephased due to this pulsed gradient in rad/um (given byδ
*gradient_strength
).
The bvalue
can be constrained for multiple gradient pulses by creating a Pathway
.
MRIBuilder.Parts.Trapezoids.opposite_kspace_lines
— Methodopposite_kspace_lines(; orientation=[1, 0, 0], kwargs...)
Return a positive and negative readout of a k-space line.
MRIBuilder.Variables.variables.flat_time
— Functionflat_time(trapezoid)
Returns the flat time of a Trapezoid
gradient profile in ms.
MRIBuilder.Variables.variables.fov
— Functionfov(readout)
Defines the field of view of a readout in mm.
MRIBuilder.Variables.variables.ramp_overlap
— Functionramp_overlap(line_readout)
Return the fraction of the gradient ramp that overlaps with the ADC readout.
Set to 0 to ensure that the ADC is only active during the flat time of the readout.
MRIBuilder.Variables.variables.rise_time
— Functionrise_time(trapezoid)
Returns the rise time of a Trapezoid
gradient profile in ms.
MRIBuilder.Variables.variables.slice_thickness
— Functionslice_thickness(slice_select)
Defines the slice thickness for a RF pulse with an active gradient in mm (e.g., SliceSelect
).
Defines as variables.gradient_strength_norm
(gradient) / variables.bandwidth
(pulse)
MRIBuilder.Variables.variables.voxel_size
— Functionvoxel_size(readout)
Defines the voxel size of a readout in mm.
MRIBuilder.Variables.variables.δ
— Functionδ(trapezoid)
Returns the effective duration of a Trapezoid
gradient profile in ms.
Defined as variables.rise_time
+ variables.flat_time
.
MRIBuilder.Parts.SpoiltSliceSelects.SpoiltSliceSelect
— TypeSpoiltSliceSelect(pulse; parameters..., variables...)
Adds slice selection to the pulse
and surrounds it with spoiler gradients.
Parameters
orientation
: vector with orientation of the slice selection and the spoilers (default: [0, 0, 1])group
: name of the group of the gradient. This will be used to scale and rotate the gradients after optimisation. Scaling is not recommended as this might ruin the spoiling.
Variables
duration
: total duration of the block in ms.slice_thickness
: slice thickness in mm.spoiler
: length scale on which the spoilers achieve 2π dephasing in mm. This sets the minimum spoiling. If this spoiling level is not achieved by the slice-select gradient alone, then there will be additional gradients added.
MRIBuilder.Variables.variables.all_gradient_strengths
— Functionall_gradient_strengths(spoilt_slice_select)
Returns the gradient strength before, during, and after the pulse in SpoiltSliceSelect
.
MRIBuilder.Variables.variables.fall_time
— Functionfall_time(spoilt_slice_select)
Returns the time of the SpoiltSliceSelect
to return to zero.
MRIBuilder.Parts.SliceSelectRephases.SliceSelectRephase
— TypeSliceSelectRephase(pulse; kwargs...)
Creates an excitatory RF pulse with slice selection and a rephasing gradient.
Parameters are the same as for SliceSelect
.
MRIBuilder.Parts.EPIReadouts.EPIReadout
— TypeEPIReadout(; resolution, ky_lines=-resolution[2]:resolution[2], recenter=false, group=:FOV, variables...)
Defines an (accelerated) EPI readout.
Parameters
variables.resolution
: Resolution of the final image in the frequency- and phase-encode directions.recenter
: if true, the signal will be recentred in k-space after the EPI readout.group
: name of the group used to rotate the readout gradients (default: :FOV).
Variables:
variables.voxel_size
: size of the voxel in the frequency- and phase-encode directions.variables.fov
: size of the FOV in the frequency- and phase-encode directions.variables.ramp_overlap
: what fraction of the gradient ramp should overlap with the readout.variables.oversample
: by how much to oversample in the frequency-encode direcion.variables.dwell_time
: dwell time in the frequency-encode direction
Sequence I/O
MRIBuilder.SequenceIO.Pulseq
— ModuleModule converting MRIBuilder sequences to and from sequences recognised by PulseqIO
.
MRIBuilder.SequenceIO.PulseqIO
— ModuleStand-alone module that reads/writes Pulseq files.
The pulseq files are read into or written from a set of types that closely match the Pulseq file format. The translation of these types into MRIBuilder types is defined in "../pulseq.jl" (i.e., MRIBuilder.SequenceIO.Pulseq
)
MRIBuilder.SequenceIO.PulseqIO.read_pulseq
— Methodread_pulseq(IO)
Reads a sequence from a pulseq file (http://pulseq.github.io/). Pulseq files can be produced using matlab (http://pulseq.github.io/) or python (https://pypulseq.readthedocs.io/en/master/).
MRIBuilder.SequenceIO.PulseqIO.write_pulseq
— Methodwrite_pulseq(IO, sequence)
Writes a sequence to an output IO file.
MRIBuilder.SequenceIO.PulseqIO.Types
— ModuleDefine the main types forming a PulseqSequence
.
Extensions and sections types are defined in their own modules.
MRIBuilder.SequenceIO.PulseqIO.Types.AnyPulseqComponent
— TypeSuper-type for any RF pulses/gradients/ADC/extensions that can play out during a PulseqBlock
.
MRIBuilder.SequenceIO.PulseqIO.Types.AnyPulseqGradient
— TypeSuper-type of Pulseq gradients:
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqADC
— TypePulseqADC(num::Int, dwell::Float64, delay::Int, frequency::Number, phase::Number)
A trapezoidal gradient pulse defined in Pulseq (see specification).
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqBlock
— TypePulseqBlock(duration::Int, rf::PulseqRFPulse, gx::AnyPulseqGradient, gy::AnyPulseqGradient, gz::AnyPulseqGradient, adc::PulseqADC, ext)
Defines a Building Block with the Pulseq sequence (see specification).
The RF pulse, gradients, and ADC can be set to nothing
.
The ext
is a sequence of extension blocks that will be played out. Set this to a sequence of zero length to not have any extensions.
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqExtension
— TypePulseqExtension(definition::PulseqExtensionDefinition, id::Int)
Reference to a specific implementation of a PulseqExtensionDefinition
.
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqExtensionDefinition
— TypePulseqExtensionDefinition(name, content)
Abstract definition of an unknown Pulseq extension.
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqGradient
— TypePulseqGradient(amplitude::Number, shape::PulseqShape, time::PulseqShape, delay::int)
A generic gradient waveform defined in Pulseq (see specification).
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqRFPulse
— TypePulseqRFPulse(amplitude::Number, magnitude::PulseqShape, phase::PulseqShape, time::PulseqShape, delay::Int, frequency::Number, phase_offset::Number)
An RF pulse defined in Pulseq (see specification).
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqSection
— TypePulseqSection(:<title>)(lines)
Represents a section in the pulseq file format.
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqSequence
— TypePulseqSequence(version::VersionNumber, definitions::NamedTuple, blocks::Vector{PulseqBlock})
A full sequence defined according to the Pulseq specification.
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqShape
— TypePulseqShape(samples)
Define the shape of a PulseqRFPulse
or PulseqGradient
.
MRIBuilder.SequenceIO.PulseqIO.Types.PulseqTrapezoid
— TypePulseqTrapezoid(amplitude::Number, rise::Int, flat::Int, fall::Int, delay::Int)
A trapezoidal gradient pulse defined in Pulseq (see specification).
MRIBuilder.SequenceIO.PulseqIO.Parsers.gen_section
— Functiongen_section(sequence, Val(:<title>))
Creates a specific PulseqSection
{<title>} from a part of the PulseqSequence.
This is the opposite of parse_section
MRIBuilder.SequenceIO.PulseqIO.Parsers.parse_section
— Functionparse_section(section)
Parses any PulseqSection
and return the appropriate type.
The opposite is gen_section
.
MRIBuilder.SequenceIO.PulseqIO.BasicParsers.parse_pulseq_dict
— Methodparse_pulseq_dict(line, names, dtypes)
Parse a line of integers/floats with known names and dtypes.
This is useful to parse most of the columnar data in Pulseq, such as in BLOCKS, RF, GRADIENTS, etc.
MRIBuilder.SequenceIO.PulseqIO.BasicParsers.parse_pulseq_properties
— Methodparse_pulseq_properties(lines)
Parse any pulseq
section formatted as:
<name> <value>
<name2> <value2>
...
This includes the VERSION, DEFINITIONS, and part of the SHAPES
MRIBuilder.SequenceIO.PulseqIO.BasicParsers.parse_value
— Methodparse_value(string)
Tries to value the string
as a number of sequence of numbers. If that does not work, the string
is returned.
MRIBuilder.SequenceIO.PulseqIO.Components
— ModuleDefine a list of all the PulseqShape
and PulseqComponent
that are used in a PulseqSequence
.
MRIBuilder.SequenceIO.PulseqIO.Components.PulseqComponents
— TypePulseqComponents(shapes, pulses, grads, adcs, extensions)
All the shapes, pulses, grads, adcs, and extensions used in a PulseqSequence
.
They can be provided as a dictionary from the integer ID to the object or as a vector.
MRIBuilder.SequenceIO.PulseqIO.Components.add_components!
— Methodadd_components(comp::PulseqComponents, search_vec::Vector, component)
add_components(comp::PulseqComponents, shape::PulseqShape)
Adds a component to the search_vec
, which is assumed to be the appropriate vector within the comp
.
It will check whether the component
is already part of the search_vec
before adding it. The integer ID of the position of the component
in search_vec
is returned.
0 is returned if component
is nothing
.
MRIBuilder.SequenceIO.PulseqIO.Components.same_component
— Methodsame_component(comp::PulseqComponents, a, b)
Check whether components a
and b
are the same when using the shapes represented in comp
.
MRIBuilder.SequenceIO.PulseqIO.Components.same_shape
— Methodsame_component(a, b)
Check whether shapes a
and b
are the same.
MRIBuilder.SequenceIO.PulseqIO.SectionsIO
— ModuleDefine IO for PulseqSection
.
MRIBuilder.SequenceIO.PulseqIO.SectionsIO.parse_pulseq_sections
— Methodparse_pulseq_sections(io)
Reads a Pulseq file into a dictionary of PulseqSection
objects.
MRIBuilder.SequenceIO.PulseqIO.SectionsIO.write_pulseq_section
— Methodwrite_pulseq_section(io, section::PulseqSection)
Writes a Pulseq section
to the IO
.
MRIBuilder.SequenceIO.PulseqIO.ParseSections
— ModuleTranslate between sets of PulseqSection
objects and PulseqSequence
.
MRIBuilder.SequenceIO.PulseqIO.ParseSections.parse_all_sections
— MethodPlot
MRIBuilder.Plot.SequenceDiagram
— TypeSequenceDiagram(; RFx, RFy, Gx, Gy, Gz, ADC)
All the lines forming a sequence diagram.
Each parameter should be a SinglePlotLine
if provided. Any parameters not provided will be set to a SinglePlotLine
with zero amplitude.
MRIBuilder.Plot.SinglePlotLine
— TypeSinglePlotLine(times, amplitudes, event_times, event_amplitudes)
A single line in a sequence diagram (e.g., RFx, Gy, ADC).
MRIBuilder.Plot.plot_sequence
— Functionplot_sequence(sequence; figure=(), axis=(), attributes...)
plot(sequence; attributes...)
plot!([scene,] sequence; attributes...)
Plot the sequence diagram.
Calling plot_sequence
will result in a much cleaner sequence diagram (recommended). However, if you want to combine this diagram with other plots you will have to use plot
or plot!
instead.
If called as plot_sequence
the user can also supply Makie.Figure
(figure=(...)
) and Makie.Axis
(axis=(...)
) keywords. If called using the plot
or plot!
interface, only the attributes listed below can be supplied
This function will only work if Makie
is installed and imported.
Attributes
Line properties
linecolor
sets the color of the lines. If you want to set the text color to the same value, you can also usecolor=...
.linewidth=1.5
sets the width of the lines.instant_width=3.
sets the width of any instant gradients or pulses with respect to thelinewidth
.
Text properties
textcolor
sets the color of the text. If you want to set the line color to the same value, you can also usecolor=...
.font
sets whether the rendered text is :regular, :bold, or :italic.fontsize
: set the size of each character.
Base.Docs.DocStr(svec("### Generic attributes\n\n- visible::Bool = true
sets whether the plot will be rendered or not.\n- overdraw::Bool = false
sets whether the plot will draw over other plots. This specifically means ignoring depth checks in GL backends.\n- transparency::Bool = false
adjusts how the plot deals with transparency. In GLMakie transparency = true
results in using Order Independent Transparency.\n- fxaa::Bool = true
adjusts whether the plot is rendered with fxaa (anti-aliasing).\n- inspectable::Bool = true
sets whether this plot should be seen by DataInspector
.\n- depth_shift::Float32 = 0f0
adjusts the depth value of a plot after all other transformations, i.e. in clip space, where 0 <= depth <= 1
. This only applies to GLMakie and WGLMakie and can be used to adjust render order (like a tunable overdraw).\n- model::Makie.Mat4f
sets a model matrix for the plot. This replaces adjustments made with translate!
, rotate!
and scale!
.\n- space::Symbol = :data
sets the transformation space for box encompassing the volume plot. See Makie.spaces()
for possible inputs.\n- clip_planes::Vector{Plane3f} = Plane3f[]
: allows you to specify up to 8 planes behind which plot objects get clipped (i.e. become invisible). By default clip planes are inherited from the parent plot or scene.\n"), nothing, Dict{Symbol, Any}(:typesig => Tuple{Any}, :module => MakieCore, :linenumber => 4, :binding => MakieCore.genericplotattributes!, :path => "/root/.julia/packages/MakieCore/NeQjl/src/basic_plots.jl"))
MRIBuilder.Plot.range_event
— Methodrange_event(single_plot_line)
Returns the minimum and maximum amplitude for the events in SinglePlotLine
MRIBuilder.Plot.range_line
— Methodrange_line(single_plot_line)
Returns the minimum and maximum amplitude for a SinglePlotLine