ssfp

SSFP constrast simulation functions.

mr_utils.sim.ssfp.ssfp.elliptical_params(T1, T2, TR, alpha, M0=1)[source]

Return ellipse parameters M, a, b.

Parameters:
  • T1 (array_like) – longitudinal exponential decay time constant (in sec).
  • T2 (array_like) – transverse exponential decay time constant (in sec).
  • TR (float) – repetition time (in sec).
  • alpha (float) – flip angle (in rad).
  • M0 (array_like, optional) – Proton density.
Returns:

  • M (array_like) – Cross point.
  • a (array_like) – Theta-independent ellipse parameter.
  • b (array_like) – Theta-independent ellipse parameter.

Notes

Outputs are the parameters of ellipse an ellipse, (M, a, b). These parameters do not depend on theta.

Implementation of equations [3-5] in [1].

mr_utils.sim.ssfp.ssfp.get_bssfp_phase(T2, TR, field_map, delta_cs=0, phi_rf=0, phi_edd=0, phi_drift=0)[source]

Additional bSSFP phase factors.

Parameters:
  • T2 (array_like) – Longitudinal relaxation constant (in sec).
  • TR (float) – Repetition time (in sec).
  • field_map (array_like) – off-resonance map (Hz).
  • delta_cs (float, optional) – chemical shift of species w.r.t. the water peak (Hz).
  • phi_rf (float, optional) – RF phase offset, related to the combin. of Tx/Rx phases (rad).
  • phi_edd (float, optional) – phase errors due to eddy current effects (rad).
  • phi_drift (float, optional) – phase errors due to B0 drift (rad).
Returns:

phase – Additional phase term to simulate readout at time TE = TR/2. Assumes balanced (TE = TR/2).
Return type:

array_like

Notes

This is exp(-i phi) from end of p. 930 in [1].

We use a positive exponent, exp(i phi), as in Hoff and Taylor MATLAB implementations. This phase factor is also positive in equaiton [5] of [3].

In Hoff’s paper the equation is not explicitly given for phi, so we implement equation [5] that gives more detailed terms, found in [2].

References

[2](1, 2, 3) Shcherbakova, Yulia, et al. “PLANET: An ellipse fitting approach for simultaneous T1 and T2 mapping using phase‐cycled balanced steady‐state free precession.” Magnetic resonance in medicine 79.2 (2018): 711-722.
[3]Scheffler, Klaus, and Jürgen Hennig. “Is TrueFISP a gradient‐echo or a spin‐echo sequence?.” Magnetic Resonance in Medicine: An Official Journal of the International Society for Magnetic Resonance in Medicine 49.2 (2003): 395-397.
mr_utils.sim.ssfp.ssfp.get_cart_elliptical_params(M, a, b)[source]

Get parameters needed for cartesian representation of ellipse.

Parameters:
  • M (array_like) – Cross point.
  • a (array_like) – Theta-independent ellipse parameter.
  • b (array_like) – Theta-independent ellipse parameter.
Returns:

  • xc (array_like) – x coordinates of geometric center of ellipse.
  • yc (array_like) – y coordinates of geometric center of ellipse.
  • A (array_like) – Semi-major axis.
  • B (array_like) – Semi-minor axis.
mr_utils.sim.ssfp.ssfp.get_center_of_mass(M, a, b)[source]

Give center of mass a function of ellipse parameters.

Parameters:
  • M (array_like) – Cross point.
  • a (array_like) – Theta-independent ellipse parameter.
  • b (array_like) – Theta-independent ellipse parameter.
Returns:

cm – Center of mass.
Return type:

array_like
mr_utils.sim.ssfp.ssfp.get_center_of_mass_nmr(T1, T2, TR, alpha, M0=1)[source]

Give center of mass as a function of NMR parameters.

