inpystem.restore.DL_ITKrMM module

This module implements the ITKrMM algorithm.

The ITKrMM algorithm

inpystem.restore.DL_ITKrMM.ITKrMM(Y, mask=None, P=5, K=None, L=1, S=None, Nit_lr=10, Nit=40, init_lr=None, init=None, CLS_init=None, PCA_transform=True, PCA_th='auto', verbose=True)

ITKrMM restoration algorithm.

Parameters

  • Y ((m, n) or (m, n, l) numpy array) – The input data.

  • mask (optional, None or (m, n) numpy array) – The acquisition mask. Default is None for full sampling.

  • P (optional, int) – The width (or height) of the patch. Default is 5.

  • K (optional, int) – The dictionary dimension. Default is 128.

  • L (optional, int) – The number of low rank components to learn. Default is 1.

  • S (optional, int) – The code sparsity level. Default is 20.

  • Nit_lr (optional, int) – The number of iterations for the low rank estimation. Default is 10.

  • Nit (optional, int) – The number of iterations. Default is 40.

  • init ((P**2, K+L) or (P**2*l, K+L) numpy array) – Initialization dictionary.

  • CLS_init (optional, dico) – CLS initialization inofrmation. See Notes for details. Default is None.

  • xref (optional, (m, n) or (m, n, l) numpy array) – Reference image to compute error evolution. Default is None for input Y data.

  • verbose (optional, bool) – The verbose parameter. Default is True.

  • PCA_transform (optional, bool) – Enables the PCA transformation if True, otherwise, no PCA transformation is processed. Default is True.

  • PCA_th (optional, int, str) – The desired data dimension after dimension reduction. Possible values are ‘auto’ for automatic choice, ‘max’ for maximum value and an int value for user value. Default is ‘auto’.

Returns

  • (m, n) or (m, n, l) numpy array – Restored data.

  • dict – Aditional informations. See Notes.

Notes

The algorithm can be initialized with CLS as soon as CLS_init is not None. In this case, CLS_init should be a dictionary containing the required Lambda key and eventually the init optional argument.

The output information keys are:

  • time: Execution time in seconds.

  • lrc: low rank component.

  • dico: Estimated dictionary.

  • E: Evolution of the error.

The wKSVD algorithm

inpystem.restore.DL_ITKrMM.wKSVD(Y, mask=None, P=5, K=None, L=1, S=None, Nit_lr=10, Nit=40, init_lr=None, init=None, CLS_init=None, PCA_transform=True, PCA_th='auto', verbose=True)

wKSVD restoration algorithm.

Parameters

  • Y ((m, n) or (m, n, l) numpy array) – The input data.

  • mask (optional, None or (m, n) numpy array) – The acquisition mask. Default is None for full sampling.

  • P (optional, int) – The width (or height) of the patch. Default is 5.

  • K (optional, int) – The dictionary dimension. Default is 128.

  • L (optional, int) – The number of low rank components to learn. Default is 1.

  • S (optional, int) – The code sparsity level. Default is 20.

  • Nit_lr (optional, int) – The number of iterations for the low rank estimation. Default is 10.

  • Nit (optional, int) – The number of iterations. Default is 40.

  • init ((P**2, K+L) or (P**2*l, K+L) numpy array) – Initialization dictionary.

  • CLS_init (optional, dico) – CLS initialization inofrmation. See Notes for details. Default is None.

  • xref (optional, (m, n) or (m, n, l) numpy array) – Reference image to compute error evolution. Default is None for input Y data.

  • verbose (optional, bool) – The verbose parameter. Default is True.

  • PCA_transform (optional, bool) – Enables the PCA transformation if True, otherwise, no PCA transformation is processed. Default is True.

  • PCA_th (optional, int, str) – The desired data dimension after dimension reduction. Possible values are ‘auto’ for automatic choice, ‘max’ for maximum value and an int value for user value. Default is ‘auto’.

Returns

  • (m, n) or (m, n, l) numpy array – Restored data.

  • dict – Aditional informations. See Notes.

Notes

The algorithm can be initialized with CLS as soon as CLS_init is not None. In this case, CLS_init should be a dictionary containing the required Lambda key and eventually the init optional argument.

The output information keys are:

  • time: Execution time in seconds.

  • lrc: low rank component.

  • dico: Estimated dictionary.

  • E: Evolution of the error.

Patch manipulation functions

inpystem.restore.DL_ITKrMM.forward_patch_transform(ref, w)

