sporco.util

Utility functions.

Functions

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