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(*args, **kwargs)

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

Function Descriptions

sporco.dictlrn.cbpdndlmd.cbpdnmsk_class_label_lookup(label)

Get a ConvBPDNMask class from a label string.

sporco.dictlrn.cbpdndlmd.ConvBPDNMaskOptionsDefaults(method='admm')

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

sporco.dictlrn.cbpdndlmd.ConvBPDNMaskOptions(opt=None, method='admm')

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)

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.

• 'pgm' : Use the implementation defined in pgm.cbpdn.ConvBPDNMask.

The default value is 'admm'.

sporco.dictlrn.cbpdndlmd.ccmodmsk_class_label_lookup(label)

Get a ConvCnstrMODMask class from a label string.

sporco.dictlrn.cbpdndlmd.ConvCnstrMODMaskOptionsDefaults(method='pgm')

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

sporco.dictlrn.cbpdndlmd.ConvCnstrMODMaskOptions(opt=None, method='pgm')

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)

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.

• 'pgm' : Use the implementation defined in pgm.ccmod.ConvCnstrMODMask. This method is the best choice for large training sets.

The default value is 'pgm'.

Class Descriptions

class sporco.dictlrn.cbpdndlmd.ConvBPDNMaskDictLearn(*args, **kwargs)

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 [28]) or pgm.cbpdn.ConvBPDNMask (see [13] and [53]), and the dictionary update is computed using pgm.ccmod.ConvCnstrMODMask (see [26]) or one of the solver classes in admm.ccmodmd (see [53] and [26]). The coupling between sparse coding and dictionary update stages is as in [24].

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 [51] 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 PGM 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 PGM 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

D0array_like

Initial dictionary array

Sarray_like

Signal array

lmbdafloat

Regularisation parameter

Warray_like

Mask array. The array shape must be such that the array is compatible for multiplication with the internal shape of input array S (see cnvrep.CDU_ConvRepIndexing for a discussion of the distinction between external and internal data layouts) after reshaping to the shape determined by cnvrep.mskWshape.

optConvBPDNMaskDictLearn.Options object

Algorithm options

xmethodstring, optional (default ‘admm’)

String selecting sparse coding solver. Valid values are documented in function ConvBPDNMask.

dmethodstring, optional (default ‘pgm’)

String selecting dictionary update solver. Valid values are documented in function ConvCnstrMODMask.

dimKint, 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.

dimNint, optional (default 2)

Number of spatial/temporal dimensions

class Options(opt=None, xmethod=None, dmethod=None)

Bases: sporco.dictlrn.dictlrn.DictLearn.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 ConvBPDNMask and ConvCnstrMODMask respectively.

getdict(crop=True)

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

reconstruct(D=None, X=None)

Reconstruct representation.

evaluate()

Evaluate functional value of previous iteration.

solve()

Call graph