# 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_likeDictionary array

Cd: intSize of dictionary channel index

M: intNumber of filters in dictionary

dimN: int, optional (default 2)Number of problem spatial indices

Returns:

Dr: ndarrayReshaped 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_likeWeight array

cri:`CSC_ConvRepIndexing`

objectObject specifying convolutional representation dimensions

Returns:

shp: tupleAppropriate 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_likeData fidelity term weight/mask array

cri:`CSC_ConvRepIndexing`

object or`CDU_ConvRepIndexing`

objectObject specifying convolutional representation dimensions

Returns:

shp: tupleAppropriate 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_likeInput dictionary array

dsz: tupleFilter support size(s)

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

Returns:

vz: ndarrayDictionary 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_likeArray with components to be normalised

dimN: int, optional (default 2)Number of initial dimensions over which norm should be computed

Returns:

vnrm: ndarrayNormalised 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_likeArray to be padded

Nv: tupleSizes to which each of initial indices should be padded

Returns:

vp: ndarrayPadded 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_likeDictionary array to be cropped

dsz: tupleFilter support size(s)

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

Returns:

vc: ndarrayCropped 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_likeInput array

dsz: tupleFilter support size(s), specified using the same format as the dsz parameter of

`bcrop`

Nv: tupleSizes 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

Returns:

y: ndarrayProjection 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: tupleFilter support size(s), specified using the same format as the dsz parameter of

`bcrop`

Nv: tupleSizes 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

Returns:

fn: functionConstraint 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_likeInput array

dsz: tupleFilter support size(s), specified using the same format as the dsz parameter of

`bcrop`

Nv: tupleSizes of problem spatial indices

dimN: int, optional (default 2)Number of problem spatial indices

dimC: int, optional (default 1)Number of problem channel indices

Returns:

y: ndarrayProjection 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_likeInput array

dsz: tupleFilter support size(s), specified using the same format as the dsz parameter of

`bcrop`

Nv: tupleSizes of problem spatial indices

dimN: int, optional (default 2)Number of problem spatial indices

dimC: int, optional (default 1)Number of problem channel indices

Returns:

y: ndarrayProjection 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_likeInput array

dsz: tupleFilter support size(s), specified using the same format as the dsz parameter of

`bcrop`

Nv: tupleSizes of problem spatial indices

dimN: int, optional (default 2)Number of problem spatial indices

dimC: int, optional (default 1)Number of problem channel indices

Returns:

y: ndarrayProjection 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_likeInput array

dsz: tupleFilter support size(s), specified using the same format as the dsz parameter of

`bcrop`

.Nv: tupleSizes of problem spatial indices

dimN: int, optional (default 2)Number of problem spatial indices

dimC: int, optional (default 1)Number of problem channel indices

Returns:

y: ndarrayProjection 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 useinternallyof S, D, and X arrays with a standard layout (described below), butinputS 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

inputS and D, and is also common tointernalS, 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

internaldata 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_likeInput dictionary

S: array_likeInput 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: tupleDictionary 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 useinternallyof S, D, and X arrays with a standard layout (described below), butinputS 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

inputS and dsz, and is also common tointernalS, 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

internaldata 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: tupleDictionary size specification (using the same format as the dsz argument of

`bcrop`

)S: array_likeInput 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