# sporco.cnvrep¶

Classes and functions that support working with convolutional representations

Functions

 stdformD(D, Cd, M[, dimN]) Reshape dictionary array (D in admm.cbpdn module, X in admm.ccmod module) to internal standard form. l1Wshape(W, cri) Get appropriate internal shape (see CSC_ConvRepIndexing) for an $$\ell_1$$ norm weight array W, as in option L1Weight in admm.cbpdn.ConvBPDN.Options and related options classes. mskWshape(W, cri) Get appropriate internal shape (see CSC_ConvRepIndexing and CDU_ConvRepIndexing) for data fidelity term mask array W. zeromean(v, dsz[, dimN]) Subtract mean value from each filter in the input array v. normalise(v[, dimN]) Normalise vectors, corresponding to slices along specified number of initial spatial dimensions of an array, to have unit $$\ell_2$$ norm. zpad(v, Nv) Zero-pad initial axes of array to specified size. bcrop(v, dsz[, dimN]) Crop specified number of initial spatial dimensions of dictionary array to specified size. Pcn(x, dsz, Nv[, dimN, dimC, crp, zm]) Constraint set projection for convolutional dictionary update problem. getPcn(dsz, Nv[, dimN, dimC, crp, zm]) Construct the constraint set projection function for convolutional dictionary update problem. _Pcn(x, dsz, Nv[, dimN, dimC]) Projection onto dictionary update constraint set: support projection and normalisation. _Pcn_zm(x, dsz, Nv[, dimN, dimC]) Projection onto dictionary update constraint set: support projection, mean subtraction, and normalisation. _Pcn_crp(x, dsz, Nv[, dimN, dimC]) Projection onto dictionary update constraint set: support projection and normalisation. _Pcn_zm_crp(x, dsz, Nv[, dimN, dimC]) Projection onto dictionary update constraint set: support projection, mean subtraction, and normalisation.

