Utility#

Functions:

`calculate_diffusion_weighting`(seq[, ...])	Evaluates the b-value or b-matrix of arbitrary gradient waveforms by numerical integration.
`calculate_gradient_spectra`(sequence, directions)	Calculates gradient sampling spectra along a given direction according to:
`concomitant_fields`(sequence, coordinates)	Computes concomitant fields for all and accumulated phase for static positions at the end of the given sequence.
`find_gradient_blocks`(time_points, grad_wf)	Given an array of single-channel gradient amplitudes (waveform) and corresponding time points, subdivides the waveform into possible trapezoidal and arbitrary gradient definitions.
`get_rotation_matrix`(slice_normal, ...[, ...])	Evaluates a rotation matrix according which can be used to transform between MPS and XYZ coordinates.
`grid_sequence_list`(sequence_list[, ...])	Grids RF, Gradients and adc_events of all sequences in the provided List.
`mps_to_xyz`(gradients[, slice_normal, ...])	Converts from MPS formalism to scanner coordinates XYZ. Default scheme is Coronal slice
`report`(seq[, format])	Creates Sequence report in specified format. Contained values: - Counter per block type - Non-unique block names - Flip angles of RF-events - RF-peak power of RF-waveforms - Center-timing of acquisition events - Max gradient per channel - Max gradient magnitude (norm of all axes) - Max gradient slew per channel - Max gradient slew norm.
`xyz_to_mps`(gradients[, slice_normal, ...])	Converts from XYZ formalism to scanner coordinates MPS. Default scheme is Coronal slice

calculate_diffusion_weighting(seq, return_bmatrix=False, return_cumulative=False)[source]#

Evaluates the b-value or b-matrix of arbitrary gradient waveforms by numerical integration.

Parameters:

seq (Sequence) – Sequence object, which is gridded to obtain hte waveform
return_bmatrix (bool) – If True returns the b-matrix instead of the scalar b-value
return_cumulative (bool) – if True returns the bvalue on raster-time resolution

Returns:

Quantity of shape (1, ) or (t, ) depending on return_cumulative argument

calculate_gradient_spectra(sequence, directions, start_time=None, end_time=None, interpolation_subfactor=1, pad_factor=10)[source]#

Calculates gradient sampling spectra along a given direction according to:

\[ \begin{align}\begin{aligned}S(\omega,t) = |\tilde{q}(\omega,t)|^2\\\tilde{q}(\omega,t) = \int_{0}^{t}q(t')e^{i\omega t'}dt'\\q(t) = \gamma \int_{0}^{t}G(t')dt'\end{aligned}\end{align} \]

where G(t) is the gradient. Spectra returns in units of \(mT^2/m^2/ms^4\)

Parameters:

sequence (Sequence) – Sequence to calculate spectra on
directions (List[ndarray]) – List[np.ndarray of shape (3, )] denoting the directions to calculate spectra along
start_time (Optional[Quantity]) – Quantity[Time] Start time of spectra calculation window
end_time (Optional[Quantity]) – Quantity[Time] End time of spectra calculation window
interpolation_subfactor (int) – int, factor to divide sequence raster time by for spectra calculation
pad_factor (int) – int, multiplicative pad factor prior to fourier transform. Used to better resolve low frequencies

Returns:

(List[Spectra],Frequency) Tuple of arrays giving spectra and frequency axis

concomitant_fields(sequence, coordinates)[source]#

Computes concomitant fields for all and accumulated phase for static positions at the end of the given sequence.

\[ \begin{align}\begin{aligned}B_c(t) = (g_z^2/(8B_0))(x^2 + y^2) + (g_x^2 + g_y^2)/(2 B_0)z^2 - (g_x g_z)/(2B_0) xz - (g_y g_z)/(2B_0)yz\\\phi_c(t) = \int_0^t \gamma / B_c(t\prime) dt\prime\end{aligned}\end{align} \]

Parameters:

sequence (Sequence) –
coordinates (ndarray) – (…, [x, y, z])

Returns:

