apps.mobafit

apps.mobafit#

bartorch.apps.mobafit()#

Fit a signal model to reconstructed contrast images, voxel by voxel.

The pipeline BART’s mobafit command runs, assembled here: a forward model from bartorch.nlop, the Gauss-Newton loop of bartorch.nlop.IRGNM over it, and the fitted variables read back into their own units.

The model is TorchSim’s rather than BART’s – what a fit needs is a forward it can differentiate, with bounds and a starting state, which is what SignalModel is over a TorchSim simulator – so this does not reproduce the command’s coefficients. It solves the same problem with the same method and answers in named maps.

Parameters:

  • images (torch.Tensor) – Contrast images, (contrasts, *voxels), C order: one image per echo, inversion time or repetition, in the order the model’s acquisition lists them. Any intensity units: a model with an amplitude is fitted to the images scaled to unit peak, and the amplitude, given or fitted, is in the units of images.

  • model (bartorch.nlop.SignalModel) – The signal model, built on the acquisition that produced images – MultiEcho(), InversionRecovery() or Bloch() – on the voxel shape of images.

  • iterations (int, default=20) – Gauss-Newton steps. The command takes five over its own scaled coefficients; twenty are what a bounded parameterisation needs.

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

  • inner (solver, default=None) – A configured solver from bartorch.optim for the linearized problem, whose regularizers then penalize the maps. The default is plain conjugate gradients, which is what the command solves with.

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

  • alpha_min (float, default=0.0) – What that weight decays towards.

  • redu (float, default=2.0) – Factor the weight is divided by after each step.

  • magnitude (bool, default=False) – Fit the magnitude of the model to the magnitude of the data rather than the signal itself, which is BART’s -a.

  • start (torch.Tensor, default=None) – Maps to start from, of the model’s input shape. Built from **values when it is not given.

  • reference (dict of str, default=None) – Maps each Gauss-Newton step is regularized towards, {name: value} in each property’s own units as **values takes them; a name left out takes the model’s default. A value outside the model’s bounds is clamped to them, so a limit such as a vanishing rate is approached from inside. Without it each step is regularized towards zero in the model’s variables, as the command’s is: the middle of each bound and no amplitude.

  • **values – Starting values per unknown, in that property’s own units, as initial() takes them.

Returns:

The fitted maps in their own units, by the name each unknown carries. A voxel whose data is zero across every contrast is left at the value it started from, as the command leaves such a patch at zero.

Return type:

dict of str to torch.Tensor

Examples

>>> M = nlop.MultiEcho([12.5 * (echo + 1) for echo in range(8)], (128, 128))
>>> maps = mobafit(images, M, T2=80.0)
>>> maps["T2"]

Examples using mobafit#

Parameter maps straight from k-space

Parameter maps straight from k-space

Parameter maps from scanner images

Parameter maps from scanner images