sporco.util

Utility functions.

Functions

complex_randn(*args)	Function sporco.util.complex_randn is deprecated; please use sporco.signal.complex_randn instead.
spnoise(s, frc[, smn, smx])	Function sporco.util.spnoise is deprecated; please use sporco.signal.spnoise instead.
rndmask(shp, frc[, dtype])	Function sporco.util.rndmask is deprecated; please use sporco.signal.rndmask instead.
rgb2gray(rgb)	Function sporco.util.rgb2gray is deprecated; please use sporco.signal.rgb2gray instead.
lstabsdev(A, b)	Function sporco.util.lstabsdev is deprecated; please use sporco.interp.lstabsdev instead.
lstmaxdev(A, b)	Function sporco.util.lstmaxdev is deprecated; please use sporco.interp.lstmaxdev instead.
lanczos_kernel(x[, a])	Function sporco.util.lanczos_kernel is deprecated; please use sporco.interp.lanczos_kernel instead.
interpolation_points(N[, include_zero])	Function sporco.util.interpolation_points is deprecated; please use sporco.interp.interpolation_points instead.
tikhonov_filter(s, lmbda[, npd])	Function sporco.util.tikhonov_filter is deprecated; please use sporco.signal.tikhonov_filter instead.
lanczos_filters(sz[, a, collapse_axes])	Function sporco.util.lanczos_filters is deprecated; please use sporco.interp.lanczos_filters instead.
gaussian(shape[, sd])	Function sporco.util.gaussian is deprecated; please use sporco.signal.gaussian instead.
local_contrast_normalise(s[, n, c])	Function sporco.util.local_contrast_normalise is deprecated; please use sporco.signal.local_contrast_normalise instead.
pca(U[, centre])	Function sporco.util.pca is deprecated; please use sporco.linalg.pca instead.
nkp(A, bshape, cshape)	Function sporco.util.nkp is deprecated; please use sporco.linalg.nkp instead.
kpsvd(A, bshape, cshape)	Function sporco.util.kpsvd is deprecated; please use sporco.linalg.kpsvd instead.
u(x)	Python 2/3 compatible definition of utf8 literals
idle_cpu_count([mincpu])	Estimate number of idle CPUs.
grid_search(fn, grd[, fmin, nproc])	Grid search for optimal parameters of a specified function.
netgetdata(url[, maxtry, timeout])	Get content of a file via a URL.
in_ipython()	Determine whether code is running in an ipython shell.
in_notebook()	Determine whether code is running in a Jupyter Notebook shell.
notebook_system_output()	Capture system-level stdout/stderr within a Jupyter Notebook shell.
tiledict(D[, sz])	Construct an image allowing visualization of dictionary content.
convdicts()	Access a set of example learned convolutional dictionaries.
_depwarn(fn)
ntpl2array(ntpl)
array2ntpl(arr)
transpose_ntpl_list(lst)
rolling_window(*args, **kwargs)
subsample_array(*args, **kwargs)
extract_blocks(*args, **kwargs)
average_blocks(*args, **kwargs)
combine_blocks(*args, **kwargs)

Classes

ExampleImages([scaled, dtype, zoom, gray, pth])	Access a set of example images.
Timer([labels, dfltlbl, alllbl])	Timer class supporting multiple independent labelled timers.
ContextTimer([timer, label, action])	A wrapper class for Timer that enables its use as a context manager.

Function Descriptions

sporco.util.complex_randn(*args)

Function sporco.util.complex_randn is deprecated; please use sporco.signal.complex_randn instead.

sporco.util.spnoise(s, frc, smn=0.0, smx=1.0)

Function sporco.util.spnoise is deprecated; please use sporco.signal.spnoise instead.

sporco.util.rndmask(shp, frc, dtype=None)

Function sporco.util.rndmask is deprecated; please use sporco.signal.rndmask instead.

sporco.util.rgb2gray(rgb)

Function sporco.util.rgb2gray is deprecated; please use sporco.signal.rgb2gray instead.

