apps.moba

apps.moba#

bartorch.apps.moba()#

Fit a signal model to k-space: model-based reconstruction of parameter maps.

The method of BART’s moba: the model y = P F (S . M(theta)), fitted to the samples by Gauss-Newton (bartorch.nlop.IRGNM). Without sensitivities the coils are a second unknown, shared by the contrasts and represented as in NonlinearSense, under a Sobolev weighting. The model is BlochSim’s (ModelOperator), so the result is named maps in physical units rather than the command’s coefficients.

Parameters:

  • kspace (torch.Tensor) – Samples (contrasts, coils, *samples), C order, contrasts in the order of the model’s acquisition. *samples is the voxel shape on a grid, and traj.shape[:-1] without a leading contrast axis along a trajectory.

  • model (bartorch.nlop.ModelOperator) – Signal model on the voxel shape, (y, x) or (z, y, x).

  • sensitivities (torch.Tensor, default=None) – Coil sensitivities (coils, *voxels), shared by the contrasts; estimated jointly with the maps when None.

  • traj (torch.Tensor, default=None) – Trajectory (..., samples, 3) in grid units, shared by the contrasts or with a leading contrast axis. Requires sensitivities.

  • pattern (torch.Tensor, default=None) – Sampling pattern or weights broadcastable against kspace, of size one along the coil axis; may differ between contrasts. None on a grid is one wherever any coil has a sample.

  • iterations (int, default=20) – Gauss-Newton steps. The command’s 8 suffice for its scaled coefficients, not for the bounded parameterization.

  • cg_maxiter (int, default=50) – Conjugate-gradient iterations per linearized problem.

  • inner (solver, default=None) – Solver from bartorch.optim for the linearized problem, whose regularizers penalize the maps; requires sensitivities. None is conjugate gradients.

  • alpha (float, default=1.0) – Tikhonov weight of the first Gauss-Newton step.

  • alpha_min (float, default=0.0) – Limit the weight decays towards.

  • redu (float, default=2.0) – Decay factor of the weight per step.

  • sobolev (tuple of float, default=(880.0, 32.0)) – (a, b) of the coil weighting (1 + a |k|^2)^(-b/2) when the coils are estimated; the command’s defaults.

  • smooth (dict of str to tuple of float, default=None) – {name: (a, b)}: properties solved for as smooth maps, through the weighting (1 + a |k|^2)^(-b/2) of Sobolev, as the command treats its B1 and B0 maps. The weighting applies to the model’s variable, the transformed value for a bounded property.

  • start (torch.Tensor, default=None) – Starting point in the model’s domain, with the amplitude divided by scaling; built from **values when None. A smooth property enters through the weighting’s adjoint, which keeps a constant map and smooths any other.

  • reference (dict of str, default=None) – Values each step is regularized towards, {name: value} in physical units with an amplitude in the units of kspace; unnamed properties take the model’s defaults, and values are clamped strictly inside the model’s bounds. None uses the start. The coil coefficients are regularized towards zero.

  • scaling (float, default=None) – Factor the data is divided by for the solve; the fitted amplitude is multiplied by it again. None applies the rule of bartorch.optim.data_scaling() to least-squares contrast images (known coils) or zero-filled coil images (estimated coils). A model without an amplitude is fitted to unscaled data.

  • return_sensitivities (bool, default=False) – Also return the estimated sensitivities.

  • **values – Starting values name=value in physical units, as initial() takes them, with an amplitude in the units of kspace.

Returns:

  • maps (dict of str to torch.Tensor) – Fitted maps in physical units, keyed by unknown. With estimated coils, amplitude and sensitivities share a complex factor the data does not determine.

  • sensitivities (torch.Tensor) – Estimated sensitivities (coils, *voxels); only with return_sensitivities.

Raises:

ValueError – If traj or inner is given without sensitivities, if return_sensitivities is set with sensitivities, if kspace does not match the encoding’s samples, or if smooth names a property the model does not solve for.

Notes

BART regularizes each step towards zero. Zero in the bounded parameterization is the middle of each bound with no amplitude, and with the coils starting at zero the data has no derivative by the maps there, so the default centre is the start instead. Its influence decays with the Tikhonov weight.

Examples

>>> M = nlop.MultiEcho([12.5 * (echo + 1) for echo in range(8)], (128, 128))
>>> maps = moba(kspace, M, sensitivities, T2=80.0)
>>> maps, sensitivities = moba(kspace, M, return_sensitivities=True, T2=80.0)

Examples using moba#

9. Nonlinear inversion for T2 mapping

9. Nonlinear inversion for T2 mapping