Classes

 CSC_ConvRepIndexing(D, S[, dimK, dimN]) Manage the inference of problem dimensions and the roles of numpy.ndarray indices for convolutional representations in convolutional sparse coding problems (e.g. DictionarySize(dsz[, dimN]) Compute dictionary size parameters from a dictionary size specification tuple as in the dsz argument of bcrop. CDU_ConvRepIndexing(dsz, S[, dimK, dimN]) Manage the inference of problem dimensions and the roles of numpy.ndarray indices for convolutional representations in convolutional dictionary update problems (e.g.

## Function Descriptions¶

sporco.cnvrep.stdformD(D, Cd, M, dimN=2)[source]

Reshape dictionary array (D in admm.cbpdn module, X in admm.ccmod module) to internal standard form.

Parameters: D : array_like Dictionary array Cd : int Size of dictionary channel index M : int Number of filters in dictionary dimN : int, optional (default 2) Number of problem spatial indices Dr : ndarray Reshaped dictionary array
sporco.cnvrep.l1Wshape(W, cri)[source]

Get appropriate internal shape (see CSC_ConvRepIndexing) for an $$\ell_1$$ norm weight array W, as in option L1Weight in admm.cbpdn.ConvBPDN.Options and related options classes. The external shape of W depends on the external shape of input data array S and the size of the final axis (i.e. the number of filters) in dictionary array D. The internal shape of the weight array W is required to be compatible for multiplication with the internal sparse representation array X. The simplest criterion for ensuring that the external W is compatible with S is to ensure that W has shape S.shape + D.shape[-1:], except that non-singleton dimensions may be replaced with singleton dimensions. If W has a single additional axis that is neither a spatial axis nor a filter axis, it is assigned as a channel or multi-signal axis depending on the corresponding assignement in S.

Parameters: W : array_like Weight array cri : Object specifying convolutional representation dimensions shp : tuple Appropriate internal weight array shape
sporco.cnvrep.mskWshape(W, cri)[source]

Get appropriate internal shape (see CSC_ConvRepIndexing and CDU_ConvRepIndexing) for data fidelity term mask array W. The external shape of W depends on the external shape of input data array S. The simplest criterion for ensuring that the external W is compatible with S is to ensure that W has the same shape as S, except that non-singleton dimensions in S may be singleton dimensions in W. If W has a single non-spatial axis, it is assigned as a channel or multi-signal axis depending on the corresponding assignement in S.

Parameters: W : array_like Data fidelity term weight/mask array cri : CSC_ConvRepIndexing object or CDU_ConvRepIndexing object Object specifying convolutional representation dimensions shp : tuple Appropriate internal mask array shape
sporco.cnvrep.zeromean(v, dsz, dimN=2)[source]

Subtract mean value from each filter in the input array v. The dsz parameter specifies the support sizes of each filter using the same format as the dsz parameter of bcrop. Support sizes must be taken into account to ensure that the mean values are computed over the correct number of samples, ignoring the zero-padded region in which the filter is embedded.

Parameters: v : array_like Input dictionary array dsz : tuple Filter support size(s) dimN : int, optional (default 2) Number of spatial dimensions vz : ndarray Dictionary array with filter means subtracted
sporco.cnvrep.normalise(v, dimN=2)[source]

Normalise vectors, corresponding to slices along specified number of initial spatial dimensions of an array, to have unit $$\ell_2$$ norm. The remaining axes enumerate the distinct vectors to be normalised.

Parameters: v : array_like Array with components to be normalised dimN : int, optional (default 2) Number of initial dimensions over which norm should be computed vnrm : ndarray Normalised array
sporco.cnvrep.zpad(v, Nv)[source]

Zero-pad initial axes of array to specified size. Padding is applied to the right, top, etc. of the array indices.

Parameters: v : array_like Array to be padded Nv : tuple Sizes to which each of initial indices should be padded vp : ndarray Padded array
sporco.cnvrep.bcrop(v, dsz, dimN=2)[source]

Crop specified number of initial spatial dimensions of dictionary array to specified size. Parameter dsz must be a tuple having one of the following forms (the examples assume two spatial/temporal dimensions). If all filters are of the same size, then

(flt_rows, filt_cols, num_filt)


may be used when the dictionary has a single channel, and

(flt_rows, filt_cols, num_chan, num_filt)


should be used for a multi-channel dictionary. If the filters are not all of the same size, then

(
(flt_rows1, filt_cols1, num_filt1),
(flt_rows2, filt_cols2, num_filt2),
...
)


may be used for a single-channel dictionary. A multi-channel dictionary may be specified in the form

(
(flt_rows1, filt_cols1, num_chan, num_filt1),
(flt_rows2, filt_cols2, num_chan, num_filt2),
...
)


or

(
(
(flt_rows11, filt_cols11, num_chan11, num_filt1),
(flt_rows21, filt_cols21, num_chan21, num_filt1),
...
)
(
(flt_rows12, filt_cols12, num_chan12, num_filt2),
(flt_rows22, filt_cols22, num_chan22, num_filt2),
...
)
...
)


depending on whether the filters for each channel are of the same size or not. The total number of dictionary filters, is either num_filt in the first two forms, or the sum of num_filt1, num_filt2, etc. in the other form. If the filters are not two-dimensional, then the dimensions above vary accordingly, i.e., there may be fewer or more filter spatial dimensions than flt_rows, filt_cols, e.g.

(flt_rows, num_filt)


for one-dimensional signals, or

(flt_rows, filt_cols, filt_planes, num_filt)


for three-dimensional signals.

Parameters: v : array_like Dictionary array to be cropped dsz : tuple Filter support size(s) dimN : int, optional (default 2) Number of spatial dimensions vc : ndarray Cropped dictionary array
sporco.cnvrep.Pcn(x, dsz, Nv, dimN=2, dimC=1, crp=False, zm=False)[source]

Constraint set projection for convolutional dictionary update problem.

Parameters: x : array_like Input array dsz : tuple Filter support size(s), specified using the same format as the dsz parameter of bcrop Nv : tuple Sizes of problem spatial indices dimN : int, optional (default 2) Number of problem spatial indices dimC : int, optional (default 1) Number of problem channel indices crp : bool, optional (default False) Flag indicating whether the result should be cropped to the support of the largest filter in the dictionary. zm : bool, optional (default False) Flag indicating whether the projection function should include filter mean subtraction y : ndarray Projection of input onto constraint set
sporco.cnvrep.getPcn(dsz, Nv, dimN=2, dimC=1, crp=False, zm=False)[source]

Construct the constraint set projection function for convolutional dictionary update problem.

Parameters: dsz : tuple Filter support size(s), specified using the same format as the dsz parameter of bcrop Nv : tuple Sizes of problem spatial indices dimN : int, optional (default 2) Number of problem spatial indices dimC : int, optional (default 1) Number of problem channel indices crp : bool, optional (default False) Flag indicating whether the result should be cropped to the support of the largest filter in the dictionary. zm : bool, optional (default False) Flag indicating whether the projection function should include filter mean subtraction fn : function Constraint set projection function
sporco.cnvrep._Pcn(x, dsz, Nv, dimN=2, dimC=1)[source]

Projection onto dictionary update constraint set: support projection and normalisation. The result has the full spatial dimensions of the input.

Parameters: x : array_like Input array dsz : tuple Filter support size(s), specified using the same format as the dsz parameter of bcrop Nv : tuple Sizes of problem spatial indices dimN : int, optional (default 2) Number of problem spatial indices dimC : int, optional (default 1) Number of problem channel indices y : ndarray Projection of input onto constraint set
sporco.cnvrep._Pcn_zm(x, dsz, Nv, dimN=2, dimC=1)[source]

Projection onto dictionary update constraint set: support projection, mean subtraction, and normalisation. The result has the full spatial dimensions of the input.

Parameters: x : array_like Input array dsz : tuple Filter support size(s), specified using the same format as the dsz parameter of bcrop Nv : tuple Sizes of problem spatial indices dimN : int, optional (default 2) Number of problem spatial indices dimC : int, optional (default 1) Number of problem channel indices y : ndarray Projection of input onto constraint set
sporco.cnvrep._Pcn_crp(x, dsz, Nv, dimN=2, dimC=1)[source]

Projection onto dictionary update constraint set: support projection and normalisation. The result is cropped to the support of the largest filter in the dictionary.

Parameters: x : array_like Input array dsz : tuple Filter support size(s), specified using the same format as the dsz parameter of bcrop Nv : tuple Sizes of problem spatial indices dimN : int, optional (default 2) Number of problem spatial indices dimC : int, optional (default 1) Number of problem channel indices y : ndarray Projection of input onto constraint set
sporco.cnvrep._Pcn_zm_crp(x, dsz, Nv, dimN=2, dimC=1)[source]

Projection onto dictionary update constraint set: support projection, mean subtraction, and normalisation. The result is cropped to the support of the largest filter in the dictionary.

Parameters: x : array_like Input array dsz : tuple Filter support size(s), specified using the same format as the dsz parameter of bcrop. Nv : tuple Sizes of problem spatial indices dimN : int, optional (default 2) Number of problem spatial indices dimC : int, optional (default 1) Number of problem channel indices y : ndarray Projection of input onto constraint set

## Class Descriptions¶

class sporco.cnvrep.CSC_ConvRepIndexing(D, S, dimK=None, dimN=2)[source]

Bases: object

Manage the inference of problem dimensions and the roles of numpy.ndarray indices for convolutional representations in convolutional sparse coding problems (e.g. admm.cbpdn.ConvBPDN and related classes).

Initialise a ConvRepIndexing object representing dimensions of S (input signal), D (dictionary), and X (coefficient array) in a convolutional representation. These dimensions are inferred from the input D and S as well as from parameters dimN and dimK. Management and inferrence of these problem dimensions is not entirely straightforward because admm.cbpdn.ConvBPDN and related classes make use internally of S, D, and X arrays with a standard layout (described below), but input S and D are allowed to deviate from this layout for the convenience of the user.

The most fundamental parameter is dimN, which specifies the dimensionality of the spatial/temporal samples being represented (e.g. dimN = 2 for representations of 2D images). This should be common to input S and D, and is also common to internal S, D, and X. The remaining dimensions of input S can correspond to multiple channels (e.g. for RGB images) and/or multiple signals (e.g. the array contains multiple independent images). If input S contains two additional dimensions (in addition to the dimN spatial dimensions), then those are considered to correspond, in order, to channel and signal indices. If there is only a single additional dimension, then determination whether it represents a channel or signal index is more complicated. The rule for making this determination is as follows:

• if dimK is set to 0 or 1 instead of the default None, then that value is taken as the number of signal indices in input S and any remaining indices are taken as channel indices (i.e. if dimK = 0 then dimC = 1 and if dimK = 1 then dimC = 0).
• if dimK is None then the number of channel dimensions is determined from the number of dimensions in the input dictionary D. Input D should have at least dimN + 1 dimensions, with the final dimension indexing dictionary filters. If it has exactly dimN + 1 dimensions then it is a single-channel dictionary, and input S is also assumed to be single-channel, with the additional index in S assigned as a signal index (i.e. dimK = 1). Conversely, if input D has dimN + 2 dimensions it is a multi-channel dictionary, and the additional index in S is assigned as a channel index (i.e. dimC = 1).

Note that it is an error to specify dimK = 1 if input S has dimN + 1 dimensions and input D has dimN + 2 dimensions since a multi-channel dictionary requires a multi-channel signal. (The converse is not true: a multi-channel signal can be decomposed using a single-channel dictionary.)

The internal data layout for S (signal), D (dictionary), and X (coefficient array) is (multi-channel dictionary)

  sptl.          chn  sig  flt
S(N0,  N1, ...,  C,   K,   1)
D(N0,  N1, ...,  C,   1,   M)
X(N0,  N1, ...,  1,   K,   M)


or (single-channel dictionary)

  sptl.          chn  sig  flt
S(N0,  N1, ...,  C,   K,   1)
D(N0,  N1, ...,  1,   1,   M)
X(N0,  N1, ...,  C,   K,   M)


where

• Nv = [N0, N1, …] and N = N0 x N1 x … are the vector of sizes of the spatial/temporal indices and the total number of spatial/temporal samples respectively
• C is the number of channels in S
• K is the number of signals in S
• M is the number of filters in D

It should be emphasised that dimC and dimK may take on values 0 or 1, and represent the number of channel and signal dimensions respectively in input S. In the internal layout of S there is always a dimension allocated for channels and signals. The number of channel dimensions in input D and the corresponding size of that index are represented by dimCd and Cd respectively.

Parameters: D : array_like Input dictionary S : array_like Input signal dimK : 0, 1, or None, optional (default None) Number of dimensions in input signal corresponding to multiple independent signals dimN : int, optional (default 2) Number of spatial/temporal dimensions of signal samples
class sporco.cnvrep.DictionarySize(dsz, dimN=2)[source]

Bases: object

Compute dictionary size parameters from a dictionary size specification tuple as in the dsz argument of bcrop.

Initialise a DictionarySize object.

Parameters: dsz : tuple Dictionary size specification (using the same format as the dsz argument of bcrop) dimN : int, optional (default 2) Number of spatial dimensions
class sporco.cnvrep.CDU_ConvRepIndexing(dsz, S, dimK=None, dimN=2)[source]

Bases: object

Manage the inference of problem dimensions and the roles of numpy.ndarray indices for convolutional representations in convolutional dictionary update problems (e.g. ConvCnstrMODBase and derived classes).

Initialise a ConvRepIndexing object representing dimensions of S (input signal), D (dictionary), and X (coefficient array) in a convolutional representation. These dimensions are inferred from the input dsz and S as well as from parameters dimN and dimK. Management and inferrence of these problem dimensions is not entirely straightforward because ConvCnstrMODBase and related classes make use internally of S, D, and X arrays with a standard layout (described below), but input S and dsz are allowed to deviate from this layout for the convenience of the user. Note that S, D, and X refers to the names of signal, dictionary, and coefficient map arrays in admm.cbpdn.ConvBPDN; the corresponding variable names in ConvCnstrMODBase are S, X, and Z.

The most fundamental parameter is dimN, which specifies the dimensionality of the spatial/temporal samples being represented (e.g. dimN = 2 for representations of 2D images). This should be common to input S and dsz, and is also common to internal S, D, and X. The remaining dimensions of input S can correspond to multiple channels (e.g. for RGB images) and/or multiple signals (e.g. the array contains multiple independent images). If input S contains two additional dimensions (in addition to the dimN spatial dimensions), then those are considered to correspond, in order, to channel and signal indices. If there is only a single additional dimension, then determination whether it represents a channel or signal index is more complicated. The rule for making this determination is as follows:

• if dimK is set to 0 or 1 instead of the default None, then that value is taken as the number of signal indices in input S and any remaining indices are taken as channel indices (i.e. if dimK = 0 then dimC = 1 and if dimK = 1 then dimC = 0).
• if dimK is None then the number of channel dimensions is determined from the number of dimensions specified in the input dictionary size dsz. Input dsz should specify at least dimN + 1 dimensions, with the final dimension indexing dictionary filters. If it has exactly dimN + 1 dimensions then it is a single-channel dictionary, and input S is also assumed to be single-channel, with the additional index in S assigned as a signal index (i.e. dimK = 1). Conversely, if input dsz specified dimN + 2 dimensions it is a multi-channel dictionary, and the additional index in S is assigned as a channel index (i.e. dimC = 1).

Note that it is an error to specify dimK = 1 if input S has dimN + 1 dimensions and input dsz specified dimN + 2 dimensions since a multi-channel dictionary requires a multi-channel signal. (The converse is not true: a multi-channel signal can be decomposed using a single-channel dictionary.)

The internal data layout for S (signal), D (dictionary), and X (coefficient array) is (multi-channel dictionary)

  sptl.          chn  sig  flt
S(N0,  N1, ...,  C,   K,   1)
D(N0,  N1, ...,  C,   1,   M)
X(N0,  N1, ...,  1,   K,   M)


or (single-channel dictionary)

  sptl.          chn  sig  flt
S(N0,  N1, ...,  C,   K,   1)
D(N0,  N1, ...,  1,   1,   M)
X(N0,  N1, ...,  C,   K,   M)


where

• Nv = [N0, N1, …] and N = N0 x N1 x … are the vector of sizes of the spatial/temporal indices and the total number of spatial/temporal samples respectively
• C is the number of channels in S
• K is the number of signals in S
• M is the number of filters in D

It should be emphasised that dimC and dimK may take on values 0 or 1, and represent the number of channel and signal dimensions respectively in input S. In the internal layout of S there is always a dimension allocated for channels and signals. The number of channel dimensions in input D and the corresponding size of that index are represented by dimCd and Cd respectively.

Parameters: dsz : tuple Dictionary size specification (using the same format as the dsz argument of bcrop) S : array_like Input signal dimK : 0, 1, or None, optional (default None) Number of dimensions in input signal corresponding to multiple independent signals dimN : int, optional (default 2) Number of spatial/temporal dimensions of signal samples