mrpro.operators.DictionaryMatchOp

class mrpro.operators.DictionaryMatchOp[source]

Bases: Operator[Tensor, tuple[Unpack[Tin]]]

Dictionary Matching Operator.

This operator can be used for dictionary matching, for example in magnetic ressonance fingerprinting.

It performs absolute normalized dot product matching between a dictionary of signals, i.e. find the entry \(d^*\) in the dictionary maximizing \(\left|\frac{d}{\|d\|} \cdot \frac{y}{\|y\|}\right|\) and returns the associated signal model parameters \(x\) generating the matching signal \(d^*=d(x)\).

At initialization, a signal model needs to be provided. Afterwards append with different x values should be called to add entries to the dictionary. This operator then calculates for each x value the signal returned by the model. To perform a match, use __call__ and supply some y values. The operator will then perform the dot product matching and return the associated x values.

__init__(generating_function: Callable[[Unpack[Tin]], tuple[Tensor]], index_of_scaling_parameter: int | None = None)[source]

Initialize DictionaryMatchOp.

Parameters:

  • generating_function (Callable[[Unpack[TypeVarTuple]], tuple[Tensor]]) – signal model that takes n inputs and returns a signal y.

  • index_of_scaling_parameter (int | None, default: None) –

    Normalized dot product matching is insensitive to overall signal scaling. A scaling factor (e.g. the equilibrium magnetization m0 in InversionRecovery) is calculated after the dictionary matching if index_of_scaling_parameter is not None. index_of_scaling_parameter should set to the index of the scaling parameter in the signal model.

    Example:

    For ~mrpro.operators.models.InversionRecovery the parameters are [m0, t1] and therefore index_of_scaling_parameter should be set to 0. The operator will then return t1 estimated via dictionary matching and m0 via a post-processing step. If index_of_scaling_parameter is None, the value returned for m0 will be meaningless.

__call__(*args: Unpack[Tin]) → Tout[source]

Apply the forward operator.

For more information, see forward.

Note

Prefer using operator_instance(*parameters), i.e. using __call__ over using forward.

forward(input_signal: Tensor) → tuple[Unpack[Tin]][source]

Perform dot-product matching.

Given y values as input_signal, the tuple of x values in the dictionary that result in a signal with the highest dot-product similarity will be returned

Parameters:

input_signal (Tensor) – y values, shape (m ...) where m is the return dimension of the signal model, for example time points.

Returns:

match – tuple of n tensors with shape (…)

append(*x: Unpack[Tin]) → Self[source]

Append x values to the dictionary.

Parameters:

x (Unpack[TypeVarTuple]) – points where the signal model will be evaluated. For signal models with n inputs, n tensors should be provided. Broadcasting is supported.

Returns:

Self

__add__(other: Operator[Unpack[Tin], Tout]) → Operator[Unpack[Tin], Tout][source]
__add__(other: Tensor) → Operator[Unpack[Tin], tuple[Unpack[Tin]]]

Operator addition.

Returns lambda x: self(x) + other(x) if other is a operator, lambda x: self(x) + other*x if other is a tensor

__matmul__(other: Operator[Unpack[Tin2], tuple[Unpack[Tin]]]) → Operator[Unpack[Tin2], Tout][source]

Operator composition.

Returns lambda x: self(other(x))

__mul__(other: Tensor | complex) → Operator[Unpack[Tin], Tout][source]

Operator multiplication with tensor.

Returns lambda x: self(x*other)

__radd__(other: Tensor) → Operator[Unpack[Tin], tuple[Unpack[Tin]]][source]

Operator right addition.

Returns lambda x: other*x + self(x)

__rmul__(other: Tensor | complex) → Operator[Unpack[Tin], Tout][source]

Operator multiplication with tensor.

Returns lambda x: other*self(x)