# magni.cs.indicators module¶

Module prodiving performance indicator determination functionality.

## Routine listings¶

calculate_coherence(Phi, Psi, norm=None)
Calculate the coherence of the Phi Psi matrix product.
calculate_mutual_coherence(Phi, Psi, norm=None)
Calculate the mutual coherence of Phi and Psi.
calculate_relative_energy(Phi, Psi, method=None)
Calculate the relative energy of Phi Psi matrix product atoms.

Notes

For examples of uses of the performance indicators, see the related papers on predicting/modelling reconstruction quality [1], [2].

References

 [1] P. S. Pedersen, J. Ostergaard, and T. Larsen, “Predicting Reconstruction Quality within Compressive Sensing for Atomic Force Microscopy,” 2015 IEEE Global Conference on Signal and Information Processing (GlobalSIP), Orlando, FL, 2015, pp. 418-422. doi: 10.1109/GlobalSIP.2015.7418229
 [2] P. S. Pedersen, J. Ostergaard, and T. Larsen, “Modelling Reconstruction Quality of Lissajous Undersampled Atomic Force Microscopy Images,” 2016 IEEE 13th International Symposium on Biomedical Imaging (ISBI), Prague, Czech Republic, 2016, pp. 245-248. doi: 10.1109/ISBI.2016.7493255
magni.cs.indicators.calculate_coherence(Phi, Psi, norm=None)[source]

Calculate the coherence of the Phi Psi matrix product.

In the context of Compressive Sensing, coherence usually refers to the maximum absolute correlation between two columns of the Phi Psi matrix product. This function allows the usage of a different normalised norm where the infinity-norm yields the usual case.

Parameters: Phi (magni.utils.matrices.Matrix or numpy.ndarray) – The measurement matrix. Psi (magni.utils.matrices.Matrix or numpy.ndarray) – The dictionary matrix. norm (int or float) – The normalised norm used for the calculation (the default value is None which implies that the 0-, 1-, 2-, and infinity-norms are returned). coherence (float or dict) – The coherence value(s).

Notes

If norm is None, the function returns a dict containing the coherence using the 0-, 1-, 2-, and infinity-norms. Otherwise, the function returns the coherence using the specified norm.

The coherence is calculated as:

$\begin{split}\left(\frac{1}{n^2 - n} \sum_{i = 1}^n \sum_{\substack{j = 1 \\ j \neq i}}^n \left( \frac{|\Psi_{:, i}^T \Phi^T \Phi \Psi_{:, j}|} {||\Phi \Psi_{:, i}||_2 ||\Phi \Psi_{:, j}||_2} \right)^{\text{norm}}\right)^{\frac{1}{\text{norm}}}\end{split}$

where n is the number of columns in Psi. In the case of the 0-norm, the coherence is calculated as:

$\begin{split}\frac{1}{n^2 - n} \sum_{i = 1}^n \sum_{\substack{j = 1 \\ j \neq i}}^n \mathbf{1} \left(\frac{|\Psi_{:, i}^T \Phi^T \Phi \Psi_{:, j}|} {||\Phi \Psi_{:, i}||_2 ||\Phi \Psi_{:, j}||_2}\right)\end{split}$

where $$\mathbf{1}(a)$$ is 1 if a is non-zero and 0 otherwise. In the case of the infinity-norm, the coherence is calculated as:

$\begin{split}\max_{\substack{i, j \in \{1, \dots, n\} \\ i \neq j}} \left(\frac{|\Psi_{:, i}^T \Phi^T \Phi \Psi_{:, j}|} {||\Phi \Psi_{:, i}||_2 ||\Phi \Psi_{:, j}||_2}\right)\end{split}$

Examples

For example,

>>> import numpy as np
>>> import magni
>>> from magni.cs.indicators import calculate_coherence
>>> Phi = np.zeros((5, 9))
>>> Phi[0, 0] = Phi[1, 2] = Phi[2, 4] = Phi[3, 6] = Phi[4, 8] = 1
>>> Psi = magni.imaging.dictionaries.get_DCT((3, 3))
>>> for item in sorted(calculate_coherence(Phi, Psi).items()):
...     print('{}-norm: {:.3f}'.format(*item))
0-norm: 0.222
1-norm: 0.141
2-norm: 0.335
inf-norm: 1.000


The above values can be calculated individually by specifying a norm:

>>> for norm in (0, 1, 2, np.inf):
...     value = calculate_coherence(Phi, Psi, norm=norm)
...     print('{}-norm: {:.3f}'.format(norm, value))
0-norm: 0.222
1-norm: 0.141
2-norm: 0.335
inf-norm: 1.000

magni.cs.indicators.calculate_mutual_coherence(Phi, Psi, norm=None)[source]

