CHAP.utils.general

File : general.py Author : Rolf Verberg Description: A collection of general modules

Module Contents

Functions

gformat	Format a number with ‘%g’-like format, while:
getfloat_attr	Format an attribute of an object for printing.
depth_list	Return the depth of a list.
depth_tuple	Return the depth of a tuple.
unwrap_tuple	Unwrap a tuple.
illegal_value	Print illegal value message and/or raise error.
illegal_combination	Print illegal combination message and/or raise error.
not_zero	Return value with a minimal absolute size of tiny, preserving the sign.
test_ge_gt_le_lt	Check individual and mutual validity of ge, gt, le, lt qualifiers.
range_string_ge_gt_le_lt	Return a range string representation matching the ge, gt, le, lt qualifiers. Does not validate the inputs, do that as needed before calling.
is_int	Value is an integer in range ge <= v <= le or gt < v < lt or some combination.
is_num	Value is a number in range ge <= v <= le or gt < v < lt or some combination.
_is_int_or_num
is_int_pair	Value is an integer pair, each in range ge <= v[i] <= le or gt < v[i] < lt or ge[i] <= v[i] <= le[i] or gt[i] < v[i] < lt[i] or some combination.
is_num_pair	Value is a number pair, each in range ge <= v[i] <= le or gt < v[i] < lt or ge[i] <= v[i] <= le[i] or gt[i] < v[i] < lt[i] or some combination.
_is_int_or_num_pair
is_int_series	Value is a tuple or list of integers, each in range ge <= l[i] <= le or gt < l[i] < lt or some combination.
is_num_series	Value is a tuple or list of numbers, each in range ge <= l[i] <= le or gt < l[i] < lt or some combination.
is_str_series	Value is a tuple or list of strings.
is_dict_series	Value is a tuple or list of dictionaries.
is_dict_nums	Value is a dictionary with single number values
is_dict_strings	Value is a dictionary with single string values
is_index	Value is an array index in range ge <= v < lt. NOTE lt IS NOT included!
is_index_range	Value is an array index range in range ge <= v[0] <= v[1] <= le or ge <= v[0] <= v[1] < lt. NOTE le IS included!
index_nearest	Return index of nearest array value.
index_nearest_down	Return index of nearest array value, rounded down
index_nearest_up	Return index of nearest array value, rounded up.
get_consecutive_int_range	Return a list of pairs of integers marking consecutive ranges of integers.
round_to_n	Round to a specific number of sig figs .
round_up_to_n	Round up to a specific number of sig figs.
trunc_to_n	Truncate to a specific number of sig figs.
almost_equal	Check if equal to within a certain number of significant digits.
string_to_list	Return a list of numbers by splitting/expanding a string on any combination of commas, whitespaces, or dashes (when split_on_dash=True). e.g: ‘1, 3, 5-8, 12 ‘ -> [1, 3, 5, 6, 7, 8, 12]
list_to_string	Return a list of pairs of integers marking consecutive ranges of integers in string notation.
get_trailing_int	Get the trailing integer in a string.
input_int	Interactively prompt the user to enter an integer.
input_num	Interactively prompt the user to enter a number.
_input_int_or_num	Interactively prompt the user to enter an integer or number.
input_int_list	Prompt the user to input a list of interger and split the entered string on any combination of commas, whitespaces, or dashes (when split_on_dash is True). e.g: ‘1 3,5-8 , 12 ‘ -> [1, 3, 5, 6, 7, 8, 12]
input_num_list	Prompt the user to input a list of numbers and split the entered string on any combination of commas or whitespaces. e.g: ‘1.0, 3, 5.8, 12 ‘ -> [1.0, 3.0, 5.8, 12.0]
_input_int_or_num_list
input_yesno	Interactively prompt the user to enter a y/n question.
input_menu	Interactively prompt the user to select from a menu.
assert_no_duplicates_in_list_of_dicts	Assert that there are no duplicates in a list of dictionaries.
assert_no_duplicate_key_in_list_of_dicts	Assert that there are no duplicate keys in a list of dictionaries.
assert_no_duplicate_attr_in_list_of_objs	Assert that there are no duplicate attributes in a list of objects.
file_exists_and_readable	Check if a file exists and is readable.
rolling_average	Returns the rolling sum or average of an array over the last dimension.
baseline_arPLS	Returns the smoothed baseline estimate of a spectrum.
select_mask_1d	Display a lineplot and have the user select a mask.
select_roi_1d	Display a 2D plot and have the user select a single region of interest.
select_roi_2d	Display a 2D image and have the user select a single rectangular region of interest.
select_image_indices	Display a 2D image and have the user select a set of image indices in either row or column direction.
quick_imshow	Display a 2D image.
quick_plot	Display a 2D line plot.
nxcopy	Function that returns a copy of a nexus object, optionally exluding certain child items.

