Miscellaneous utilities

allel.util.hdf5_cache(filepath=None, parent=None, group=None, names=None, typed=False, hashed_key=False, **h5dcreate_kwargs)

HDF5 cache decorator.

Parameters:

filepath : string, optional

Path to HDF5 file. If None a temporary file name will be used.

parent : string, optional

Path to group within HDF5 file to use as parent. If None the root group will be used.

group : string, optional

Path to group within HDF5 file, relative to parent, to use as container for cached data. If None the name of the wrapped function will be used.

names : sequence of strings, optional

Name(s) of dataset(s). If None, default names will be ‘f00’, ‘f01’, etc.

typed : bool, optional

If True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

hashed_key : bool, optional

If False (default) the key will not be hashed, which makes for readable cache group names. If True the key will be hashed, however note that on Python >= 3.3 the hash value will not be the same between sessions unless the environment variable PYTHONHASHSEED has been set to the same value.

Returns:

decorator : function

Examples

Without any arguments, will cache using a temporary HDF5 file:

>>> import allel
>>> @allel.util.hdf5_cache()
... def foo(n):
...     print('executing foo')
...     return np.arange(n)
...
>>> foo(3)
executing foo
array([0, 1, 2])
>>> foo(3)
array([0, 1, 2])
>>> foo.cache_filepath 
'/tmp/tmp_jwtwgjz'

Supports multiple return values, including scalars, e.g.:

>>> @allel.util.hdf5_cache()
... def bar(n):
...     print('executing bar')
...     a = np.arange(n)
...     return a, a**2, n**2
...
>>> bar(3)
executing bar
(array([0, 1, 2]), array([0, 1, 4]), 9)
>>> bar(3)
(array([0, 1, 2]), array([0, 1, 4]), 9)

Names can also be specified for the datasets, e.g.:

>>> @allel.util.hdf5_cache(names=['z', 'x', 'y'])
... def baz(n):
...     print('executing baz')
...     a = np.arange(n)
...     return a, a**2, n**2
...
>>> baz(3)
executing baz
(array([0, 1, 2]), array([0, 1, 4]), 9)
>>> baz(3)
(array([0, 1, 2]), array([0, 1, 4]), 9)