libics.core.util

func

class libics.core.util.func.Memoize(func)

Bases: object

Decorator. Caches a function’s return value each time it is called. If called later with the same arguments, the cached value is returned (not reevaluated).

Examples

>>> @Memoize
... def example_function(*args):
...     pass

Methods

__call__(*args)

Call self as a function.

class libics.core.util.func.PeriodicTimer(period, worker_func, *args, repetitions=None, **kwargs)

Bases: object

Periodic timer that runs a worker function after each period timeout.

Parameters

periodfloat: Timeout period in seconds.
worker_funccallable: Function that is periodically called. Call signature: worker_func(*args, **kwargs) with *args, **kwargs static arguments.
repetitionsint or None: Number of timeouts after the thread returns. None allows for infinite repetitions.

Notes

This timer can be restarted.

Methods

`__call__`()	Call self as a function.
`is_alive`()	Check whether thread is alive.
`run`()	Timer thread method that periodically calls a function.
`set_args`(args, *kwargs)	Sets the arguments with which the worker function is called.
`set_stop_action`(stop_action)	Sets the stop action.
`start`(args, *kwargs)	Starts a thread which runs the run method.
`stop`()	Stops the timer.

get_function
get_period

get_function()

get_period()

is_alive(): Check whether thread is alive.

run()

Timer thread method that periodically calls a function.

For starting a thread running this run method, call the start method.

Notes

Can be stopped by running the stop() method. No dynamic arguments are allowed. Static (keyword) arguments can be set by calling the set_args(*args, **kwargs) method. Timer has feedback, i.e. corrects runtime delays if delays are smaller than the period.

set_args(*args, **kwargs)

Sets the arguments with which the worker function is called.

The worker function will be called as worker_func(*args, **kwargs).

set_stop_action(stop_action)

Sets the stop action.

Parameters

stop_actioncallable: Function that is called upon stop method call. Call signature: stop_action().

start(*args, **kwargs)

Starts a thread which runs the run method.

Arguments are passed on to the Thread.start method.

stop(): Stops the timer.

class libics.core.util.func.StoppableThread(target=None, args=(), kwargs={}, stop_action=None)

Bases: threading.Thread

Thread that ends on a stop event.

To stop the thread, wait conditionally for the StoppableThread.stop_event to trigger.

Parameters

targetcallable: Callable object to be invoked by the run() method.
args, kwargs: (Keyword) arguments for the target invocation.
stop_actioncallable or None: Function that is called upon stop method call. None is interpreted as a pass function.

Notes

This thread cannot be restarted.

Attributes

daemon: A boolean value indicating whether this thread is a daemon thread.
ident: Thread identifier of this thread or None if it has not been started.
name: A string used for identification purposes only.
native_id: Native integral thread ID of this thread, or None if it has not been started.

Methods

`isAlive`()	Return whether the thread is alive.
`is_alive`()	Return whether the thread is alive.
`join`([timeout])	Wait until the thread terminates.
`run`()	Method representing the thread's activity.
`start`()	Start the thread's activity.
`stop`()	Stops the thread.

getName
isDaemon
setDaemon
setName

stop(): Stops the thread.

misc

libics.core.util.misc.assume_construct_obj(obj, cls_, raise_exception=None)

Asserts that the given object is of cls_ class. If not and obj is a dictionary, an instance of the class is constructed with the dictionary as keyword arguments.

Parameters

objobject or dict

Object itself, keyword argument dictionary or single positional argument.

cls_class

Class of instance to be constructed.

raise_exceptionException or None

Specifies the behaviour if object construction fails. None:

Returns the input object.

Exception:: Raises the given exception.

Returns

objcls_: Instance of given class or object itself.

Raises

raise_exception: Specified exception, if applicable.

libics.core.util.misc.assume_dir(path)

Asserts that the given path directory exists. If not, the path will be created. path is interpreted as file path if it does not end with “/” and has an extension *.*, otherwise it is interpreted as directory.

Parameters

pathstr: Path of required directory or path to file in required directory.

Returns

dir_pathstr: If the directory did not exist, it was created. The directory path is returned.

libics.core.util.misc.assume_endswith(string, suffix)

Asserts that the passed string ends with with suffix. If it does not, the suffix is appended. The assumed result is returned.

Parameters

stringstr: String to be checked.
suffixstr: Assumed end of string.

Returns

stringstr: String with assumed ending.

Raises

AssertionError: If the parameters are invalid.

libics.core.util.misc.assume_even_int(val): Asserts that val is a scalar even integer.

libics.core.util.misc.assume_iter(data)

Asserts that data is iterable. If the given data is iterable, it is returned. If it is not, a list with the data as single element is returned.

