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

Returns:
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 : CSC_ConvRepIndexing object

Object specifying convolutional representation dimensions

Returns:
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

Returns:
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

Returns:
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

Returns:
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

Returns:
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

Returns:
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

Returns:
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

Returns:
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

Returns:
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

Returns:
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

Returns:
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

Returns:
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