Parameters:
  • T1 (array_like) – longitudinal exponential decay time constant (in sec).
  • T2 (array_like) – transverse exponential decay time constant (in sec).
  • TR (float) – Repetition time (in sec).
  • alpha (float) – Flip angle (in rad).
  • M0 (array_like, optional) – Proton density.
Returns:

cm – Center of mass.
Return type:

array_like
mr_utils.sim.ssfp.ssfp.get_complex_cross_point(Is)[source]

Find intersection of two lines connecting diagonal pairs.

Parameters:Is (array_like) – 4 phase-cycled images: [I0, I1, I2, I3].
Returns:M – Complex cross point.
Return type:array_like

Notes

We assume that Is has the phase-cycle dimenension along the first axis.

(xi, yi) are the real and imaginary parts of complex valued pixels in four bSSFP images denoted Ii and acquired with phase cycling dtheta = (i-1)*pi/2 with 0 < i < 4.

This is Equation [13] from [1].

mr_utils.sim.ssfp.ssfp.get_cross_point(I1, I2, I3, I4)[source]

Find intersection of two lines connecting diagonal pairs.

Parameters:
  • I1 (array_like) – First of the first phase-cycle pair (0 degrees).
  • I2 (array_like) – First of the second phase-cycle pair (90 degrees).
  • I3 (array_like) – Second of the first phase-cycle pair (180 degrees).
  • I4 (array_like) – Second of the second phase-cycle pair (270 degrees).
Returns:

  • x0 (array_like) – x coordinate of cross point.
  • y0 (array_like) – y coordinate of cross point.

Notes

(xi,yi) are the real and imaginary parts of complex valued pixels in four bSSFP images denoted Ii and acquired with phase cycling dtheta = (i-1)*pi/2 with 0 < i < 4.

This are Equations [11-12] from [1]. There is a typo in the paper for equation [12] fixed in this implementation. The first term of the numerator should have (y2 - y4) instead of (x2 - y4) as written.

mr_utils.sim.ssfp.ssfp.get_geo_center(M, a, b)[source]

Get geometric center of ellipse.

Parameters:
  • M (array_like) – Cross point.
  • a (array_like) – Theta-independent ellipse parameter.
  • b (array_like) – Theta-independent ellipse parameter.
Returns:

  • xc (array_like) – x coordinates of geometric center of ellipse.
  • yc (array_like) – y coordinates of geometric center of ellipse.
mr_utils.sim.ssfp.ssfp.get_theta(TR, field_map, phase_cyc=0, delta_cs=0)[source]

Get theta, spin phase per repetition time, given off-resonance.

Parameters:
  • TR (float) – repetition time (in sec).
  • field_map (array_like) – Off-resonance map (in Hz).
  • phase_cyc (array_like, optional) – Phase-cycling (in rad).
  • delta_cs (float, optional, optional) – Chemical shift of species w.r.t. the water peak (Hz).
Returns:

theta – Spin phase per repetition time, given off-resonance.
Return type:

array_like

Notes

Equation for theta=2*pi*df*TR is in Appendix A of [6]. The additional chemical shift term can be found, e.g., in [2].

References

[6]Hargreaves, Brian A., et al. “Characterization and reduction of the transient response in steady‐state MR imaging.” Magnetic Resonance in Medicine: An Official Journal of the International Society for Magnetic Resonance in Medicine 46.1 (2001): 149-158.
mr_utils.sim.ssfp.ssfp.make_cart_ellipse(xc, yc, A, B, num_t=100)[source]

Make a cartesian ellipse, return x,y coordinates for plotting.

Parameters:
  • xc (array_like) – x coordinates of geometric center of ellipse.
  • yc (array_like) – y coordinates of geometric center of ellipse.
  • A (array_like) – Semi-major axis.
  • B (array_like) – Semi-minor axis.
Returns:

  • x (array_like) – Cartesian x coordinates.
  • y (array_like) – Cartesian y coordinates.
mr_utils.sim.ssfp.ssfp.spectrum(T1, T2, TR, alpha)[source]

