Models¶
Package containig various model files for fitting.
This package contains the various MRI models currently implemented for the toolbox. In additon, the “GeneralModel” can be run with a simple text file to devine new model. An exemplary textfile for simple models can be generated by running the “genDefaultModelfile” function of the “GeneralModel”.
Module holding the biexponential model for fitting.

class
pyqmri.models.BiExpDecay.
Model
(par)¶ Biexponential model for MRI parameter quantification.
This class holds a biexponential model for fitting complex MRI data. It realizes a forward application of the analytical signal expression and the partial derivatives with respesct to each parameter of interest, as required by the abstract methods in the BaseModel.
Parameters: par (dict) – A python dict containing the necessary information to setup the object. Needs to contain the sequence related parametrs, e.g. TR, TE, TI, to fully describe the acquisitio process 
TE
¶ Echo time (or any other timing valid in a biexponential fit).
Type: float

uk_scale
¶ Scaling factors for each unknown to balance the partial derivatives.
Type: list of float

guess
¶ The initial guess. Needs to be set using “computeInitialGuess” prior to fitting.
Type: numpy.array, None

computeInitialGuess
(*args)¶ Initialize unknown array for the fitting.
This function provides an initial guess for the fitting.
Parameters: args (list of objects) – Serves as universal interface. No objects need to be passed here.

rescale
(x)¶ Rescale the unknowns with the scaling factors.
Rescales each unknown with the corresponding scaling factor and applies a 1/x transformation for the time constants of the exponentials, yielding a result in milliseconds.
Parameters: x (numpy.array) – The array of unknowns to be rescaled Returns: The rescaled unknowns Return type: numpy.array

Module holding the diffusion tensor model for fitting.

class
pyqmri.models.DiffdirLL.
Model
(par)¶ Diffusion tensor model for MRI parameter quantification.
This class holds a DTI model for fitting complex MRI data. It realizes a forward application of the analytical signal expression and the partial derivatives with respesct to each parameter of interest, as required by the abstract methods in the BaseModel.
The fitting is based on the Cholesky decomposition of the DTI tensor to achiev an implicit positive definite constrained on each DTI tensor component.
Parameters: par (dict) – A python dict containing the necessary information to setup the object. Needs to contain the sequence related parametrs, e.g. TR, TE, TI, to fully describe the acquisitio process 
b
¶ b values for each diffusion direction.
Type: float

dir
¶ The diffusion direction vectors. Assumed to have length 1.
Type: numpy.array

uk_scale
¶ Scaling factors for each unknown to balance the partial derivatives.
Type: list of float

guess
¶ The initial guess. Needs to be set using “computeInitialGuess” prior to fitting.
Type: numpy.array

phase
¶ The phase of each diffusion direction relative to the b0 image. Estimated during the initial guess using the image series of all directions/bvalue pairs.
Type: numpy.array

b0
¶ The b0 image if present in the data file. None else.
Type: numpy.array

computeInitialGuess
(*args)¶ Initialize unknown array for the fitting.
This function provides an initial guess for the fitting. args[0] is assumed to contain the image series wich is used for phase correction.
Parameters: args (list of objects) – Assumes the image series at potition 0 and optionally computes a phase based on the difference between each image series minus the first image in the series (Scan i minus Scan 0). This phase correction is needed as each diffusion weighting has a different phase.

rescale
(x)¶ Rescale the unknowns with the scaling factors.
Rescales each unknown with the corresponding scaling factor. As the DTI tensor is fitted using the Cholesky decompotion, each entry of the original tensor is recovered by combining the appropriate Cholesky factors after rescaling.
Parameters: x (numpy.array) – The array of unknowns to be rescaled Returns: The rescaled unknowns Return type: numpy.array

Module holding the general model for fitting.

class
pyqmri.models.GeneralModel.
Model
(par)¶ Realization of a generative model based on sympy.
This model can handel all kinds of sympy input in form of a config file. Partial derivatives of the model are automatically generated and a numpy compatible function is build from sumpy equations.
signaleq
¶ The signal equation derived from sympy
Type: sympy derived function

grad
¶ Partial derivatives with respect to the unknowns
Type: list of functions

rescalefun
¶ Type: list of functions

Functions to rescale each parameter

