# sporco.dictlrn.cbpdndlmd¶

Dictionary learning based on CBPDN sparse coding with a spatial mask in the data fidelity term

Functions

`cbpdnmsk_class_label_lookup` (label) |
Get a ConvBPDNMask class from a label string. |

`ConvBPDNMaskOptionsDefaults` ([method]) |
Get defaults dict for the ConvBPDNMask class specified by the `method` parameter. |

`ConvBPDNMaskOptions` ([opt, method]) |
A wrapper function that dynamically defines a class derived from the Options class associated with one of the implementations of the Convolutional BPDN problem, and returns an object instantiated with the provided parameters. |

`ConvBPDNMask` (*args, **kwargs) |
A wrapper function that dynamically defines a class derived from one of the implementations of the Convolutional Constrained MOD problems, and returns an object instantiated with the provided parameters. |

`ccmodmsk_class_label_lookup` (label) |
Get a ConvCnstrMODMask class from a label string. |

`ConvCnstrMODMaskOptionsDefaults` ([method]) |
Get defaults dict for the ConvCnstrMODMask class specified by the `method` parameter. |

`ConvCnstrMODMaskOptions` ([opt, method]) |
A wrapper function that dynamically defines a class derived from the Options class associated with one of the implementations of the Convolutional Constrained MOD problem, and returns an object instantiated with the provided parameters. |

`ConvCnstrMODMask` (*args, **kwargs) |
A wrapper function that dynamically defines a class derived from one of the implementations of the Convolutional Constrained MOD problems, and returns an object instantiated with the provided parameters. |

Classes

`ConvBPDNMaskDictLearn` (D0, S, lmbda, W[, …]) |
Dictionary learning by alternating between sparse coding and dictionary update stages. |

## Function Descriptions¶

`sporco.dictlrn.cbpdndlmd.`

`cbpdnmsk_class_label_lookup`

(label)[source]¶Get a ConvBPDNMask class from a label string.

`sporco.dictlrn.cbpdndlmd.`

`ConvBPDNMaskOptionsDefaults`

(method='admm')[source]¶Get defaults dict for the ConvBPDNMask class specified by the

`method`

parameter.

`sporco.dictlrn.cbpdndlmd.`

`ConvBPDNMaskOptions`

(opt=None,method='admm')[source]¶A wrapper function that dynamically defines a class derived from the Options class associated with one of the implementations of the Convolutional BPDN problem, and returns an object instantiated with the provided parameters. The wrapper is designed to allow the appropriate object to be created by calling this function using the same syntax as would be used if it were a class. The specific implementation is selected by use of an additional keyword argument ‘method’. Valid values are as specified in the documentation for

`ConvBPDN`

.

`sporco.dictlrn.cbpdndlmd.`

`ConvBPDNMask`

(*args,**kwargs)[source]¶A wrapper function that dynamically defines a class derived from one of the implementations of the Convolutional Constrained MOD problems, and returns an object instantiated with the provided parameters. The wrapper is designed to allow the appropriate object to be created by calling this function using the same syntax as would be used if it were a class. The specific implementation is selected by use of an additional keyword argument ‘method’. Valid values are:

`'admm'`

: Use the implementation defined in`admm.cbpdn.ConvBPDNMaskDcpl`

.`'fista'`

: Use the implementation defined in`fista.cbpdn.ConvBPDNMask`

.The default value is

`'admm'`

.

`sporco.dictlrn.cbpdndlmd.`

`ccmodmsk_class_label_lookup`

(label)[source]¶Get a ConvCnstrMODMask class from a label string.

`sporco.dictlrn.cbpdndlmd.`

`ConvCnstrMODMaskOptionsDefaults`

(method='fista')[source]¶Get defaults dict for the ConvCnstrMODMask class specified by the

`method`

parameter.

`sporco.dictlrn.cbpdndlmd.`

`ConvCnstrMODMaskOptions`

(opt=None,method='fista')[source]¶A wrapper function that dynamically defines a class derived from the Options class associated with one of the implementations of the Convolutional Constrained MOD problem, and returns an object instantiated with the provided parameters. The wrapper is designed to allow the appropriate object to be created by calling this function using the same syntax as would be used if it were a class. The specific implementation is selected by use of an additional keyword argument ‘method’. Valid values are as specified in the documentation for

`ConvCnstrMODMask`

.

`sporco.dictlrn.cbpdndlmd.`

`ConvCnstrMODMask`

(*args,**kwargs)[source]¶A wrapper function that dynamically defines a class derived from one of the implementations of the Convolutional Constrained MOD problems, and returns an object instantiated with the provided parameters. The wrapper is designed to allow the appropriate object to be created by calling this function using the same syntax as would be used if it were a class. The specific implementation is selected by use of an additional keyword argument ‘method’. Valid values are:

`'ism'`

: Use the implementation defined in`ConvCnstrMODMaskDcpl_IterSM`

. This method works well for a small number of training images, but is very slow for larger training sets.`'cg'`

: Use the implementation defined in`ConvCnstrMODMaskDcpl_CG`

. This method is slower than`'ism'`

for small training sets, but has better run time scaling as the training set grows.`'cns'`

: Use the implementation defined in`ConvCnstrMODMaskDcpl_Consensus`

. This method is a good choice for large training sets.`'fista'`

: Use the implementation defined in`fista.ccmod.ConvCnstrMODMask`