Data

logger
tiny

API

CHAP.utils.general.logger

‘getLogger(…)’

CHAP.utils.general.tiny

None

CHAP.utils.general.gformat(val, length=11)

Format a number with ‘%g’-like format, while:

• the length of the output string will be of the requested length

• positive numbers will have a leading blank

• the precision will be as high as possible

• trailing zeros will not be trimmed

CHAP.utils.general.getfloat_attr(obj, attr, length=11)

Format an attribute of an object for printing.

CHAP.utils.general.depth_list(_list)

Return the depth of a list.

CHAP.utils.general.depth_tuple(_tuple)

Return the depth of a tuple.

CHAP.utils.general.unwrap_tuple(_tuple)

Unwrap a tuple.

CHAP.utils.general.illegal_value(value, name, location=None, raise_error=False, log=True)

Print illegal value message and/or raise error.

CHAP.utils.general.illegal_combination(value1, name1, value2, name2, location=None, raise_error=False, log=True)

Print illegal combination message and/or raise error.

CHAP.utils.general.not_zero(value)

Return value with a minimal absolute size of tiny, preserving the sign.

CHAP.utils.general.test_ge_gt_le_lt(ge, gt, le, lt, func, location=None, raise_error=False, log=True)

Check individual and mutual validity of ge, gt, le, lt qualifiers.

Parameters:

func (callable: is_int, is_num) – Test for integers or numbers

Returns:

True upon success or False when mutually exlusive

Return type:

bool

CHAP.utils.general.range_string_ge_gt_le_lt(ge=None, gt=None, le=None, lt=None)

Return a range string representation matching the ge, gt, le, lt qualifiers. Does not validate the inputs, do that as needed before calling.

CHAP.utils.general.is_int(v, ge=None, gt=None, le=None, lt=None, raise_error=False, log=True)

Value is an integer in range ge <= v <= le or gt < v < lt or some combination.

Returns:

True if yes or False is no

Return type:

bool

CHAP.utils.general.is_num(v, ge=None, gt=None, le=None, lt=None, raise_error=False, log=True)

Value is a number in range ge <= v <= le or gt < v < lt or some combination.

Returns:

True if yes or False is no

Return type:

bool

CHAP.utils.general._is_int_or_num(v, type_str, ge=None, gt=None, le=None, lt=None, raise_error=False, log=True)

CHAP.utils.general.is_int_pair(v, ge=None, gt=None, le=None, lt=None, raise_error=False, log=True)

Value is an integer pair, each in range ge <= v[i] <= le or gt < v[i] < lt or ge[i] <= v[i] <= le[i] or gt[i] < v[i] < lt[i] or some combination.

Returns:

True if yes or False is no

Return type:

bool

CHAP.utils.general.is_num_pair(v, ge=None, gt=None, le=None, lt=None, raise_error=False, log=True)

Value is a number pair, each in range ge <= v[i] <= le or gt < v[i] < lt or ge[i] <= v[i] <= le[i] or gt[i] < v[i] < lt[i] or some combination.

Returns:

True if yes or False is no

Return type:

bool

CHAP.utils.general._is_int_or_num_pair(v, type_str, ge=None, gt=None, le=None, lt=None, raise_error=False, log=True)

CHAP.utils.general.is_int_series(t_or_l, ge=None, gt=None, le=None, lt=None, raise_error=False, log=True)

Value is a tuple or list of integers, each in range ge <= l[i] <= le or gt < l[i] < lt or some combination.

CHAP.utils.general.is_num_series(t_or_l, ge=None, gt=None, le=None, lt=None, raise_error=False, log=True)

Value is a tuple or list of numbers, each in range ge <= l[i] <= le or gt < l[i] < lt or some combination.

CHAP.utils.general.is_str_series(t_or_l, raise_error=False, log=True)

Value is a tuple or list of strings.

CHAP.utils.general.is_dict_series(t_or_l, raise_error=False, log=True)

Value is a tuple or list of dictionaries.

