# sporco.dictlrn.cbpdndl¶

Dictionary learning based on CBPDN sparse coding

Functions

 cbpdn_class_label_lookup(label) Get a CBPDN class from a label string. ConvBPDNOptionsDefaults([method]) Get defaults dict for the ConvBPDN class specified by the method parameter. ConvBPDNOptions([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. ConvBPDN(*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. ccmod_class_label_lookup(label) Get a CCMOD class from a label string. ConvCnstrMODOptionsDefaults([method]) Get defaults dict for the ConvCnstrMOD class specified by the method parameter. ConvCnstrMODOptions([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. ConvCnstrMOD(*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

 ConvBPDNDictLearn(D0, S[, lmbda, opt, …]) Dictionary learning by alternating between sparse coding and dictionary update stages.

## Function Descriptions¶

sporco.dictlrn.cbpdndl.cbpdn_class_label_lookup(label)[source]

Get a CBPDN class from a label string.

sporco.dictlrn.cbpdndl.ConvBPDNOptionsDefaults(method='admm')[source]

Get defaults dict for the ConvBPDN class specified by the method parameter.

sporco.dictlrn.cbpdndl.ConvBPDNOptions(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.cbpdndl.ConvBPDN(*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:

The default value is 'admm'.

sporco.dictlrn.cbpdndl.ccmod_class_label_lookup(label)[source]

Get a CCMOD class from a label string.

sporco.dictlrn.cbpdndl.ConvCnstrMODOptionsDefaults(method='fista')[source]

Get defaults dict for the ConvCnstrMOD class specified by the method parameter.

sporco.dictlrn.cbpdndl.ConvCnstrMODOptions(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 ConvCnstrMOD.

sporco.dictlrn.cbpdndl.ConvCnstrMOD(*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 ConvCnstrMOD_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 ConvCnstrMOD_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 ConvCnstrMOD_Consensus. This method is a good choice for large training sets.
• 'fista' : Use the implementation defined in fista.ccmod.ConvCnstrMOD. This method is the best choice for large training sets.

The default value is 'fista'.

## Class Descriptions¶

class sporco.dictlrn.cbpdndl.ConvBPDNDictLearn(D0, S, lmbda=None, opt=None, xmethod=None, dmethod=None, dimK=1, dimN=2)[source]

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

The sparse coding is performed using admm.cbpdn.ConvBPDN (see [29]) or fista.cbpdn.ConvBPDN (see [9] and [33]), and the dictionary update is computed using fista.ccmod.ConvCnstrMOD (see [18]) or one of the solver classes in admm.ccmod (see [33] and [1]). The coupling between sparse coding and dictionary update stages is as in [17].

Solve the optimisation problem

$\mathrm{argmin}_{\mathbf{d}, \mathbf{x}} \; (1/2) \sum_k \left \| \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 admm.cbpdn.ConvBPDN and ConvCnstrMOD problems. Multi-channel variants [31] 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 \| \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_like Initial dictionary array S : array_like Signal array lmbda : float Regularisation parameter opt : Algorithm options xmethod : string, optional (default ‘admm’) String selecting sparse coding solver. Valid values are documented in function ConvBPDN. dmethod : string, optional (default ‘fista’) String selecting dictionary update solver. Valid values are documented in function ConvCnstrMOD. 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 class

Valid values for parameters xmethod and dmethod are documented in functions ConvBPDN and ConvCnstrMOD respectively.

getdict(crop=True)[source]

Get final dictionary. If crop is True, apply cnvrep.bcrop to returned array.

reconstruct(D=None, X=None)[source]

Reconstruct representation.

evaluate()[source]

Evaluate functional value of previous iteration.

solve()

Call graph