modelparams
¶ List of model parameters
Type: list

indphase
¶ Flag to estimate the phase from a given image series. The phase is normed on the first image. If True, each image will be multiplied by the estimated phase in the forward and gradient evaluation.
Type: bool

init_values
¶ Initial guess for each unknown
Type: list of str

computeInitialGuess
(*args)¶ Initialize unknown array for the fitting.
This function provides an initial guess for the fitting, based on the values on the text file.
Parameters: args (list of objects) – Assumes the image series at potition 0 and optionally computes a phase based on the difference between each image series minus the first image in the series. (Scan i minus Scan 0)

rescale
(x)¶ Rescale the unknowns with the scaling factors.
Rescales each unknown with the corresponding scaling factor and an optional transformation.
Parameters: x (numpy.array) – The array of unknowns to be rescaled Returns: The rescaled unknowns Return type: numpy.array


pyqmri.models.GeneralModel.
genDefaultModelfile
()¶ Generate a default model config file.
This method generates a default model file in the current project folder. This file can be modified or further models can be added.
Module holding the simple image model for image reconstruction.

class
pyqmri.models.ImageReco.
Model
(par)¶ Image reconstruction model for MRI.
A simple linear image model to perform image reconstruction with joint regularization on all Scans.
Parameters: par (dict) – A python dict containing the necessary information to setup the object. Needs to contain the sequence related parametrs, e.g. TR, TE, TI, to fully describe the acquisitio process 
guess
¶ Initial guess for the images. Set after object creation using “computeInitialGuess”
Type: numpy.array, None

computeInitialGuess
(*args)¶ Initialize unknown array for the fitting.
This function provides an initial guess for the fitting.
Parameters: args (list of objects) – Assumes the images series at position 0 and uses it as initial guess.

rescale
(x)¶ Rescale the unknowns with the scaling factors.
Rescales each unknown with the corresponding scaling.
Parameters: x (numpy.array) – The array of unknowns to be rescaled Returns: The rescaled unknowns Return type: numpy.array

Module holding the inversion recovers LookLocker quantification model.

class
pyqmri.models.IRLL.
Model
(par)¶ Inversion recovery LookLocker model for MRI parameter quantification.
This class holds a IRLL model for T1 quantification from complex MRI data. It realizes a forward application of the analytical signal expression and the partial derivatives with respesct to each parameter of interest, as required by the abstract methods in the BaseModel. The fitting target is the exponential term itself which is easier to fit than the corresponding timing constant.
The rescale function applies a transformation and returns the expected T1 values in ms.
The implemented signal model follows the work from Henderson et al. (1999)
The model should only be used for radially acquired data!
Parameters: par (dict) – A python dict containing the necessary information to setup the object. Needs to contain the sequence related parametrs, e.g. TR, TE, TI, to fully describe the acquisitio process 
TR
¶ Repetition time of the IRLL sequence.
Type: float

fa
¶ Flip angle of the gradient echo sequence.
Type: float

tau
¶ Repetition time for one gradient echo read out.
Type: float

td
¶ Delay prio to first readout point after inversion.
Type: float

Nproj
¶ Number of projections per bin
Type: int

Nproj_measrued
¶ Total number of projections measured
Type: int

uk_scale
¶ Scaling factors for each unknown to balance the partial derivatives.
Type: list of float

guess
¶ The initial guess. Needs to be set using “computeInitialGuess” prior to fitting.
Type: numpy.array, None

scale
¶ A scaling factor to balance the different exponential terms.
Type: float

computeInitialGuess
(*args)¶ Initialize unknown array for the fitting.
This function provides an initial guess for the fitting.
Parameters: args (list of objects) – Serves as universal interface. No objects need to be passed here.

rescale
(x)¶ Rescale the unknowns with the scaling factors.
Rescales each unknown with the corresponding scaling factor and applies a transformation for the time constants of the exponentials, yielding a resulting T1 in milliseconds.
Parameters: x (numpy.array) – The array of unknowns to be rescaled Returns: The rescaled unknowns Return type: numpy.array

Module holding the template base class model.