Parameters

data: Input data to be checked for iterability.

Returns

dataiterable: Returns an iterable version of data.

libics.core.util.misc.assume_list(data)

Asserts that data is a list. If the given data is a tuple, it is cast to a list. If not, a list is created with the data as single item.

Parameters

data: Input data to be checked for list.

Returns

datalist: Returns a list containing data.

libics.core.util.misc.assume_numpy_array(data, shape=None, error='raise')

Asserts that data is a numpy.ndarray object (with given shape).

Parameters

data: Input data to be checked for numpy.ndarray.
shapetuple(int) or None: If given data is scalar, creates a numpy array with given shape containing given data as element. If given data has a different shape, performs error handling according to the error parameter.
errorstr: Controls how to handle shape errors: “raise”: raises a ValueError. “repeat” or “tile”: appends the data or crops it to match the shape. Repeating means “[1, 2, 3] -> [1, 1, 2, 2, 3, 3], tiling means “[1, 2, 3] -> [1, 2, 3, 1, 2, 3].

Returns

datanp.ndarray: Returns a numpy array data.

libics.core.util.misc.assume_odd_int(val): Asserts that val is a scalar odd integer.

libics.core.util.misc.assume_startswith(string, prefix)

Asserts that the passed string starts with with prefix. If it does not, the prefix is prepended. The assumed result is returned.

Parameters

stringstr: String to be checked.
prefixstr: Assumed start of string.

Returns

stringstr: String with assumed beginning.

Raises

AssertionError: If the parameters are invalid.

libics.core.util.misc.assume_tuple(data)

Asserts that data is a tuple. If the given data is a list, it is cast to a tuple. If not, a tuple is created with the data as single item.

Parameters

data: Input data to be checked for list.

Returns

datatuple: Returns a tuple containing data.

libics.core.util.misc.capitalize_first_char(s)

Capitalizes the first character (if possible) and leaves the rest of the string invariant.

Parameters

sstr: String to be capitalized.

Returns

s_capstr: Capitalized string.

libics.core.util.misc.char_range(start, stop=None, step=1)

Yield an alphabetic range of lowercase letters.

Parameters

startchr: Start character. If stop is None: stop character (default start character: ‘a’).
stopchr or int or None: If char: stop character (including stop). If int: number of steps (not including stop). If None: uses start as stop character
stepint: Character steps per repetition.

Yields

lr: Letter range.

libics.core.util.misc.cv_array_points_to_bins(ar)

Converts a center point array to bin points.

Dimensions: (ndim0, ndim1, …) -> (ndim0 + 1, ndim1 + 1, …).

Notes

FIXME: Does not work for multiple dimensions. TODO: Does not apply proper dimensional averaging, only “diagonal” two-point average.

libics.core.util.misc.cv_bitfield(n)

Converts an integer to a list of booleans.

Parameters

nint: Integer number representing the bit field.

Returns

bflist(bool): Converted bitfield.

libics.core.util.misc.cv_camel_to_snake_case(s, snake_char='_')

Converts CamelCase to snake_case.

Parameters

sstr: String in CamelCase
snake_charstr: Snake case concatenation character.

Returns

sstr: String in snake_case.

libics.core.util.misc.cv_datetime(var)

Converts to a Python datetime object.

Parameters

varpd.Timestamp or float or str: float: Python timestamp. str: Python datetime isoformat.

libics.core.util.misc.cv_float(text, dec_sep=['.', ','])

Converts a string into a float.

Parameters

textstr: Numeric text.
dec_sepstr or Iter[str]: Single or multiple decimal separators.

libics.core.util.misc.cv_index_center_to_rect(center, size)

Converts center-size indices to min-max indices.

Parameters

centerIter[int]: Index center in each dimension.
sizeIter[int] or int: (Full) size of rectangle in each dimension. If int, the size is applied to each dimension.

Returns

rectIter[(int, int)]: Index rectangle where the outer iterator corresponds to the dimension and the inner tuple corresponds to the slice (min, max).

libics.core.util.misc.cv_index_center_to_slice(center, size): Shorthand for applying cv_index_rect_to_slice(cv_index_center_to_rect()).

libics.core.util.misc.cv_index_ellipsis(indices, ndim)

Resolves an indexing tuple containing Ellipsis into explicit slices.

Parameters

indicesIter[int or slice or Ellipsis]: Indexing tuple.
ndimint: Number of dimensions of resolved indexing tuple.

Returns

resolved_indicestuple(int or slice): Indexing tuple with Ellipsis resolved.

Examples

