pystem.restore.DL_ITKrMM module

This module implements the ITKrMM algorithm.

The ITKrMM algorithm

pystem.restore.DL_ITKrMM.ITKrMM(Y, mask=None, PatchSize=5, K=128, L=1, S=20, Nit_lr=10, Nit=40, CLS_init=None, xref=None, verbose=True, PCA_transform=True, PCA_th='auto')

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.

  • PatchSize (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.

  • 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.

pystem.restore.DL_ITKrMM.ITKrMM_matlab(Y, mask, PatchSize=5, K=128, L=1, S=20, Nit_lr=10, Nit=40, CLS_init=None, xref=None, verbose=True, PCA_transform=True, PCA_th='auto')

ITKrMM restoration algorithm with matlab code.

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.

  • PatchSize (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.

  • 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

pystem.restore.DL_ITKrMM.wKSVD_matlab(Y, mask, PatchSize=5, K=128, L=1, S=20, Nit_lr=10, Nit=40, CLS_init=None, xref=None, verbose=True, PCA_transform=True, PCA_th='auto')

wKSVD restoration algorithm with Matlab code.

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.

  • PatchSize (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.

  • 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

pystem.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

pystem.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

pystem.restore.DL_ITKrMM.CLS_init(Y, Lambda, K=128, S=None, PatchSize=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*PatchSize*l.

  • PatchSize (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*PatchSize**2) numpy array – The dictionary for dictionary learning algorithm.

  • (K, l*PatchSize**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 pystem.restore.DL_ITKrMM.Dico_Learning_Executer(Y, mask=None, PatchSize=5, K=128, L=1, S=20, Nit_lr=10, Nit=40, CLS_init=None, xref=None, verbose=True, PCA_transform=True, PCA_th='auto')

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,

  • launches 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.

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

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

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

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

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

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

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

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

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

  • data ((PatchSize**2, N) or (PatchSize**2*l, N) numpy array) – The Y data in patch format. N is the number of patches.

  • mdata ((PatchSize**2, N) or (PatchSize**2*l, N) numpy array) – The mask in patch format. N is the number of patches.

  • init ((PatchSize**2, K+L) or (PatchSize**2*l, K+L) numpy array) – The initialization in patch format.

  • PCA_operator (PcaHandler object) – The PCA operator.

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

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 other optional arguments required for CLS (PCA_transform, PCA_th, init).

The ITKrMM core

pystem.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

pystem.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

pystem.restore.DL_ITKrMM.itkrmm_core(data, masks=None, K=None, S=1, lrc=None, Nit=50, init=None, verbose=True, xref=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.

  • xref (optional, None or (d, N) numpy array) – True data or reference data to check convergence. Default is data.

Returns

  • (d, K) numpy array – Estimated dictionary

  • float – Execution time in seconds.

(Nit, ) numpy array

Evolution of NMSE between current data and xref.