sporco.cnvrep¶

Classes and functions that support working with convolutional representations.

Functions

`stdformD`(D, Cd, M[, dimN])	Reshape dictionary array to internal standard form.
`l1Wshape`(W, cri)	Get internal shape for an \(\ell_1\) norm weight array.
`mskWshape`(W, cri)	Get internal shape for a data fidelity term mask array.
`zeromean`(v, dsz[, dimN])	Subtract mean value from each filter in the input array v.
`normalise`(v[, dimN])	Normalise vector components of input array.
`zpad`(v, Nv)	Zero-pad initial axes of array to specified size.
`bcrop`(v, dsz[, dimN])	Crop 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])	Dictionary support projection and normalisation.
`_Pcn_zm`(x, dsz, Nv[, dimN, dimC])	Dictionary support projection, mean subtraction, and normalisation.
`_Pcn_crp`(x, dsz, Nv[, dimN, dimC])	Dictionary support projection and normalisation (cropped).
`_Pcn_zm_crp`(x, dsz, Nv[, dimN, dimC])	Dictionary support projection, mean subtraction, and normalisation (cropped).

Classes

`CSC_ConvRepIndexing`(D, S[, dimK, dimN])	Array dimensions and indexing for CSC problems.
`DictionarySize`(dsz[, dimN])	Compute dictionary size parameters.
`CDU_ConvRepIndexing`(dsz, S[, dimK, dimN])	Array dimensions and indexing for CDU problems.

Function Descriptions¶

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

Reshape dictionary array to internal standard form.

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

Parameters

Darray_like
Dictionary array

Cdint
Size of dictionary channel index

Mint
Number of filters in dictionary

dimNint, optional (default 2)
Number of problem spatial indices

Returns

Drndarray
Reshaped dictionary array

sporco.cnvrep.l1Wshape(W, cri)[source]¶

Get internal shape for an \(\ell_1\) norm weight array.

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

Warray_like
Weight array

criCSC_ConvRepIndexing object
Object specifying convolutional representation dimensions

Returns

shptuple
Appropriate internal weight array shape

sporco.cnvrep.mskWshape(W, cri)[source]¶

Get internal shape for a data fidelity term mask array.

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 (if S has non-singleton channel and signal axes, the single non-spatial axis in W is taken as a channel axis).

Parameters

Warray_like
Data fidelity term weight/mask array

criCSC_ConvRepIndexing object or CDU_ConvRepIndexing object
Object specifying convolutional representation dimensions

Returns

shptuple
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

varray_like
Input dictionary array

dsztuple
Filter support size(s)

dimNint, optional (default 2)
Number of spatial dimensions

Returns

vzndarray
Dictionary array with filter means subtracted

sporco.cnvrep.normalise(v, dimN=2)[source]¶

Normalise vector components of input array.

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

varray_like
Array with components to be normalised

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

Returns

vnrmndarray
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

varray_like
Array to be padded

Nvtuple
Sizes to which each of initial indices should be padded

Returns

vpndarray
Padded array
sporco.cnvrep.bcrop(v, dsz, dimN=2)[source]¶
Crop dictionary array to specified size.

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

varray_like
Dictionary array to be cropped

dsztuple
Filter support size(s)

dimNint, optional (default 2)
Number of spatial dimensions

Returns

vcndarray
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

xarray_like
Input array

dsztuple
Filter support size(s), specified using the same format as the dsz parameter of bcrop

Nvtuple
Sizes of problem spatial indices

dimNint, optional (default 2)
Number of problem spatial indices

dimCint, optional (default 1)
Number of problem channel indices

crpbool, optional (default False)
Flag indicating whether the result should be cropped to the support of the largest filter in the dictionary.

zmbool, optional (default False)
Flag indicating whether the projection function should include filter mean subtraction

Returns

yndarray
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

dsztuple
Filter support size(s), specified using the same format as the dsz parameter of bcrop

Nvtuple
Sizes of problem spatial indices

dimNint, optional (default 2)
Number of problem spatial indices

dimCint, optional (default 1)
Number of problem channel indices

crpbool, optional (default False)
Flag indicating whether the result should be cropped to the support of the largest filter in the dictionary.

zmbool, optional (default False)
Flag indicating whether the projection function should include filter mean subtraction

Returns

fnfunction
Constraint set projection function

sporco.cnvrep._Pcn(x, dsz, Nv, dimN=2, dimC=1)[source]¶

Dictionary support projection and normalisation.

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

Parameters

xarray_like
Input array

dsztuple
Filter support size(s), specified using the same format as the dsz parameter of bcrop

Nvtuple
Sizes of problem spatial indices

dimNint, optional (default 2)
Number of problem spatial indices

dimCint, optional (default 1)
Number of problem channel indices

Returns

yndarray
Projection of input onto constraint set

sporco.cnvrep._Pcn_zm(x, dsz, Nv, dimN=2, dimC=1)[source]¶

Dictionary support projection, mean subtraction, and normalisation.

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

Parameters

xarray_like
Input array

dsztuple
Filter support size(s), specified using the same format as the dsz parameter of bcrop

Nvtuple
Sizes of problem spatial indices

dimNint, optional (default 2)
Number of problem spatial indices

dimCint, optional (default 1)
Number of problem channel indices

Returns

yndarray
Projection of input onto constraint set

sporco.cnvrep._Pcn_crp(x, dsz, Nv, dimN=2, dimC=1)[source]¶

Dictionary support projection and normalisation (cropped).

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

xarray_like
Input array

dsztuple
Filter support size(s), specified using the same format as the dsz parameter of bcrop

Nvtuple
Sizes of problem spatial indices

dimNint, optional (default 2)
Number of problem spatial indices

dimCint, optional (default 1)
Number of problem channel indices

Returns

yndarray
Projection of input onto constraint set

sporco.cnvrep._Pcn_zm_crp(x, dsz, Nv, dimN=2, dimC=1)[source]¶

Dictionary support projection, mean subtraction, and normalisation (cropped).

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

xarray_like
Input array

dsztuple
Filter support size(s), specified using the same format as the dsz parameter of bcrop.

Nvtuple
Sizes of problem spatial indices

dimNint, optional (default 2)
Number of problem spatial indices

dimCint, optional (default 1)
Number of problem channel indices

Returns

yndarray
Projection of input onto constraint set

Class Descriptions¶

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

Array dimensions and indexing for CSC problems.

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.

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

Darray_like
Input dictionary

Sarray_like
Input signal

dimK0, 1, or None, optional (default None)
Number of dimensions in input signal corresponding to multiple independent signals

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

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

Initialise a DictionarySize object.

Parameters

dsztuple
Dictionary size specification (using the same format as the dsz argument of bcrop)

dimNint, optional (default 2)
Number of spatial dimensions
class sporco.cnvrep.CDU_ConvRepIndexing(dsz, S, dimK=None, dimN=2)[source]¶
Bases: object

Array dimensions and indexing for CDU problems.

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.

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

dsztuple
Dictionary size specification (using the same format as the dsz argument of bcrop)

Sarray_like
Input signal

dimK0, 1, or None, optional (default None)
Number of dimensions in input signal corresponding to multiple independent signals

dimNint, optional (default 2)
Number of spatial/temporal dimensions of signal samples