Transforms data from 2D/3D array to array whose shape is (w**2, N) where w is the patch width and N is the number of patches.

Parameters

  • ref ((m, n) or (m, n, l) numpy array) – The input image.

  • w (int) – The width (or height) of the patch.

Returns

data – The patches stacked version. Its shape is (w**2, N) where N is the number of patches if ref is 2D or (w**2*l, N) is ref is 3D.

Return type

(w**2, N) or (w**2*l, N) numpy array

inpystem.restore.DL_ITKrMM.inverse_patch_transform(data, shape)

Transforms data from array of the form (w**2, N) or (w**2*l, N) where w is the patch width, l is the number of bands (in the case of 3D data) and N is the number of patches into 2D/3D array.

Parameters

  • data ((w**2, N) or (w**2*l, N) numpy array) – The input data.

  • shape ((m, n) or (m, n, l)) – The image shape.

Returns

ref – The input image.

Return type

(m, n) or (m, n, l) numpy array

CLS initialization function

inpystem.restore.DL_ITKrMM.CLS_init(Y, Lambda, K=128, S=None, P=5, mask=None, PCA_transform=False, PCA_th='auto', init=None, verbose=True)

Dictionary learning initialization based on CLS restoration algorithm.

Parameters

  • Y ((m, n, l)n umpy array) – A 3D multi-band image.

  • Lambda (float) – Regularization parameter.

  • K (optional, int) – The dictionary size. Default is 128.

  • S (optional, int) – The code sparsity. Default is 0.1*P*l.

  • P (optional, int) – The patch size. Default is 5.

  • mask (optional, None, (m, n) boolean numpy array) – A sampling mask which is True if the pixel is sampled and False otherwise. Default is None for full sampling.

  • PCA_transform (optional, bool) – Enables the PCA transformation if True, otherwise, no PCA transformation is processed. Default is False as it should be done in dico learning operator.

  • PCA_th (optional, int, str) – The desired data dimension after dimension reduction. Possible values are ‘auto’ for automatic choice, ‘max’ for maximum value and an int value for user value. Default is ‘auto’.

  • init (optional, None, (m, n, l) numpy array) – The algorithm initialization. Default is None for random initialization.

  • verbose (optional, bool) – Indicates if information text is desired. Default is True.

Returns

  • (K, l*P**2) numpy array – The dictionary for dictionary learning algorithm.

  • (K, l*P**2) numpy array – The sparse code for dictionary learning algorithm.

  • (m, n, l) numpy array – CLS restored array.

  • dict – Dictionary containing some extra info

Note

Infos in output dictionary:

  • E : In the case of partial reconstruction, the cost function evolution over iterations.

  • Gamma : The array of kept coefficients (order is Fortran-style)

  • nnz_ratio : the ratio Gamma.size/(m*n)

  • H: the basis of the chosen signal subspace

The dictionary learning interface

class inpystem.restore.DL_ITKrMM.Dico_Learning_Executer(Y, mask=None, P=5, K=None, L=1, S=None, Nit_lr=10, Nit=40, init_lr=None, init=None, CLS_init=None, PCA_transform=True, PCA_th='auto', verbose=True)

Class to define execute dictionary learning algorithms.

The following class is a common code for most dictionary learning methods. It performs the following tasks:

  • reshapes the data in patch format,

  • performs low-rank component estimation,

  • starts the dictionary learning method,

  • reshape output data,

  • handle CLS initialization to speed-up computation.

Variables

  • Y ((m, n) or (m, n, l) numpy array) – The input data.

  • Y_PCA ((m, n) or (m, n, PCA_th) numpy array) – The input data in PCA space. Its value is Y if Y is 2D.

  • mask ((m, n) numpy array) – The acquisition mask.

  • P (int) – The width (or height) of the patch.

  • K (int) – The dictionary dimension. This dictionary is composed of L low-rank components and K-L non-low-rank components.

  • L (int) – The number of low rank components to learn.

  • S (int) – The code sparsity level.

  • Nit_lr (int) – The number of iterations for the low rank estimation.

  • Nit (int) – The number of iterations.

  • CLS_init (dico) – CLS initialization inofrmation.

  • verbose (bool) – The verbose parameter. Default is True.

  • mean_std (2-tuple) – Tuple of size 2 which contains the data mean and std.

  • data ((N, D) numpy array) – The Y data in patch format. N (resp. D) is the number of voxels per patch (resp. patches).

  • mdata ((N, D) numpy array) – The mask in patch format. N (resp. D) is the number of voxels per patch (resp. patches).

  • init ((N, K-L) numpy array) – The low-rank estimation initialization in patch format. N is the number of voxels per patch.

  • init – The dictionary-learning initialization in patch format. N is the number of voxels per patch.

  • PCA_operator (PcaHandler object) – The PCA operator.

