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 bi-exponential model for fitting.

class pyqmri.models.BiExpDecay.Model(par)

Bi-exponential model for MRI parameter quantification.

This class holds a bi-exponential 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 bi-exponential 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(**kwargs)

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(**kwargs)

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(**kwargs)

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(**kwargs)

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 Look-Locker quantification model.

class pyqmri.models.IRLL.Model(par)

Inversion recovery Look-Locker 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 read-out 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(**kwargs)

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(**kwargs)

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
setInitalGuess(**kwargs)
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(**kwargs)

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