>>> ar = np.arange(2*3*4*5).reshape((2, 3, 4, 5))
>>> indices = (1, ..., 4)
>>> ar[indices]
array([[ 64,  69,  74,  79],
       [ 84,  89,  94,  99],
       [104, 109, 114, 119]])
>>> resolved_indices = cv_index_ellipsis(indices, ar.ndim)
>>> resolved_indices
(1, slice(None, None, None), slice(None, None, None), 4)
>>> np.all(ar[indices] == ar[resolved_indices])
True

libics.core.util.misc.cv_index_mask_to_rect(mask)

Converts boolean mask to rectangle. Assumes rectangular mask.

Parameters

masknp.ndarray(bool): Boolean mask with array shape.

Returns

rectIter[(int, int)]: Index rectangle where the outer iterator corresponds to the dimension and the inner tuple corresponds to the slice (min, max).

libics.core.util.misc.cv_index_rect_to_slice(rect)

Converts min-max indices to slices.

Parameters

rectIter[(int, int) or slice]: Index rectangle where the outer iterator corresponds to the dimension and the inner tuple corresponds to the slice (min, max).

Returns

slicesIter[slice]: Iterator of slices from index rectangle.

libics.core.util.misc.cv_iter_to_str(_iter, fmt=None, join=', ', prefix='[', suffix=']')

Converts an iterable to a single string.

Parameters

_iterIter[Any]: Iterable to be converted.
fmtstr or None: Formatter string, e.g.: “{:.2f}”, “{:03d}”, “{:4.3e}”. If None, the items in _iter are converted by str().
joinstr: Characters used to join the items.
prefix, suffixstr: Prefix/suffix prepended/appended to the joined string.

Returns

sstr: Converted string.

libics.core.util.misc.cv_timestamp(var)

Converts a date/time to the Python datetime timestamp.

Parameters

vardatetime.datetime or pd.Timestamp: Date/time object.

libics.core.util.misc.do_nothing(*args, **kwargs): Takes any arguments and keyword arguments and does nothing.

libics.core.util.misc.extract(s, regex, group=1, cv_func=None, flags=0)

Extracts part of a string. Serves as convenience function to re.search.

Parameters

sstr: String from which to extract.
regexstr: Regular expression defining search function. Search findings should be enclosed in parentheses ().
groupint or list(int) or tuple(int) or np.ndarray(1, int): Group index of search results. If list, returns corresponding list of search results.
cv_funccallable or None: Conversion function applied to search results (e.g. float).
flagsint: Flags parameter passed to re.search.

Returns

result: Converted (if applicable) search result or results as defined by the group parameter.

Raises

KeyError: If extraction failed.

libics.core.util.misc.extract_index_nonunique_array(vec, min_count=2, rtol=1e-08)

Filters a vector for non-unique values and returns their indices.

Parameters

vecnp.ndarray(1): Vector from which to extract indices of non-unique values.
min_countint: Minimum multiplicity of values.
rtolfloat: Relative tolerance defining the minimum deviation required to regard values as different. Only used for non-integer types.

Returns

idxiter(np.ndarray(1, int)): Iterable filter of lists of indices.

libics.core.util.misc.filter_in_iter(ls, it)

Filters the elements of a list that are in an iterable.

Parameters

lsIter: List to be filtered.
itIter: Iterable to filter by. Only elements in ls which are also in it are returned.

Returns

lsfilter: Filtered list.

libics.core.util.misc.flatten_nested_dict(d, delim='.')

Flattens a nested dictionary into a top-level dictionary. Levels are separated by the specified delimiter. Note that dictionary keys may only be of str type.

Parameters

ddict: Dictionary to be flattened.
delimstr: Level delimiter for keys.

Returns

ddict: Flattened dictionary.

libics.core.util.misc.flatten_nested_list(ls)

Flattens a nested list recursively.

Parameters

lslist: Nested list.

Returns

flat_lslist: Flattened list.

Notes

Inefficient implementation.

libics.core.util.misc.generate_fill_chars(s, fill_char=' ')

Generates fill characters with the same length as s.

Parameters

sint or object which implements len: Object or length of object defining length of fill character string.
fill_charstr: String defining the fill character. Multi-character fill_char produces a series of fill characters which is cut to a length defined by s.

Returns

fsstr: Fill string with length defined by s.

libics.core.util.misc.get_combinations(ls, flatten=True, dtype=None)

Takes an iterable of iterables and returns a list with all possible mutual, ordered combinations.

Parameters

lsIter[Any]: Iterable from which combinations are constructed.
flattenbool: Whether to flatten the items in ls. If True, the algorithm is faster but cannot work with e.g. items in ls that are multi-dimensional arrays.
dtypeNone or callable: Combinations are given as numpy array. If callable, dtype is called on the returned numpy array.

