uGUIDE.estimate_microstructure

uGUIDE.estimate_microstructure(x: Tensor, config: Dict, postprocessing=None, verbose: bool = False, plot: bool = False, plot_max_voxels: int = 5, plot_random: bool = True, theta_gt: Tensor | None = None) → Tuple[Tensor, Tensor, Tensor, Tensor, Tensor]

Estimate microstructure parameters given observed diffusion MRI signals. The posterior distributions are obtained by sampling from the normalizing flow. If a problem occurs, mask is set to False for the corresponding parameter(s). Then the posterior distribution is defined as degenerate or not. Finally this function extracts and returns the maximum-a-posteriori, the uncertainty and the ambiguity from the estimated posterior distributions for each voxel.

Parameters:

xtorch.Tensor, shape (N_voxels, config[‘size_x’])

Observed diffusion MRI signal. Its size must be identical to the signals used for training (i.e. config['size_x'])

configdict

μGUIDE configuration.

postprocessingfunction, optional

If one or multiple microstructure parameters in the model definition are not uniformly distributed, surrogate parameters need to be used instead during training. This function allows to convert those surrogate parameters into the model microstructure parameters. If set to None, no conversion is performed.

verbosebool, default=False

Whether to print messages about the estimation process, especially invalid cases where the estimation did not work.

plotbool, default=True

Whether to save the posterior distributions.

plot_max_voxelsint, default=5

Maximum number of voxels to plot the posterior distributions for. If the number of voxels to estimate is higher than this number, only a random subset of voxels will be plotted if plot_random is set to True. If plot_random is set to False, the first plot_max_voxels will be plotted.

plot_randombool, default=True

Whether to randomly select the voxels to plot the posterior distributions for when the number of voxels to estimate is higher than plot_max_voxels.

theta_gttorch.Tensor, optional

Ground truth value corresponding to the observed signal x, whith size (config[‘size_theta’],). Used when testing on simulations. Adds a vertical dashed black line on the plotted posterior distributions.

Returns:

maptorch.Tensor, shape (N, size_theta)

Maximum-a-posteriori estimated for each microstructure parameter from the posterior distributions.

masktorch.Tensor, shape (N, size_theta)

Default to True. Set to False if a parameter estimation did not work.

degeneracy_masktorch.Tensor, shape (N, size_theta)

Set to True if a posterior distribution is defined as degenerate. False otherwise.

uncertaintytorch.Tensor, shape (N, size_theta)

Uncertainty measure estimated for each microstructure parameter from the posterior distributions (in %).

ambiguitytorch.Tensor, shape (N, size_theta)

Ambiguity measure estimated for each microstructure parameter from the posterior distributions (in %).