make_epi_shot_offsets

pypulseqpp.make_epi_shot_offsets()

Return the phase-encoding offsets of one EPI shot, relative to its first echo.

result[e] is (Δky, Δkz), in encoded lines and partitions, of the view acquired at echo e relative to the view acquired at echo 0 of the same shot; result[0] is always (0, 0). For a shot whose first echo acquires the view (y0, z0), echo e acquires (y0, z0) + result[e]. The routine does not select the global acquisition support, does not choose the shot origin (y0, z0), which the scan loop chooses, and creates no Pulseq labels.

With R_y = acceleration and S = segments, the line offset of 'linear' and 'caipi' is Δky_e = e S R_y. S shots with origins y0, y0 + R_y, ..., y0 + (S - 1) R_y therefore interleave to acquire every R_y-th line. 'caipi' adds the partition offset of the CAIPIRINHA lattice with R_z = partition_acceleration and shift Δz = caipi_shift, reduced modulo R_z, so the partition blips cycle through one lattice period; the offsets tile make_caipirinha_mask() exactly. 'zigzag' alternates between an outward and a return pass across extent lines, the return pass displaced by half a blip.

Parameters:

• etl (int) – Echo-train length: the number of echoes, and of rows returned.

• scheme ({'linear', 'caipi', 'zigzag'}, default='linear') – 'linear': segmented or single-shot EPI, Δkz = 0. 'caipi': segmented blipped-CAIPI. 'zigzag': repeated up-and-down traversal of one phase-encoding segment, which acquires the same lines at several echo times; Δkz = 0.

• acceleration (int, default=1) – In-plane undersampling factor R_y.

• segments (int, default=1) – Number of shots S among which the lines are interleaved. The blip is S R_y lines.

• partition_acceleration (int, default=1) – Partition undersampling factor R_z, the period of the partition offsets. 'caipi' only.

• caipi_shift (int, default=1) – CAIPIRINHA shift Δz: partitions the lattice is displaced by per acquired line. 'caipi' only.

• extent (int or None, default=None) – Phase-encoding lines spanned by one pass. Required by 'zigzag' and rejected by the other schemes.

Returns:

Integer array of shape (etl, 2): [Δky, Δkz] of each echo, relative to echo 0.

Return type:

numpy.ndarray

Raises:

ValueError – If a count is out of range, scheme is unknown, or extent is given for a scheme other than 'zigzag' or omitted for it.

See also

make_caipirinha_mask

the lattice the 'caipi' offsets tile.

make_cartesian_plane_sampling

acquisition support of a Cartesian plane.

make_traversal_order

loop order over shots or slices.

Examples

Four echoes at twofold acceleration step two lines per echo:

>>> import pypulseqpp as pp
>>> offsets = pp.make_epi_shot_offsets(4, acceleration=2)
>>> offsets.tolist()
[[0, 0], [2, 0], [4, 0], [6, 0]]

The offsets are relative. With two segments the blip is four lines, and shots with origins at lines 3 and 5 acquire interleaved lines:

>>> offsets = pp.make_epi_shot_offsets(4, acceleration=2, segments=2)
>>> (offsets + [3, 0])[:, 0].tolist()
[3, 7, 11, 15]
>>> (offsets + [5, 0])[:, 0].tolist()
[5, 9, 13, 17]

Segmented blipped-CAIPI with R_z = 3 cycles the partition offset through one lattice period:

>>> pp.make_epi_shot_offsets(
...     6, scheme="caipi", acceleration=2, partition_acceleration=3
... ).tolist()
[[0, 0], [2, 1], [4, 2], [6, 0], [8, 1], [10, 2]]

A zigzag pass turns at extent, and the return pass is displaced by half a blip:

>>> offsets = pp.make_epi_shot_offsets(
...     9, scheme="zigzag", acceleration=4, extent=12
... )
>>> offsets[:, 0].tolist()
[0, 4, 8, 12, 10, 6, 2, 0, 4]