Returns

combnp.ndarray or Any: Combinations list.

Examples

>>> ls = [(1, 2), (5, ), (7, 8)]
>>> get_combinations(ls, dtype=list)
[[1, 5, 7], [1, 5, 8], [2, 5, 7], [2, 5, 8]]

libics.core.util.misc.get_first_elem_iter(ls)

Gets the first element of a (nested) iterable.

Parameters

lsiterable: Indexed iterable (list, tuple).

Returns

elem: First element of the iterable.

libics.core.util.misc.get_numpy_array_index(ar_or_ndim, dim, idx, default_idx=slice(None, None, None))

Gets the multidimensional index to slice an array.

Parameters

ar_or_ndimnp.ndarray or int: Array or number of dimensions of targeted array.
dimint or Iterable[int]: Index or indices of dimensions.
idxint or slice or Iterable[int or slice]: Actual indices. If iterable is given, must be in the same order as dim.
default_idxint or slice: Indices of dimensions not in dim.

Returns

slctuple(int or slice): Slicing indices.

Examples

>>> ar = np.arange(2 * 3 * 4).reshape((2, 3, 4))
>>> slc0 = get_numpy_array_index(ar, (0, 2), (0, 0))
>>> np.all(ar[slc0] == ar[0, :, 0])
True
>>> slc1 = get_numpy_array_index(ar.ndim, (1, 2), (0, slice(0, 2)))
>>> np.all(ar[slc1] == ar[:, 0, 0:2])
True

libics.core.util.misc.get_numpy_dtype_str(dtype)

Gets the Python built-in type string corresponding to the given numpy dtype. If no matching built-in type is found, the numpy string representation of the dtype is returned.

Parameters

dtypenumpy.dtype: Numpy data type.

Returns

dtype_strstr: String corresponding to numpy data type.

libics.core.util.misc.get_regex_number(sgn=True, dec_sep='.')

Gets the regular expression for a signed decimal floating point number.

Parameters

sgnbool: Whether to allow sign before number.
dec_sepstr: Decimal separator character. Multiple separators can be used by passing multiple characters, e.g. “.,” for both point and comma as separators.

libics.core.util.misc.get_si_prefix(val, cutoff=1)

Gets value and SI unit prefix.

Parameters

valfloat: Value in base SI unit.
cutofffloat: Numerical value, at which the next SI prefix is chosen.

Returns

valfloat: Value in prefixed SI unit.
prefixstr: SI prefix.

libics.core.util.misc.hex_positive(number, nbits=64): Returns the hex of an integer without sign with given number of bits.

libics.core.util.misc.id_dict(arg): Takes any iterable and returns a dictionary mapping the item values to themselves.

libics.core.util.misc.is_datetime(var): Returns whether given variable is of date/time type.

libics.core.util.misc.is_iter(var): Returns whether given variable is iterable.

libics.core.util.misc.is_number(var): Returns whether given variable is of scalar, numeric type.

libics.core.util.misc.iter_progress(it, **kwargs)

Returns an iterator and prints a progress bar for each iteration.

Note that it must be sized (i.e. has a length). **kwargs are passed to print_progress().

libics.core.util.misc.make_dict(key_list, val_list)

Creates a dictionary from a key list and a value list.

Parameters

key_list, val_listlist: Same-length lists with keys and values. Mapping is performed on an index basis.

Returns

ddict: Created dictionary with key_list as keys and val_list as values.

Raises

AssertionError: If the lengths of the lists do not match.

libics.core.util.misc.make_getitem_func(arg)

Takes an object which implements __getitem__ and accesses this method.

Parameters

argindexable: Object with __getitem__ method, e.g. dict or list.

Returns

funccallable: Function signature: func(x)->y. Takes an argument and calls the getitem method. If the argument is invalid, the function returns identity.

libics.core.util.misc.map_dicts(func, *arg_dicts, kwarg_dicts={}, pre_args=(), post_args=(), **kwargs)

Constructs a new dictionary containing all common keys. Calls the given function with the key’s corresponding values and assigns the return value to the new dictionary.

Parameters

funccallable: Function to be mapped.
*arg_dictsdict: Dictionaries whose values are mapped as arguments.
kwarg_dictsdict(dict): Dictionaries whose values are mapped as keyword arguments. The keys of kwarg_dicts correspond to the keywords.
pre_args, post_argstuple: Arguments passed to func (before, after) dict values, i.e. func(*pre_args, *dict_vals, *post_args).
**kwargs: Keyword arguments passed to func.

Returns