CHAP.utils.general.is_dict_nums(d, raise_error=False, log=True)

Value is a dictionary with single number values

CHAP.utils.general.is_dict_strings(d, raise_error=False, log=True)

Value is a dictionary with single string values

CHAP.utils.general.is_index(v, ge=0, lt=None, raise_error=False, log=True)

Value is an array index in range ge <= v < lt. NOTE lt IS NOT included!

CHAP.utils.general.is_index_range(v, ge=0, le=None, lt=None, raise_error=False, log=True)

Value is an array index range in range ge <= v[0] <= v[1] <= le or ge <= v[0] <= v[1] < lt. NOTE le IS included!

CHAP.utils.general.index_nearest(a, value)

Return index of nearest array value.

CHAP.utils.general.index_nearest_down(a, value)

Return index of nearest array value, rounded down

CHAP.utils.general.index_nearest_up(a, value)

Return index of nearest array value, rounded up.

CHAP.utils.general.get_consecutive_int_range(a)

Return a list of pairs of integers marking consecutive ranges of integers.

CHAP.utils.general.round_to_n(x, n=1)

Round to a specific number of sig figs .

CHAP.utils.general.round_up_to_n(x, n=1)

Round up to a specific number of sig figs.

CHAP.utils.general.trunc_to_n(x, n=1)

Truncate to a specific number of sig figs.

CHAP.utils.general.almost_equal(a, b, sig_figs)

Check if equal to within a certain number of significant digits.

CHAP.utils.general.string_to_list(s, split_on_dash=True, remove_duplicates=True, sort=True, raise_error=False)

Return a list of numbers by splitting/expanding a string on any combination of commas, whitespaces, or dashes (when split_on_dash=True). e.g: ‘1, 3, 5-8, 12 ‘ -> [1, 3, 5, 6, 7, 8, 12]

CHAP.utils.general.list_to_string(a)

Return a list of pairs of integers marking consecutive ranges of integers in string notation.

CHAP.utils.general.get_trailing_int(string)

Get the trailing integer in a string.

CHAP.utils.general.input_int(s=None, ge=None, gt=None, le=None, lt=None, default=None, inset=None, raise_error=False, log=True)

Interactively prompt the user to enter an integer.

CHAP.utils.general.input_num(s=None, ge=None, gt=None, le=None, lt=None, default=None, raise_error=False, log=True)

Interactively prompt the user to enter a number.

CHAP.utils.general._input_int_or_num(type_str, s=None, ge=None, gt=None, le=None, lt=None, default=None, inset=None, raise_error=False, log=True)

Interactively prompt the user to enter an integer or number.

CHAP.utils.general.input_int_list(s=None, num_max=None, ge=None, le=None, split_on_dash=True, remove_duplicates=True, sort=True, raise_error=False, log=True)

Prompt the user to input a list of interger and split the entered string on any combination of commas, whitespaces, or dashes (when split_on_dash is True). e.g: ‘1 3,5-8 , 12 ‘ -> [1, 3, 5, 6, 7, 8, 12]

remove_duplicates: removes duplicates if True (may also change the order) sort: sort in ascending order if True return None upon an illegal input

CHAP.utils.general.input_num_list(s=None, num_max=None, ge=None, le=None, remove_duplicates=True, sort=True, raise_error=False, log=True)

Prompt the user to input a list of numbers and split the entered string on any combination of commas or whitespaces. e.g: ‘1.0, 3, 5.8, 12 ‘ -> [1.0, 3.0, 5.8, 12.0]

remove_duplicates: removes duplicates if True (may also change the order) sort: sort in ascending order if True return None upon an illegal input

CHAP.utils.general._input_int_or_num_list(type_str, s=None, num_max=None, ge=None, le=None, split_on_dash=True, remove_duplicates=True, sort=True, raise_error=False, log=True)

CHAP.utils.general.input_yesno(s=None, default=None)

Interactively prompt the user to enter a y/n question.

CHAP.utils.general.input_menu(items, default=None, header=None)

Interactively prompt the user to select from a menu.

CHAP.utils.general.assert_no_duplicates_in_list_of_dicts(_list, raise_error=False)

Assert that there are no duplicates in a list of dictionaries.

CHAP.utils.general.assert_no_duplicate_key_in_list_of_dicts(_list, key, raise_error=False)

Assert that there are no duplicate keys in a list of dictionaries.