Note

The algorithm can be initialized with CLS as soon as CLS_init is not None. In this case, CLS_init should be a dictionary containing the required Lambda key and eventually the CLS init optional argument.

The ITKrMM core

inpystem.restore.DL_ITKrMM.rec_lratom(data, masks=None, lrc=None, Nit=10, inatom=None, verbose=True)

Recover new low rank atom equivalent to itkrmm with K = S = 1.

Parameters

  • data ((d, N) numpy array) – The (corrupted) training signals as its columns.

  • masks ((d, N) numpy array) – Mask data as its columns. masks(.,.) in {0,1}. Default is masks = 1.

  • lrc ((d, n) numpy array) – Orthobasis for already recovered low rank component. Default is None.

  • Nit (int) – Number of iterations. Default is 10.

  • inatom ((d, ) numpy array) – Initialisation that should be normalized. Default is None for random.

  • verbose (bool) – If verbose is True, information is sent to the output. Default is True.

Returns

atom – Estimated low rank component.

Return type

(d, ) numpy array

inpystem.restore.DL_ITKrMM.OMPm(D, X, S, Masks=None)

Masked OMP.

This is a modified version of OMP to account for corruptions in the signal.

Consider some input data \(\mathbf{X}\) (whose shape is (N, P) where N is the number of signals) which are masked by \(\mathbf{M}\). Given an input dictionary \(\mathbf{D}\) of shape (K, P), this algorithm returns the optimal sparse \(\hat{\mathbf{A}}\) matrix such that:

\[\gdef \A {\mathbf{A}} \gdef \M {\mathbf{M}} \gdef \X {\mathbf{X}} \gdef \D {\mathbf{D}} \begin{aligned} \hat{\A} &= \arg\min_\A \frac{1}{2}||\M\X - \M(\A\D)||_F^2\\ &s.t. \max_k||\A_{k,:}||_{0} \leq S \end{aligned}\]

A slightly different modification of Masked OMP is available in “Sparse and Redundant Representations: From Theory to Applications in Signal and Image Processing,” the book written by M. Elad in 2010.

Parameters

  • D ((K, P) numpy array) – The dictionary. Its rows MUST be normalized, i.e. their norm must be 1.

  • X ((N, P) numpy array) – The masked signals to represent.

  • S (int) – The max. number of coefficients for each signal.

  • Masks (optional, (N, P) numpy array or None) – The sampling masks that should be 1 if sampled and 0 otherwise. Default is None for full sampling.

Returns

sparse coefficient matrix.

Return type

(N, K) sparse coo_matrix array

inpystem.restore.DL_ITKrMM.itkrmm_core(data, masks=None, K=None, S=1, lrc=None, Nit=50, init=None, verbose=True, parent=None)

Iterative Thresholding and K residual Means masked.

Parameters

  • data ((d, N) numpy array) – The (corrupted) training signals as its columns.

  • masks (optional, None, (d, N) numpy array) – The masks as its columns. masks(.,.) in {0,1}. Default is None for full sampling.

  • K (optional, None or int) – Dictionary size. Default is None for d.

  • S (optional, int) – Desired or estimated sparsity level of the signals. Default is 1.

  • lrc (optional, None or (d, L) numpy array) – Orthobasis for low rank component. Default is None.

  • Nit (optional, int) – Number of iterations. Default is 50.

  • init (optional, None or (d, K-L) numpy array) – Initialisation, unit norm column matrix. Here, L is the number of low rank components. Default is None for random.

  • verbose (optional, optional, bool) – The verbose parameter. Default is True.

  • parent (optional, None or Dico_Learning_Executer object) – The Dico_Learning_Executer object that called this function. If this is not None, the SNR between initial true data (given throught the `xref`argument of Dico_Learning_Executer) and the currently reconstructed data will be computed for each iteration. As this means one more OMPm per iteration, this is quite longer. Default is None for faster code and non-SNR output.

Returns

  • (d, K) numpy array – Estimated dictionary

  • dictionary – Output information. See Note.

Note

The output dictionary contains the following keys.

  • time (float): Execution time in seconds.

  • ‘SNR’ (None, (Nit, ) array): Evolution of the SNR across the iterations in case `parent`is not None.