. This method is the best choice for large training sets.The default value is

`'fista'`

.

## Class Descriptions¶

class`sporco.dictlrn.cbpdndlmd.`

`ConvBPDNMaskDictLearn`

(D0,S,lmbda,W,opt=None,xmethod=None,dmethod=None,dimK=1,dimN=2)[source]¶Bases:

`sporco.dictlrn.dictlrn.DictLearn`

Dictionary learning by alternating between sparse coding and dictionary update stages.

The sparse coding is performed using

`admm.cbpdn.ConvBPDNMaskDcpl`

(see [19]) or`fista.cbpdn.ConvBPDNMask`

(see [9] and [32]), and the dictionary update is computed using`fista.ccmod.ConvCnstrMODMask`

(see [17]) or one of the solver classes in`admm.ccmodmd`

(see [32] and [17]). The coupling between sparse coding and dictionary update stages is as in [16].Solve the optimisation problem

\[\mathrm{argmin}_{\mathbf{d}, \mathbf{x}} \; (1/2) \sum_k \left \| W (\sum_m \mathbf{d}_m * \mathbf{x}_{k,m} - \mathbf{s}_k ) \right \|_2^2 + \lambda \sum_k \sum_m \| \mathbf{x}_{k,m} \|_1 \quad \text{such that} \quad \mathbf{d}_m \in C \;\; \forall m \;,\]where \(C\) is the feasible set consisting of filters with unit norm and constrained support, via interleaved alternation between the ADMM steps of the

`ConvBPDNMaskDcpl`

and`ConvCnstrMODMaskDcpl`

problems. The multi-channel variants [30] supported by`ConvBPDNMaskDcpl`

and`ConvCnstrMODMaskDcpl`

are also supported.After termination of the

`solve`

method, attribute`itstat`

is a list of tuples representing statistics of each iteration. The fields of the named tuple`IterationStats`

are:

`Iter`

: Iteration number

`ObjFun`

: Objective function value

`DFid`

: Value of data fidelity term \((1/2) \sum_k \| W (\sum_m \mathbf{d}_m * \mathbf{x}_{k,m} - \mathbf{s}_k) \|_2^2\)

`RegL1`

: Value of regularisation term \(\sum_k \sum_m \| \mathbf{x}_{k,m} \|_1\)

`Cnstr`

: Constraint violation measure

If the ADMM solver is selected for sparse coding:

`XPrRsdl`

: Norm of X primal residual

`XDlRsdl`

: Norm of X dual residual

`XRho`

: X penalty parameter

If the FISTA solver is selected for sparse coding:

`X_F_Btrack`

: Value of objective function for CSC problem

`X_Q_Btrack`

: Value of quadratic approximation for CSC problem

`X_ItBt`

: Number of iterations in backtracking for CSC problem

`X_L`

: Inverse of gradient step parameter for CSC problem

If an ADMM solver is selected for the dictionary update:

`DPrRsdl`

: Norm of D primal residual

`DDlRsdl`

: Norm of D dual residual

`DRho`

: D penalty parameter

If the FISTA solver is selected for the dictionary update:

`D_F_Btrack`

: Value of objective function for CDU problem

`D_Q_Btrack`

: Value of wuadratic approximation for CDU problem

`D_ItBt`

: Number of iterations in backtracking for CDU problem

`D_L`

: Inverse of gradient step parameter for CDU problem

`Time`

: Cumulative run time

Call graph

Parameters:

D0: array_likeInitial dictionary array

S: array_likeSignal array

lmbda: floatRegularisation parameter

W: array_likeMask array. The array shape must be such that the array is compatible for multiplication with the

internalshape of input array S (see`cnvrep.CDU_ConvRepIndexing`

for a discussion of the distinction betweenexternalandinternaldata layouts).opt:`ConvBPDNMaskDictLearn.Options`

objectAlgorithm options

xmethod: string, optional (default ‘admm’)String selecting sparse coding solver. Valid values are documented in function

`ConvBPDNMask`

.dmethod: string, optional (default ‘fista’)String selecting dictionary update solver. Valid values are documented in function

`ConvCnstrMODMask`

.dimK: int, optional (default 1)Number of signal dimensions. If there is only a single input signal (e.g. if S is a 2D array representing a single image) dimK must be set to 0.

dimN: int, optional (default 2)Number of spatial/temporal dimensions

class`Options`

(opt=None,xmethod=None,dmethod=None)[source]¶Bases:

`sporco.dictlrn.dictlrn.Options`

CBPDN dictionary learning algorithm options.

Options include all of those defined in

`dictlrn.DictLearn.Options`

, together with additional options:

`AccurateDFid`

: Flag determining whether data fidelity term is estimated from the value computed in the X update (`False`

) or is computed after every outer iteration over an X update and a D update (`True`

), which is slower but more accurate.

`DictSize`

: Dictionary size vector.

`CBPDN`

: An options class appropriate for the selected sparse coding solver class

`CCMOD`

: An options class appropriate for the selected dictionary update solver classValid values for parameters

`xmethod`

and`dmethod`

are documented in functions`ConvBPDNMask`

and`ConvCnstrMODMask`

respectively.

`getdict`

(crop=True)[source]¶Get final dictionary. If

`crop`

is`True`

, apply`cnvrep.bcrop`

to returned array.

`solve`

()¶

Call graph