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
-