sporco.util.lstabsdev(A, b)

Function sporco.util.lstabsdev is deprecated; please use sporco.interp.lstabsdev instead.

sporco.util.lstmaxdev(A, b)

Function sporco.util.lstmaxdev is deprecated; please use sporco.interp.lstmaxdev instead.

sporco.util.lanczos_kernel(x, a=3)

Function sporco.util.lanczos_kernel is deprecated; please use sporco.interp.lanczos_kernel instead.

sporco.util.interpolation_points(N, include_zero=True)

Function sporco.util.interpolation_points is deprecated; please use sporco.interp.interpolation_points instead.

sporco.util.tikhonov_filter(s, lmbda, npd=16)

Function sporco.util.tikhonov_filter is deprecated; please use sporco.signal.tikhonov_filter instead.

sporco.util.lanczos_filters(sz, a=3, collapse_axes=True)

Function sporco.util.lanczos_filters is deprecated; please use sporco.interp.lanczos_filters instead.

sporco.util.gaussian(shape, sd=1.0)

Function sporco.util.gaussian is deprecated; please use sporco.signal.gaussian instead.

sporco.util.local_contrast_normalise(s, n=7, c=None)

Function sporco.util.local_contrast_normalise is deprecated; please use sporco.signal.local_contrast_normalise instead.

sporco.util.pca(U, centre=False)

Function sporco.util.pca is deprecated; please use sporco.linalg.pca instead.

sporco.util.nkp(A, bshape, cshape)

Function sporco.util.nkp is deprecated; please use sporco.linalg.nkp instead.

sporco.util.kpsvd(A, bshape, cshape)

Function sporco.util.kpsvd is deprecated; please use sporco.linalg.kpsvd instead.

sporco.util.u(x)

Python 2/3 compatible definition of utf8 literals

sporco.util.idle_cpu_count(mincpu=1)

Estimate number of idle CPUs.

Estimate number of idle CPUs, for use by multiprocessing code needing to determine how many processes can be run without excessive load. This function uses os.getloadavg which is only available under a Unix OS.

Parameters

mincpuint

Minimum number of CPUs to report, independent of actual estimate

Returns

idleint

Estimate of number of idle CPUs

sporco.util.grid_search(fn, grd, fmin=True, nproc=None)

Grid search for optimal parameters of a specified function.

Perform a grid search for optimal parameters of a specified function. In the simplest case the function returns a float value, and a single optimum value and corresponding parameter values are identified. If the function returns a tuple of values, each of these is taken to define a separate function on the search grid, with optimum function values and corresponding parameter values being identified for each of them. On Unix platforms the computation of the function at the grid points is computed in parallel. The computation is serial on Windows (where mp.Pool usage has some limitations) and MacOS (where parallel computation is no longer supported due to a recent change of the default process start method from fork to spawn).

Warning: This function will hang if fn makes use of pyfftw with multi-threading enabled (the bug has been reported). When using the FFT functions in sporco.fft, multi-threading can be disabled by including the following code:

import sporco.fft
sporco.fft.pyfftw_threads = 1

Parameters

fnfunction

Function to be evaluated. It should take a tuple of parameter values as an argument, and return a float value or a tuple of float values.

grdtuple of array_like

A tuple providing an array of sample points for each axis of the grid on which the search is to be performed.

fminbool, optional (default True)

Determine whether optimal function values are selected as minima or maxima. If fmin is True then minima are selected.

nprocint or None, optional (default None)

Number of processes to run in parallel. If None, the number of CPUs of the system is used.

Returns

sprmndarray

Optimal parameter values on each axis. If fn is multi-valued, sprm is a matrix with rows corresponding to parameter values and columns corresponding to function values.

sfvlfloat or ndarray

Optimum function value or values

fvmxndarray

Function value(s) on search grid

sidxtuple of int or tuple of ndarray

Indices of optimal values on parameter grid (note that sfvl = fvmx[sidx])

sporco.util.netgetdata(url, maxtry=3, timeout=10)

