DictionaryMatcher

class blochsim.estimators.DictionaryMatcher

Bases: Estimator

Match signals to dictionary atoms by normalized complex inner product.

Parameters:

• acquisition (Simulator, default=None) – The sequence being inverted, with every property that is neither unknown nor measured separately already fixed. Omit to give dictionary or signals to fit().

• dictionary (torch.Tensor, default=None) – Atoms (n_atoms, n_contrasts), real or complex.

• parameters (torch.Tensor, default=None) – Parameter values (n_atoms, n_parameters) of the atoms. Without them a call returns atom indices.

• query_chunk_size (int, default=4096) – Measured signals compared at once.

• dictionary_chunk_size (int, default=16384) – Atoms compared at once.

• top_k (int, default=1) – Candidates kept by match(); the first is the estimate.

• groups (int, default=None) – Cluster the dictionary into this many groups and score group representatives first, discarding groups before scoring their atoms [1]. See grouping.

• prune (float, default=5e-3) – Fraction below its best group score within which a voxel still considers a group. Larger keeps more groups. The default was tuned on 280 groups of 700 atoms; raise it for smaller dictionaries.

Notes

A rank given to fit() compresses the dictionary to (atoms, rank) before grouping. The estimator also returns an M0 map, computed from the match score and atom norms without touching atoms. Volumes are streamed as map(execution=...) says.

References

[1]

Cauley, S. F., Setsompop, K., Ma, D., et al., “Fast group matching for MR fingerprinting reconstruction”, Magnetic Resonance in Medicine 74.2 (2015), pp. 523-528. https://doi.org/10.1002/mrm.25439

Methods

fit	Fit the estimator over a sampling of the tissue it will meet.
from_coefficients	Map coefficients already in this estimator's basis.
map	Estimate the tissue parameters of a measured volume.
match	Find the best-matching atoms of each measured signal.
training_set	Simulate a training set from the properties given to fit().
uncertainty_of	Uncertainty of each map, as a standard deviation in the map's units.

property fitted

Whether the matcher holds a dictionary.

property grouping

Clustering of the dictionary, or None without groups.

Its condition is the condition number of the representatives and compression the factor by which in-group inner products shorten.

match()

Find the best-matching atoms of each measured signal.

Parameters:

signals (torch.Tensor) – Measurements (..., contrasts).

Returns:

Fields shaped (..., top_k).

Return type:

MatchResult

Raises:

• RuntimeError – If there is no dictionary.

• ValueError – If the contrast count differs from the dictionary’s.