CHAP.utils.general.assert_no_duplicate_attr_in_list_of_objs(_list, attr, raise_error=False)

Assert that there are no duplicate attributes in a list of objects.

CHAP.utils.general.file_exists_and_readable(f)

Check if a file exists and is readable.

CHAP.utils.general.rolling_average(y, x=None, dtype=None, start=0, end=None, width=None, stride=None, num=None, average=True, mode='valid', use_convolve=None)

Returns the rolling sum or average of an array over the last dimension.

CHAP.utils.general.baseline_arPLS(y, mask=None, w=None, tol=1e-08, lam=1000000.0, max_iter=20, full_output=False)

Returns the smoothed baseline estimate of a spectrum.

Based on S.-J. Baek, A. Park, Y.-J Ahn, and J. Choo, “Baseline correction using asymmetrically reweighted penalized least squares smoothing”, Analyst, 2015,140, 250-257

Parameters:

• y (array-like) – The spectrum.

• mask (array-like, optional) – A mask to apply to the spectrum before baseline construction, default to None.

• w (numpy.array, optional) – The weights (allows restart for additional ieterations), defaults to None.

• tol (float, optional) – The convergence tolerence, defaults to 1.e-8.

• lam (float, optional) – The &lambda (smoothness) parameter (the balance between the residual of the data and the baseline and the smoothness of the baseline). The suggested range is between 100 and 10^8, defaults to 10^6.

• max_iter (int, optional) – The maximum number of iterations, defaults to 20.

• full_output (bool, optional) – Whether or not to also output the baseline corrected spectrum, the number of iterations and error in the returned result, defaults to False.

Returns:

The smoothed baseline, with optionally the baseline corrected spectrum, the weights, the number of iterations and the error in the returned result.

Return type:

numpy.array [, numpy.array, int, float]

CHAP.utils.general.select_mask_1d(y, x=None, label=None, ref_data=[], preselected_index_ranges=None, preselected_mask=None, title=None, xlabel=None, ylabel=None, min_num_index_ranges=None, max_num_index_ranges=None, interactive=True, filename=None)

Display a lineplot and have the user select a mask.

Parameters:

• y (numpy.ndarray) – One-dimensional data array for which a mask will be constructed.

• x (numpy.ndarray, optional) – x-coordinates of the reference data, defaults to None.

• label (str, optional) – Legend label for the reference data, defaults to None.

• ref_data (list[tuple(tuple, dict)], optional) – A list of additional reference data to plot. Items in the list should be tuples of positional arguments and keyword arguments to unpack and pass directly to matplotlib.axes.Axes.plot, defaults to [].

• preselected_index_ranges (Union(list[tuple(int, int)], list[list[int]]), optional) – List of preselected index ranges to mask, defaults to None.

• preselected_mask (numpy.ndarray, optional) – Preselected boolean mask array, defaults to None.

• title (str, optional) – Title for the displayed figure, defaults to None.

• xlabel (str, optional) – Label for the x-axis of the displayed figure, defaults to None.

• ylabel (str, optional) – Label for the y-axis of the displayed figure, defaults to None.

• min_num_index_ranges (int, optional) – The minimum number of selected index ranges, defaults to None.

• max_num_index_ranges (int, optional) – The maximum number of selected index ranges, defaults to None.

• interactive (bool, optional) – Show the plot and allow user interactions with the matplotlib figure, defaults to True.

• filename (str, optional) – Save a .png of the plot to filename, defaults to None, in which case the plot is not saved.

Returns:

A boolean mask array and the list of selected index ranges.

Return type:

numpy.ndarray, list[tuple(int, int)]

CHAP.utils.general.select_roi_1d(y, x=None, preselected_roi=None, title=None, xlabel=None, ylabel=None, interactive=True, filename=None)

Display a 2D plot and have the user select a single region of interest.

Parameters:

• y (numpy.ndarray) – One-dimensional data array for which a for which a region of interest will be selected.

• x (numpy.ndarray, optional) – x-coordinates of the data, defaults to None.

• preselected_roi (tuple(int, int), optional) – Preselected region of interest, defaults to None.

• title (str, optional) – Title for the displayed figure, defaults to None.

• xlabel (str, optional) – Label for the x-axis of the displayed figure, defaults to None.

• ylabel (str, optional) – Label for the y-axis of the displayed figure, defaults to None.

• interactive (bool, optional) – Show the plot and allow user interactions with the matplotlib figure, defaults to True.