Get content of a file via a URL.

Parameters

urlstring

URL of the file to be downloaded

maxtryint, optional (default 3)

Maximum number of download retries

timeoutint, optional (default 10)

Timeout in seconds for blocking operations

Returns

strio.BytesIO

Buffered I/O stream

Raises

urlerror.URLError (urllib2.URLError in Python 2,

urllib.error.URLError in Python 3)

If the file cannot be downloaded

sporco.util.in_ipython()

Determine whether code is running in an ipython shell.

Returns

ipbool

True if running in an ipython shell, False otherwise

sporco.util.in_notebook()

Determine whether code is running in a Jupyter Notebook shell.

Returns

ipbool

True if running in a notebook shell, False otherwise

sporco.util.notebook_system_output()

Capture system-level stdout/stderr within a Jupyter Notebook shell.

Get a context manager that attempts to use wurlitzer to capture system-level stdout/stderr within a Jupyter Notebook shell, without affecting normal operation when run as a Python script. For example:

>>> sys_pipes = sporco.util.notebook_system_output()
>>> with sys_pipes():
>>>    command_producing_system_level_output()

Returns

sys_pipescontext manager

Context manager that handles output redirection when run within a Jupyter Notebook shell

sporco.util.tiledict(D, sz=None)

Construct an image allowing visualization of dictionary content.

Parameters

Darray_like

Dictionary matrix/array.

sztuple

Size of each block in dictionary.

Returns

imndarray

Image tiled with dictionary entries.

sporco.util.convdicts()

Access a set of example learned convolutional dictionaries.

Returns

cdddict

A dict associating description strings with dictionaries represented as ndarrays

Examples

Print the dict keys to obtain the identifiers of the available dictionaries

>>> from sporco import util
>>> cd = util.convdicts()
>>> print(cd.keys())
['G:12x12x72', 'G:8x8x16,12x12x32,16x16x48', ...]

Select a specific example dictionary using the corresponding identifier

>>> D = cd['G:8x8x96']

sporco.util._depwarn(fn)

sporco.util.ntpl2array(ntpl)

sporco.util.array2ntpl(arr)

sporco.util.transpose_ntpl_list(lst)

sporco.util.rolling_window(*args, **kwargs)

sporco.util.subsample_array(*args, **kwargs)

sporco.util.extract_blocks(*args, **kwargs)

sporco.util.average_blocks(*args, **kwargs)

sporco.util.combine_blocks(*args, **kwargs)

Class Descriptions

class sporco.util.ExampleImages(scaled=False, dtype=None, zoom=None, gray=False, pth=None)

Bases: object

Access a set of example images.

Parameters

scaledbool, optional (default False)

Flag indicating whether images should be on the range [0,…,255] with np.uint8 dtype (False), or on the range [0,…,1] with np.float32 dtype (True)

dtypedata-type or None, optional (default None)

Desired data type of images. If scaled is True and dtype is an integer type, the output data type is np.float32

zoomfloat or None, optional (default None)

Optional support rescaling factor to apply to the images

graybool, optional (default False)

Flag indicating whether RGB images should be converted to grayscale

pthstring or None (default None)

Path to directory containing image files. If the value is None the path points to a set of example images that are included with the package.

images()

Get list of available images.

Returns

nlstlist

A list of names of available images

groups()

Get list of available image groups.

Returns

grplist

A list of names of available image groups

groupimages(grp)

Get list of available images in specified group.

Parameters

grpstr

Name of image group

Returns

nlstlist

A list of names of available images in the specified group

image(fname, group=None, scaled=None, dtype=None, idxexp=None, zoom=None, gray=None)

Get named image.

Parameters

fnamestring

Filename of image

groupstring or None, optional (default None)

Name of image group

scaledbool or None, optional (default None)

Flag indicating whether images should be on the range [0,…,255] with np.uint8 dtype (False), or on the range [0,…,1] with np.float32 dtype (True). If the value is None, scaling behaviour is determined by the scaling parameter passed to the object initializer, otherwise that selection is overridden.