find_gradient_blocks(time_points, grad_wf)[source]#

Given an array of single-channel gradient amplitudes (waveform) and corresponding time points, subdivides the waveform into possible trapezoidal and arbitrary gradient definitions.

Assumes that for consecutive trapezoids, the zero-crossing is explicitly included, otherwise the two lobes are combined into one arbitrary waveform. Trapezoids, include triangular gradient pulses. Zero-crossings of arbitrary gradients (such as spirals) are not used to subdivide the shape.

Note

Comparison by value of inflection points and slew-rates are done up to the precision on 1e-8, therefore it is advisable to adhere to the stated units or scale correspondingly!

Parameters:

time_points (ndarray) – (t, ) array of time-points in ms
grad_wf (ndarray) – (t, ) array of gradient-waveforms in mT/m

Return type:

List[Tuple[str, ndarray, ndarray]]

Returns:

Temporally ordered gradient definitions containing: - the type (trapezoid/arbitrary) - the time-points (t_i,) - the gradient samples (g_i, )

get_rotation_matrix(slice_normal, readout_direction, target_orientation='xyz')[source]#

Evaluates a rotation matrix according which can be used to transform between MPS and XYZ coordinates. If M and S are not orthogonal, M is adjusted.

Parameters:

slice_normal (ndarray) – Slice normal vector in XYZ coordinates
readout_direction (ndarray) – Readout vector in XYZ coordinates
target_orientation (str) – str, either (‘mps’, ‘xyz’)

Return type:

ndarray

Returns:

(3, 3) array the 0th axis indexes the M/P/S vector in cartesian coordinates

M = R[0, :]
P = R[1, :]
S = R[2, :]

grid_sequence_list(sequence_list, force_uniform_grid=False)[source]#

Grids RF, Gradients and adc_events of all sequences in the provided List.

Parameters:

sequence_list (List[Sequence]) –
force_uniform_grid (bool) – bool if False the ADC-events are inserted into the time grid resulting in a non-uniform raster per TR

Return type:

Tuple[List[ndarray], ...]

Returns:

(time, rf_list, wf_list, adc_list)

mps_to_xyz(gradients, slice_normal=array([1., 0., 0.]), readout_direction=array([0., 0., 1.]))[source]#

Converts from MPS formalism to scanner coordinates XYZ. Default scheme is Coronal slice: with measurement in Z If M and S are not orthogonal, M is adjusted.

Parameters:

gradients (ndarray) – (…, 3) np.array containing gradient waveforms defined in MPS coordinates
slice_normal (ndarray) – np.array (3, ) containing the slice orientation in XYZ coordinates
readout_direction (ndarray) – np.array (3, ) containing the readout direction in XYZ coordinates

Return type:

ndarray

Returns:

(…, 3) rotated gradient waveform in XYZ coordinates

report(seq, format='str')[source]#

Creates Sequence report in specified format. Contained values:

Counter per block type

Non-unique block names

Flip angles of RF-events

RF-peak power of RF-waveforms

Center-timing of acquisition events

Max gradient per channel

Max gradient magnitude (norm of all axes)

Max gradient slew per channel

Max gradient slew norm

Raises:

NotImplementedError if format not in [str, json, html, dict]

Return type:

Union[str, dict]

Returns:

string in specified format or dictionary containing the values

Parameters:

seq (cmrseq.Sequence) –
format (str) –

xyz_to_mps(gradients, slice_normal=array([1., 0., 0.]), readout_direction=array([0., 0., 1.]))[source]#

Converts from XYZ formalism to scanner coordinates MPS. Default scheme is Coronal slice: with measurement in Z If M and S are not orthogonal, M is adjusted.

Parameters:

gradients (ndarray) – (…, 3) np.array containing gradient waveforms defined in XYZ coordinates
slice_normal (ndarray) – np.array (3, ) containing the slice orientation in XYZ coordinates
readout_direction (ndarray) – np.array (3, ) containing the readout direction in XYZ coordinates

Return type:

ndarray

Returns:

(…, 3) rotated gradient waveform in MPS coordinates