Calculate the mutual coherence of Phi and Psi.

In the context of Compressive Sensing, mutual coherence usually refers to the maximum absolute correlation between two columns of Phi and Psi. This function allows the usage of a different normalised norm where the infinity-norm yields the usual case.

Parameters: Phi (magni.utils.matrices.Matrix or numpy.ndarray) – The measurement matrix. Psi (magni.utils.matrices.Matrix or numpy.ndarray) – The dictionary matrix. norm (int or float) – The normalised norm used for the calculation (the default value is None which implies that the 0-, 1-, 2-, and infinity-norms are returned). mutual_coherence (float or dict) – The mutual_coherence value(s).

Notes

If norm is None, the function returns a dict containing the mutual coherence using the 0-, 1-, 2-, and infinity-norms. Otherwise, the function returns the mutual coherence using the specified norm.

The mutual coherence is calculated as:

$\left(\frac{1}{m n} \sum_{i = 1}^m \sum_{j = 1}^n |\Phi_{i, :} \Psi_{:, j}|^{\text{norm}}\right)^{\frac{1}{\text{norm}}}$

where m is the number of rows in Phi and n is the number of columns in Psi. In the case of the 0-norm, the mutual coherence is calculated as:

$\frac{1}{m n} \sum_{i = 1}^m \sum_{j = 1}^n \mathbf{1} (|\Phi_{i, :} \Psi_{:, j}|)$

where $$\mathbf{1}(a)$$ is 1 if a is non-zero and 0 otherwise. In the case of the infinity-norm, the mutual coherence is calculated as:

$\max_{i \in \{1, \dots, m\}, j \in \{1, \dots, n\}} |\Phi_{i, :} \Psi_{:, j}|$

Examples

For example,

>>> import numpy as np
>>> import magni
>>> from magni.cs.indicators import calculate_mutual_coherence
>>> Phi = np.zeros((5, 9))
>>> Phi[0, 0] = Phi[1, 2] = Phi[2, 4] = Phi[3, 6] = Phi[4, 8] = 1
>>> Psi = magni.imaging.dictionaries.get_DCT((3, 3))
>>> for item in sorted(calculate_mutual_coherence(Phi, Psi).items()):
...     print('{}-norm: {:.3f}'.format(*item))
0-norm: 0.889
1-norm: 0.298
2-norm: 0.333
inf-norm: 0.667


The above values can be calculated individually by specifying a norm:

>>> for norm in (0, 1, 2, np.inf):
...     value = calculate_mutual_coherence(Phi, Psi, norm=norm)
...     print('{}-norm: {:.3f}'.format(norm, value))
0-norm: 0.889
1-norm: 0.298
2-norm: 0.333
inf-norm: 0.667

magni.cs.indicators.calculate_relative_energy(Phi, Psi, method=None)[source]

Calculate the relative energy of Phi Psi matrix product atoms.

Parameters: Phi (magni.utils.matrices.Matrix or numpy.ndarray) – The measurement matrix. Psi (magni.utils.matrices.Matrix or numpy.ndarray) – The dictionary matrix. method (str) – The method used for summarising the relative energies of the Phi Psi matrix product atoms. relative_energy (float or dict) – The relative_energy summary value(s).

Notes

The summary method used is either ‘mean’ for mean value, ‘std’ for standard deviation, ‘min’ for minimum value, or ‘diff’ for difference between the maximum and minimum values.

If method is None, the function returns a dict containing all of the above summaries. Otherwise, the function returns the specified summary.

The relative energies, which are summarised by the given method, are calculated as:

$\left[ \frac{||\Phi \Psi_{:, 1}||_2}{||\Psi_{:, 1}||_2}, \dots, \frac{||\Phi \Psi_{:, n}||_2}{||\Psi_{:, n}||_2} \right]^T$

where n is the number of columns in Psi.

Examples

For example,

>>> import numpy as np
>>> import magni
>>> from magni.cs.indicators import calculate_relative_energy
>>> Phi = np.zeros((5, 9))
>>> Phi[0, 0] = Phi[1, 2] = Phi[2, 4] = Phi[3, 6] = Phi[4, 8] = 1
>>> Psi = magni.imaging.dictionaries.get_DCT((3, 3))
>>> for item in sorted(calculate_relative_energy(Phi, Psi).items()):
...     print('{}: {:.3f}'.format(*item))
diff: 0.423
mean: 0.735
min: 0.577
std: 0.126


The above values can be calculated individually by specifying a norm:

>>> for method in ('mean', 'std', 'min', 'diff'):
...     value = calculate_relative_energy(Phi, Psi, method=method)
...     print('{}: {:.3f}'.format(method, value))
mean: 0.735
std: 0.126
min: 0.577
diff: 0.423