dtypedata-type or None, optional (default None)

Desired data type of images. If scaled is True and dtype is an integer type, the output data type is np.float32. If the value is None, the data type is determined by the dtype parameter passed to the object initializer, otherwise that selection is overridden.

idxexpindex expression or None, optional (default None)

An index expression selecting, for example, a cropped region of the requested image. This selection is applied before any zoom rescaling so the expression does not need to be modified when the zoom factor is changed.

zoomfloat or None, optional (default None)

Optional rescaling factor to apply to the images. If the value is None, support rescaling behaviour is determined by the zoom parameter passed to the object initializer, otherwise that selection is overridden.

graybool or None, optional (default None)

Flag indicating whether RGB images should be converted to grayscale. If the value is None, behaviour is determined by the gray parameter passed to the object initializer.

Returns

imgndarray

Image array

Raises

IOError

If the image is not accessible

class sporco.util.Timer(labels=None, dfltlbl='main', alllbl='all')

Bases: object

Timer class supporting multiple independent labelled timers.

The timer is based on the relative time returned by timeit.default_timer.

Parameters

labelsstring or list, optional (default None)

Specify the label(s) of the timer(s) to be initialised to zero.

dfltlblstring, optional (default ‘main’)

Set the default timer label to be used when methods are called without specifying a label

alllblstring, optional (default ‘all’)

Set the label string that will be used to denote all timer labels

start(labels=None)

Start specified timer(s).

Parameters

labelsstring or list, optional (default None)

Specify the label(s) of the timer(s) to be started. If it is None, start the default timer with label specified by the dfltlbl parameter of __init__.

stop(labels=None)

Stop specified timer(s).

Parameters

labelsstring or list, optional (default None)

Specify the label(s) of the timer(s) to be stopped. If it is None, stop the default timer with label specified by the dfltlbl parameter of __init__. If it is equal to the string specified by the alllbl parameter of __init__, stop all timers.

reset(labels=None)

Reset specified timer(s).

Parameters

labelsstring or list, optional (default None)

Specify the label(s) of the timer(s) to be stopped. If it is None, stop the default timer with label specified by the dfltlbl parameter of __init__. If it is equal to the string specified by the alllbl parameter of __init__, stop all timers.

elapsed(label=None, total=True)

Get elapsed time since timer start.

Parameters

labelstring, optional (default None)

Specify the label of the timer for which the elapsed time is required. If it is None, the default timer with label specified by the dfltlbl parameter of __init__ is selected.

totalbool, optional (default True)

If True return the total elapsed time since the first call of start for the selected timer, otherwise return the elapsed time since the most recent call of start for which there has not been a corresponding call to stop.

Returns

dltfloat

Elapsed time

labels()

Get a list of timer labels.

Returns

lbllist

List of timer labels

class sporco.util.ContextTimer(timer=None, label=None, action='StartStop')

Bases: object

A wrapper class for Timer that enables its use as a context manager.

For example, instead of

>>> t = Timer()
>>> t.start()
>>> do_something()
>>> t.stop()
>>> elapsed = t.elapsed()

one can use

>>> t = Timer()
>>> with ContextTimer(t):
...   do_something()
>>> elapsed = t.elapsed()

Parameters

timerclass:Timer object, optional (default None)

Specify the timer object to be used as a context manager. If None, a new class:Timer object is constructed.

labelstring, optional (default None)

Specify the label of the timer to be used. If it is None, start the default timer.

actionstring, optional (default ‘StartStop’)

Specify actions to be taken on context entry and exit. If the value is ‘StartStop’, start the timer on entry and stop on exit; if it is ‘StopStart’, stop the timer on entry and start it on exit.

elapsed(total=True)

Return the elapsed time for the timer.

Parameters

totalbool, optional (default True)

If True return the total elapsed time since the first call of start for the selected timer, otherwise return the elapsed time since the most recent call of start for which there has not been a corresponding call to stop.

Returns

dltfloat

Elapsed time