• filename (str, optional) – Save a .png of the plot to filename, defaults to None, in which case the plot is not saved.

Returns:

The selected region of interest as array indices and a matplotlib figure.

Return type:

matplotlib.figure.Figure, tuple(int, int)

CHAP.utils.general.select_roi_2d(a, preselected_roi=None, title=None, title_a=None, row_label='row index', column_label='column index', interactive=True, filename=None)

Display a 2D image and have the user select a single rectangular region of interest.

Parameters:

• a (numpy.ndarray) – Two-dimensional image data array for which a region of interest will be selected.

• preselected_roi (tuple(int, int, int, int), optional) – Preselected region of interest, defaults to None.

• title (str, optional) – Title for the displayed figure, defaults to None.

• title_a (str, optional) – Title for the image of a, defaults to None.

• row_label (str, optional) – Label for the y-axis of the displayed figure, defaults to row index.

• column_label (str, optional) – Label for the x-axis of the displayed figure, defaults to column index.

• interactive (bool, optional) – Show the plot and allow user interactions with the matplotlib figure, defaults to True.

• filename (str, optional) – Save a .png of the plot to filename, defaults to None, in which case the plot is not saved.

Returns:

The selected region of interest as array indices.

Return type:

tuple(int, int, int, int)

CHAP.utils.general.select_image_indices(a, axis, b=None, preselected_indices=None, axis_index_offset=0, min_range=None, min_num_indices=2, max_num_indices=2, title=None, title_a=None, title_b=None, row_label='row index', column_label='column index', interactive=True)

Display a 2D image and have the user select a set of image indices in either row or column direction.

Parameters:

• a (numpy.ndarray) – Two-dimensional image data array for which a region of interest will be selected.

• axis (int) – The selection direction (0: row, 1: column)

• b (numpy.ndarray, optional) – A secondary two-dimensional image data array for which a shared region of interest will be selected, defaults to None.

• preselected_indices (tuple(int), list(int), optional) – Preselected image indices, defaults to None.

• axis_index_offset (int, optional) – Offset in axis index range and preselected indices, defaults to 0.

• min_range (int, optional) – The minimal range spanned by the selected indices, defaults to None

• min_num_indices (int, optional) – The minimum number of selected indices, defaults to None.

• max_num_indices (int, optional) – The maximum number of selected indices, defaults to None.

• title (str, optional) – Title for the displayed figure, defaults to None.

• title_a (str, optional) – Title for the image of a, defaults to None.

• title_b (str, optional) – Title for the image of b, defaults to None.

• row_label (str, optional) – Label for the y-axis of the displayed figure, defaults to row index.

• column_label (str, optional) – Label for the x-axis of the displayed figure, defaults to column index.

• interactive (bool, optional) – Show the plot and allow user interactions with the matplotlib figure, defaults to True.

Returns:

The selected region of interest as array indices and a matplotlib figure.

Return type:

matplotlib.figure.Figure, tuple(int, int, int, int)

CHAP.utils.general.quick_imshow(a, title=None, row_label='row index', column_label='column index', path=None, name=None, save_fig=False, save_only=False, extent=None, show_grid=False, grid_color='w', grid_linewidth=1, block=False, **kwargs)

Display a 2D image.

CHAP.utils.general.quick_plot(*args, xerr=None, yerr=None, vlines=None, title=None, xlim=None, ylim=None, xlabel=None, ylabel=None, legend=None, path=None, name=None, show_grid=False, save_fig=False, save_only=False, block=False, **kwargs)

Display a 2D line plot.

CHAP.utils.general.nxcopy(nxobject, exclude_nxpaths=None, nxpath_prefix=None, nxpathabs_prefix=None, nxpath_copy_abspath=None)

Function that returns a copy of a nexus object, optionally exluding certain child items.

Parameters:

• nxobject (nexusformat.nexus.NXobject) – The input nexus object to “copy”.

• exlude_nxpaths – A list of relative paths to child nexus objects that should be excluded from the returned “copy”, defaults to [].

• nxpath_prefix (str) – For use in recursive calls from inside this function only.

• nxpathabs_prefix (str) – For use in recursive calls from inside this function only.

• nxpath_copy_abspath (str) – For use in recursive calls from inside this function only.

Returns:

Copy of the input nxobject with some children optionally exluded.

Return type:

nexusformat.nexus.NXobject