Generate an entire period of the bSSFP signal profile.

Parameters:
  • T1 (array_like) – longitudinal exponential decay time constant (in sec).
  • T2 (array_like) – transverse exponential decay time constant (in sec).
  • TR (float) – Repetition time (in sec).
  • alpha (float) – Flip angle (in rad).
Returns:

sig – Full, complex SSFP spectrum.
Return type:

array_like
mr_utils.sim.ssfp.ssfp.ssfp(T1, T2, TR, alpha, field_map, phase_cyc=0, M0=1, delta_cs=0, phi_rf=0, phi_edd=0, phi_drift=0)[source]

SSFP transverse signal at time TE after excitation.

Parameters:
  • T1 (float or array_like) – longitudinal exponential decay time constant (in seconds).
  • T2 (float or array_like) – transverse exponential decay time constant (in seconds).
  • TR (float) – repetition time (in seconds).
  • alpha (float or array_like) – flip angle (in rad).
  • field_map (float or array_like) – B0 field map (in Hz).
  • phase_cyc (float or array_like, optional) – Linear phase-cycle increment (in rad).
  • M0 (float or array_like, optional) – proton density.
  • delta_cs (float, optional) – chemical shift of species w.r.t. the water peak (in Hz).
  • phi_rf (float, optional) – RF phase offset, related to the combin. of Tx/Rx phases (in rad).
  • phi_edd (float, optional) – phase errors due to eddy current effects (in rad).
  • phi_drift (float, optional) – phase errors due to B0 drift (in rad).
Returns:

Mxy – Transverse complex magnetization.
Return type:

numpy.array

Notes

T1, T2, alpha, field_map, and M0 can all be either a scalar or an MxN array. phase_cyc can be a scalar or length L vector.

Implementation of equations [1–2] in [1]. These equations are based on the Ernst-Anderson derivation [4] where off-resonance is assumed to be subtracted as opposed to added (as in the Freeman-Hill derivation [5]). Hoff actually gets Mx and My flipped in the paper, so we fix that here. We also assume that the field map will be provided given the Freeman-Hill convention.

We will additionally assume that linear phase increments (phase_cyc) will be given in the form:

\[\theta = 2 \pi (\delta_{cs} + \Delta f_0)\text{TR} + \Delta \theta.\]

Notice that this is opposite of the convention used in PLANET, where phase_cyc is subtracted (see equation [12] in [2]).

Also see equations [2.7] and [2.10a–b] from [4] and equations [3] and [6–12] from [5].

References

[1](1, 2, 3, 4, 5) Xiang, Qing‐San, and Michael N. Hoff. “Banding artifact removal for bSSFP imaging with an elliptical signal model.” Magnetic resonance in medicine 71.3 (2014): 927-933.
[4](1, 2) Ernst, Richard R., and Weston A. Anderson. “Application of Fourier transform spectroscopy to magnetic resonance.” Review of Scientific Instruments 37.1 (1966): 93-102.
[5](1, 2) Freeman R, Hill H. Phase and intensity anomalies in fourier transform NMR. J Magn Reson 1971;4:366–383.
mr_utils.sim.ssfp.ssfp.ssfp_from_ellipse(M, a, b, TR, field_map, phase_cyc=0)[source]

Simulate banding given elliptical signal params and field map.

Parameters:
  • M (array_like) – Cross point.
  • a (array_like) – Theta-independent ellipse parameter.
  • b (array_like) – Theta-independent ellipse parameter.
  • TR (float) – Repetition time (in sec).
  • field_map (array_like) – Off-resonance map (in Hz).
  • phase_cyc (float) – Phase-cycling increment (in rad).
Returns:

I – SSFP simulation result.
Return type:

array_like
mr_utils.sim.ssfp.ssfp.ssfp_old(T1, T2, TR, alpha, field_map, phase_cyc=0, M0=1)[source]

Legacy SSFP sim code. Try using current SSFP function.