ddict: Mapped dictionary.

Examples

map_dicts(func, d1, d2) performs new_dict[key] = func(d1, d2) for all keys common to both d1 and d2.

libics.core.util.misc.nest_flattened_dict(d, delim='.')

Nests (“unflattens”) a flattened dictionary. Levels are assumed to be separated by the specified delimiter.

Parameters

ddict: Flattened dictionary.
delimstr: Level delimiter of keys.

Returns

ddict: Nested dictionary.

libics.core.util.misc.order_list(ls, order)

Sorts a list according to a given index order.

Parameters

lslist: List to be sorted.
orderlist(int): Sorting index order.

Returns

lslist: Sorted list.

libics.core.util.misc.print_progress(count, total, subcount=None, subtotal=None, start_time=None, prefix='', fill='#', empty='·', bar_length=40, total_length=80, end=None)

libics.core.util.misc.rename_dict_keys(d, key_map, in_place=True)

Renames keys of a dictionary.

Parameters

ddict: Dictionary to be renamed.
key_mapdict: Mapping between old key and new key.
in_placebool: If True, changes the dictionary in place; if False, creates a copy of the dictionary.

Returns

d_newdict: Renamed dictionary.

libics.core.util.misc.resize_numpy_array(ar, shape, fill_value=0, mode_keep='front', dtype=None)

Pads or shrinks a numpy array to a requested shape.

Parameters

arnp.ndarray: Numpy array to be resized.
shapetuple(int): Target shape of array. Must have same dimension as ar.
fill_valuear.dtype: Pad value if array is increased.
mode_keep“front”, “back”, “center”: Keeps the elements of ar at the front/back/center of the resized array.
dtypenp.dtype or None: Numpy data type to cast to. If None, uses dtype of ar.

Returns

resized_arnp.ndarray: Resized numpy array.

libics.core.util.misc.ret_id(arg): Takes any argument and returns the input.

libics.core.util.misc.reverse_dict(d)

Constructs a value-to-key dictionary from the given dictionary. Does not check for duplicates, so duplicate mapping will be random.

Parameters

ddict: Dictionary to be reversed.

Returns

rev_ddict: Reversed dictionary.

libics.core.util.misc.split_strip(s, delim=',', strip=' \t\n\r')

Splits a given string and strips each list element from given characters.

Parameters

sstr: String to be split.
delimstr or None: String delimiter. If None, string will not be split.
stripstr: Strip characters.

Returns

lslist(str) or str: Returns stripped (list of) string depending on delim parameter.

libics.core.util.misc.split_unit(s)

Splits a given string into a tuple of numerical value and unit.

Parameters

sstr: String to be split.

Returns

valint or float or str: Numerical value or unchanged string.
unitstr: Unit.

Notes

If no numerical value could be determined, unit is None and the given string is returned as value. If only a numerical value could be determined, unit is None and the given string is cast to numerical format.

libics.core.util.misc.str_si_prefix(val, unit='', precision=3, cutoff=1)

String formatting for get_si_prefix().

Parameters

valfloat: Value in base SI unit.
unitstr: Base unit.
precisionint: Number of decimal digits.
cutofffloat: Numerical value, at which the next SI prefix is chosen.

Examples

>>> str_si_prefix(1e-5, "W")
10.000µW
>>> str_si_prefix(1e-10, "W", precision=0)
100pW

libics.core.util.misc.transpose_array(ar)

Transposes a rectangular array.

Parameters

arnumpy.ndarray or list(list) or tuple(tuple): Rectangular array to be transposed.

Returns

arnumpy.ndarray or list(list) or tuple(tuple): Transposed array.

path

class libics.core.util.path.FolderContentsResult(**kwargs)

Bases: object

Results container for get_folder_contents().

Attributes

regexstr: Matching regex.
pathstr: Parent directory path used for search.
folderslist(str): Full list of subfolders.
fileslist(str): Full list of files within folder.
folders_matchedlist(str): List of matched folders.
files_matchedlist(str): List of matched files.
folders_unmatchedlist(str): List of unmatched folders.
files_unmatchedlist(str): List of unmatched files.

property files

property folders

libics.core.util.path.assume_file_exists(file_path)

Checks if a file exists. Creates an empty file if not.

Parameters

file_pathstr: Path to the file to be checked.

Returns

existedbool: True if file has existed before.

libics.core.util.path.get_folder_contents(folder, regex=None)

Gets the files/subfolders in a folder.

Parameters

folderstr: Folder in which to search for files/subfolders.
regexstr: Regular expression that is checked.

Returns

resFolderContentsResult: Result container.

Raises

FileNotFoundError: If the folder does not exist.