class
pyqmri.models.template.
BaseModel
(par)¶ Base model for MRI parameter quantification.
This class holds the base model to derive other signal models from. It defines abstract a forward application of the analytical signal expression and the partial derivatives with respesct to each parameter of interest.
Parameters: par (dict) – A python dict containing the necessary information to setup the object. Needs to contain the sequence related parametrs, e.g. Number of Scans, Slices, and image dimension. 
constraints
¶ An empy list of constrains objects.
Type: list of pyqmri.models.template.constrains

NScan
¶ Number of scans (dynamics).
Type: int

NSlice
¶ Number of slices.
Type: int

dimX, dimY
The image dimensions.
Type: int

computeInitialGuess
(*args)¶ Initialize unknown array for the fitting.
This function provides an initial guess for the fitting.

execute_forward
(x, islice=None)¶ Execute the signal model from parameter to imagespace.
This function exectues the given signal model to generate an image series, given estimated parameters.
Parameters:  x (numpy.array) – The array of quantitative parameters to be fitted
 islice (int, None) – Currently unused.

execute_gradient
(x, islice=None)¶ Execute the partial derivatives of the signal model.
This function exectues the partial derivatives with respect to each unknown parameter, based on the signal model.
Parameters:  x (numpy.array) – The array of quantitative parameters to be fitted
 islice (int, None) – Currently unused.

plot_unknowns
(x)¶ Plot the unkowns in an interactive figure.
This function can be used to plot intermediate results during the optimization process.
Parameters: x (dict) – A Python dictionary containing the array of unknowns to be displayed, the associated names and real value constrains.

rescale
(x)¶ Rescale the unknowns with the scaling factors.
Rescales each unknown with the corresponding scaling factor.
Parameters: x (numpy.array) – The array of unknowns to be rescaled Returns: The rescaled unknowns Return type: numpy.array


class
pyqmri.models.template.
constraints
(min_val=inf, max_val=inf, real_const=False)¶ Constraints for a parameter.
This class holds min/max and real value constrains for a parameter. It supports updating these based on the current estimated sclaing between each partial derivative.
Parameters:  min_val (float, numpy.inf) – The minimum value.
 max_val (float, numpy.inf) – The maximum value.
 real_const (bool, false) – Constrain to real values (true) or complex values (false).

constraints
¶ An empy list of constrains objects.
Type: list of pyqmri.models.template.constrains

NScan
¶ Number of scans (dynamics).
Type: int

NSlice
¶ Number of slices.
Type: int

dimX, dimY
The image dimensions.
Type: int

figure
¶ The placeholder figure object
Type: matplotlib.pyplot.figure, None

update
(scale)¶ Update the constrains based on current scaling factor.
Parameters: scale (float) – The new scaling factor which should be used.
Module holding the variable flip angle model for T1 fitting.

class
pyqmri.models.VFA.
Model
(par)¶ Variable flip angle model for MRI parameter quantification.
This class holds a variable flip angle model for T1 quantification from complex MRI data. It realizes a forward application of the analytical signal expression and the partial derivatives with respesct to each parameter of interest, as required by the abstract methods in the BaseModel. The fitting target is the exponential term itself which is easier to fit than the corresponding timing constant.
The rescale function applies a transformation and returns the expected T1 values in ms.
Parameters: par (dict) – A python dict containing the necessary information to setup the object. Needs to contain the sequence related parametrs, e.g. TR, TE, TI, to fully describe the acquisitio process 
TR
¶ Repetition time of the gradient echo sequence.
Type: float

fa
¶ A vector containing all flip angles, one per scan.
Type: numpy.array

uk_scale
¶ Scaling factors for each unknown to balance the partial derivatives.
Type: list of float

guess
¶ The initial guess. Needs to be set using “computeInitialGuess” prior to fitting.
Type: numpy.array, None

computeInitialGuess
(*args)¶ Initialize unknown array for the fitting.
This function provides an initial guess for the fitting.
Parameters: args (list of objects) – Serves as universal interface. No objects need to be passed here.

rescale
(x)¶ Rescale the unknowns with the scaling factors.
Rescales each unknown with the corresponding scaling factor and applies a transformation for the time constants of the exponentials, yielding a resulting T1 in milliseconds.
Parameters: x (numpy.array) – The array of unknowns to be rescaled Returns: The rescaled unknowns Return type: numpy.array
