GrogInterpolator

class pygrog.calib.GrogInterpolator(shape, coords, oversamp=None, kernel_width=2, kernel_shape='circle', time_map=None, image_shape=None, stack_shape=())

Bases: object

Data-driven GROG interpolator.

For every non-Cartesian sample, a fixed-size neighbourhood of Cartesian grid points is identified. Each source sample is replicated to all its neighbours and a pre-computed GRAPPA kernel is applied.

Parameters:

• shape (int | list[int] | tuple[int]) – Spatial image size (ny, nx) or (nz, ny, nx).

• coords (NDArray[float]) – Non-Cartesian coordinates, shape (..., npts, ndim) scaled so that the range (-shape/2, shape/2) covers the full FOV.

• oversamp (float | list[float] | tuple[float] | None) – Grid oversampling factor.

• kernel_width (int) – Side-length of the interpolation kernel in oversampled-grid units. Default 2. Candidates whose GROG shift exceeds ±0.5 original-grid units in any dimension are automatically discarded, so this is a soft upper bound: effective neighbourhood shrinks for low oversamp values.

• kernel_shape (str) – 'circle' (2D) / 'sphere' (3D), 'square' / 'cube', or 'cross'. Default 'circle' / 'sphere'.

• time_map (NDArray[float] | None) – Sampling time per point, same leading shape as coords.

Methods

__init__
calc_interp_table	Compute the GRAPPA kernel table and per-replica kernel index.
collect_shots	Sum accumulated shot contributions and return gridded data.
fft_plan	Return the pre-built FFT plan (stored in self.plan).
interpolate	Apply GROG interpolation to sparse Cartesian neighbour samples.
metadata	Return metadata associated with the Cartesian output grid.
set_dataset_shape	Register the full dataset shape for shot-by-shot interpolation.

metadata()

Return metadata associated with the Cartesian output grid.

fft_plan(image_shape=None)

Return the pre-built FFT plan (stored in self.plan).

If image_shape differs from the one used at construction time, a new plan is built on the fly (not cached).

Parameters:

image_shape (tuple[int, ...] | None) – Target image shape. Defaults to the one used at construction.

Returns:

The plan namespace — has grid_shape, image_shape, indices, sqrt_weights, sort_perm, inv_perm, pre_weights (computed property), grid_size, n_samples, plus all original GROG plan fields.

Return type:

types.SimpleNamespace

calc_interp_table(train_data, lamda=0.01, precision=1)

Compute the GRAPPA kernel table and per-replica kernel index.

Parameters:

• train_data (complex array, (coils, ...)) – Calibration k-space region.

• lamda (float) – Tikhonov regularisation.

• precision (int) – Decimal digits for distance rounding.

set_dataset_shape(shape)

Register the full dataset shape for shot-by-shot interpolation.

interpolate(data, shot_index=None, ret_image=False, grid=False)

Apply GROG interpolation to sparse Cartesian neighbour samples.

Parameters:

• data (complex array or Tensor) – (*batch, coils, ..., npts) for full-dataset, or (coils, npts) for shot-by-shot.

• shot_index (int | tuple[int] | None) – If given, accumulate a single shot into the internal buffer.

• ret_image (bool) – If True, return IFFT-reconstructed images.

• grid (bool) –

  If True, scatter the interpolated sparse samples onto a dense oversampled Cartesian grid and return the tuple (gridded_kspace, mask, density) where:

  • gridded_kspace has shape (*batch, *stack, C, *grid_shape);

  • mask has shape (*stack, *grid_shape), real float (1 where at least one sample lands, 0 elsewhere);

  • density has shape (*stack, *grid_shape), real float (sum of squared GROG weights per grid cell — the Toeplitz PSF source).

  Mutually exclusive with ret_image.

Returns:

• Sparse Cartesian samples (n_coils, n_samples) (or image when

• *ret_image=True*), or (gridded_kspace, mask, density) tuple when

• *grid=True, or None when accumulating shots.*

collect_shots()

Sum accumulated shot contributions and return gridded data.