make_shuffling_order

pypulseqpp.make_shuffling_order()

Echo-train ordering of Cartesian views with random echo positions.

This is the echo ordering used by T2 Shuffling [1]. With cluster=True, train membership is formed from contiguous views in raster order (kz, then ky); echo positions within each train are randomly permuted. With cluster=False, train membership is a random partition of the views as well.

The routine orders views that are already selected; it does not select a variable-density support. make_cartesian_plane_sampling with sampling='poisson' selects such a support.

Parameters:

• coords (array_like) – Centred coordinates of the selected views: an (N, 2) array of (ky, kz) or an (N,) array of ky, relative to the k-space centre, which is the origin. Encoded view indices (y, z) on an (n_y, n_z) grid convert as views - (n_y // 2, n_z // 2). Distances and angles are evaluated in the units supplied. Boolean masks are not accepted.

• train_length (int) – Echo-train length, at least 1. The number of shots is ceil(N / train_length).

• seed (int or None, default=None) – Seed of the random permutations. Equal seeds give equal orders.

• cluster (bool, default=True) – Form each train from contiguous views in raster order; when False, assign views to trains at random.

• pad (bool, default=False) – Pad every train to train_length with None, so that the position in a train is the echo index. With False the None entries are removed.

Returns:

trains – trains[s][e] is the row index into coords of the view acquired at echo e of shot s. The values are indices, not coordinates; every row of coords appears exactly once. With pad=True, None marks an echo that acquires no view. Empty coords give [].

Return type:

list of list of int

Raises:

• TypeError – If coords is a boolean mask or not numeric.

• ValueError – If coords does not have shape (N,) or (N, 2), or train_length is not a positive integer.

See also

make_linear_order

the same train membership in raster echo order.

References

[1]

Tamir JI, Uecker M, Chen W, et al. T2 shuffling: sharp, multicontrast, volumetric fast spin-echo imaging. Magnetic Resonance in Medicine. 2017;77(1):180-195. https://doi.org/10.1002/mrm.26102

Examples

Six centred ky views in two shots of three echoes. Each shot contains a contiguous group of views; the echo at which each view is acquired is random:

>>> import pypulseqpp as pp
>>> views = [-3, -2, -1, 0, 1, 2]
>>> trains = pp.make_shuffling_order(views, 3, seed=0)
>>> trains
[[2, 0, 1], [5, 4, 3]]
>>> [[views[i] for i in train] for train in trains]
[[-1, -3, -2], [2, 1, 0]]

Another seed keeps the train membership and changes the echo positions:

>>> other = pp.make_shuffling_order(views, 3, seed=1)
>>> [[views[i] for i in train] for train in other]
[[-3, -2, -1], [2, 0, 1]]