CHAP.utils package

Submodules

CHAP.utils.converters module

Functions for converting between some commonly used data formats.

convert_sparse_dense(data)

Converts between dense and sparse representations for NumPy arrays, xarray DataArrays, and xarray Datasets.

If input is a NumPy array, converts to a SciPy sparse CSR matrix.
If input is a SciPy sparse matrix, converts to a dense NumPy array.
If input is an xarray DataArray or Dataset containing sparse arrays, converts to dense.
If input is an xarray DataArray or Dataset containing dense arrays, converts to sparse.

Parameters:: data (Union[numpy.ndarray, scipy.sparse.spmatrix, xarray.DataArray, xarray.Dataset]) – The imput data.
Returns:: Converted object – sparse if input is dense, dense if input is sparse.

convert_structured_unstructured(data)

convert_xarray_nexus(data)

Convert an xarray.DataArray or xarray.Dataset into an nexusformat.nexus.NXdata or vice versa.

Parameters:: data (Union[xarray.DataArray, xarray.Dataset, nexusformat.nexus.NXdata]) – Input data.
Returns:: Conveted data.
Return type:: Union[xarray.DataArray, xarray.Dataset, nexusformat.nexus.NXdata]

CHAP.utils.fit module

File : fit.py Author : Rolf Verberg <rolfverberg AT gmail dot com> Description: General curve fitting module

class Component(model, prefix='')

Bases: object

A model fit component.

class Components

Bases: dict

The dictionary of model fit components.

add(model, prefix=''): Add a model to the model fit component dictionary.

property components: Return the model fit component dictionary.

class Fit(nxdata, config, logger)

Bases: object

Wrapper class for scipy/lmfit.

add_model(model, prefix): Add a model component to the fit model.

add_parameter(parameter): Add a fit parameter to the fit model.

property best_errors: Return errors in the best fit parameters.

property best_fit: Return the best fit.

property best_parameters: Return the best fit parameters.

property best_values: Return values of the best fit parameters.

property chisqr: Return the chisqr value of the best fit.

property components: Return the fit model components info.

property covar: Return the covarience matrix of the best fit parameters.

eval(x, result=None): Evaluate the best fit.

fit(config=None, **kwargs): Fit the model to the input data.

static guess_init_peak(x, y, *args, center_guess=None, use_max_for_center=True): Return a guess for the initial height, center and fwhm for a single peak.

property init_parameters: Return the initial parameters for the fit model.

property init_values: Return the initial values for the fit parameters.

property normalization_offset: Return the normalization_offset for the fit model.

property num_func_eval: Return the number of function evaluations for the best fit.

property parameters: Return the fit parameter info.

plot(y=None, y_title=None, title=None, result=None, skip_init=False, plot_comp=True, plot_comp_legends=False, plot_residual=False, plot_masked_data=True, **kwargs): Plot the best fit.

print_fit_report(result=None, show_correl=False): Print a fit report.

property redchi: Return the redchi value of the best fit.

property residual: Return the residual in the best fit.

property success: Return the success value for the fit.

property var_names: Return the variable names for the covarience matrix property.

property x: Return the input x-array.

property y: Return the input y-array.

class FitMap(nxdata, config, logger)

Bases: Fit

Wrapper to the Fit class to fit data on a N-dimensional map.

property best_errors: Return errors in the best fit parameters.

property best_fit: Return the best fits.

best_parameters(dims=None): Return the best fit parameters.

property best_values: Return values of the best fit parameters.

property chisqr: Return the chisqr value of each best fit.

property components: Return the fit model components info.

property covar: Return the covarience matrices of the best fit parameters.

fit(config=None, **kwargs): Fit the model to the input data.

freemem(): Free memory allocated for parallel processing.

property max_nfev: Return if the maximum number of function evaluations is reached for each fit.

property num_func_eval: Return the number of function evaluations for each best fit.

property out_of_bounds: Return the out_of_bounds value of each best fit.

plot(dims=None, y_title=None, plot_residual=False, plot_comp_legends=False, plot_masked_data=True, **kwargs): Plot the best fits.

property redchi: Return the redchi value of each best fit.

property residual: Return the residual in each best fit.

property success: Return the success value for each fit.

property var_names: Return the variable names for the covarience matrix property.

property y: Return the input y-array.

property ymap: Return the input y-array map.

class FitProcessor(*, root: Annotated[Path, PathType(path_type=dir)] | None = '/home/runner/work/ChessAnalysisPipeline/ChessAnalysisPipeline/docs', inputdir: Annotated[Path, PathType(path_type=dir)] | None = None, outputdir: Annotated[Path, PathType(path_type=dir)] | None = None, interactive: bool | None = False, log_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | None = 'INFO', logger: Logger | None = None, name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)] | None = None, schema: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)] | None = None)

Bases: Processor

A processor to perform a fit on a data set or data map.

static create_multipeak_model(model_config): Create a multipeak model.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

process(data, config=None)

Fit the data and return a CHAP.utils.fit.Fit or CHAP.utils.fit.FitMap object depending on the dimensionality of the input data. The input data should contain a NeXus NXdata object, with properly defined signal and axis.

Parameters:

data (list[PipelineData]) – Input data containing the nexusformat.nexus.NXdata object to fit.
config (dict, optional) – Fit configuration.

Raises:

ValueError – Invalid input or configuration parameter.

Returns:

The fitted data object.

Return type:

Union[CHAP.utils.fit.Fit, CHAP.utils.fit.FitMap]

class ModelResult(model, parameters, x=None, y=None, method=None, ast=None, res_par_exprs=None, res_par_indices=None, res_par_names=None, result=None)

Bases: object

The result of a model fit, mimicking the functionality of a similarly named class in the lmfit library.

eval_components(x=None, parameters=None)

Evaluate each component of a composite model function.

Parameters:

x (Union[list, np.ndarray], optional) – Independent variable, defaults to None, in which case the class variable x is used.
parameters (Parameters, optional) – Composite model parameters, defaults to None, in which case the class variable params is used.

Returns:

A dictionary with component name and evealuated function values key, value pairs.

Return type:

dict

fit_report(show_correl=False)

Generates a report of the fitting results with their best parameter values and uncertainties.

Parameters:: show_correl (bool, optional) – Whether to show list of correlations, defaults to False.

class Parameters

Bases: dict

A dictionary of FitParameter objects, mimicking the functionality of a similarly named class in the lmfit library.

add(parameter, prefix='')

Add a fit parameter.

Parameters:

parameter (Union[str, FitParameter]) – The fit parameter to add to the dictionary.
prefix (str, optional) – The prefix for the model to which this parameter belongs, defaults to ‘’.

CHAP.utils.general module

File : general.py Author : Rolf Verberg <rolfverberg AT gmail dot com> Description: A collection of general modules

all_any(l, key)

Check for a common key in a list of dictionaries, looping at maximum only once over the entire list.

Parameters:

l (list[dict]) – Input list.
key (Any) – The common dictionary key.

Returns:

1 if all(l, key), 0 if not any(l, key), or -1 otherwise. Return None for a zero length input list.

Return type:

Union[None, int]

almost_equal(a, b, sig_figs): Check if equal to within a certain number of significant digits.

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.

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.

assert_no_duplicates_in_list_of_dicts(_list, raise_error=False): Assert that there are no duplicates in a list of dictionaries.

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.
w (numpy.array, optional) – The weights (allows restart for additional ieterations).
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]

depth_list(_list): Return the depth of a list.

depth_tuple(_tuple): Return the depth of a tuple.

dictionary_update(target, source, merge_key_paths=None, sort=False)

Recursively updates a target dictionary with values from a source dictionary. Source values superseed target values for identical keys unless both values are lists of dictionaries in which case they are merged according to the merge_key_paths parameter.

Parameters:

target (collections.abc.Mapping) – Target dictionary.
source – Source dictionary.
merge_key_paths (Union[str, list[str]]) – List key paths to merge dictionary lists, only used if items in the target and source dictionary trees are lists of dictionaries.
sort (bool, optional) – Sort dictionary lists on the key.

Returns:

The updated target directory.

Return type:

collections.abc.Mapping

fig_to_iobuf(fig, fileformat=None)

Return an in-memory object as a byte stream represention of a Matplotlib figure.

Parameters:

fig (matplotlib.figure.Figure) – Matplotlib figure object.
fileformat (str, optional) – Valid Matplotlib saved figure file format, defaults to ‘png’.

Returns:

Byte stream representation of the Matplotlib figure and the associated file format.

Return type:

tuple[_io.BytesIO, str]

file_exists_and_readable(f): Check if a file exists and is readable.

get_consecutive_int_range(a): Return a list of pairs of integers marking consecutive ranges of integers.

get_trailing_int(string): Get the trailing integer in a string.

getfloat_attr(obj, attr, length=11): Format an attribute of an object for printing.

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

illegal_combination(value1, name1, value2, name2, location=None, raise_error=False, log=True): Print illegal combination message and/or raise error.

illegal_value(value, name, location=None, raise_error=False, log=True): Print illegal value message and/or raise error.

index_nearest(a, value): Return index of nearest array value.

index_nearest_down(a, value): Return index of nearest array value, rounded down.

index_nearest_up(a, value): Return index of nearest array value, rounded up.

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.

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 integers 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]

Parameters:

s (str, optional) – Interactive user prompt, defaults to None.
num_max (int, optional) – Maximum number of inputs in list.
ge (int, optional) – Minimum value of inputs in list.
le (int, optional) – Minimum value of inputs in list.
split_on_dash (bool, optional) – Allow dashes in input string, defaults to True.
remove_duplicates (bool, optional) – Removes duplicates (may also change the order), defaults to True.
sort (bool, optional) – Sort in ascending order, defaults to True.
raise_error (bool, optional) – Raise an exception upon any error, defaults to False.
log (bool, optional) – Print an error message upon any error, defaults to True.

Returns:

Input list or none upon an illegal input.

Return type:

list

input_menu(items, default=None, header=None): Interactively prompt the user to select from a menu.

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.

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]

Parameters:

s (str, optional) – Interactive user prompt.
num_max (int, optional) – Maximum number of inputs in list.
ge (float, optional) – Minimum value of inputs in list.
le (float, optional) – Minimum value of inputs in list.
remove_duplicates (bool, optional) – Removes duplicates (may also change the order), defaults to True.
sort (bool, optional) – Sort in ascending order, defaults to True.
raise_error (bool, optional) – Raise an exception upon any error, defaults to False.
log (bool, optional) – Print an error message upon any error, defaults to True.

Returns:

Input list or none upon an illegal input.

Return type:

list

input_yesno(s=None, default=None): Interactively prompt the user to enter a y/n question.

is_dict_nums(d, raise_error=False, log=True): Value is a dictionary with single number values.

is_dict_series(t_or_l, raise_error=False, log=True): Value is a tuple or list of dictionaries.

is_dict_strings(d, raise_error=False, log=True): Value is a dictionary with single string values.

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!

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!

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

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

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.

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

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

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.

is_str_or_str_series(t_or_l, raise_error=False, log=True): Value is a string ot a tuple or list of strings.

is_str_series(t_or_l, raise_error=False, log=True): Value is a tuple or list of strings.

list_dictionary_update(target, source, key=None, key_type=None, sort=False)

Recursively updates a target list of dictionaries with values from a source list of dictionaries. Each list item is updated item by item based on the key if given and equal to a key that is shared among all sets of source and target list item keys. Otherwise the target list appended to the source list is returned.

Parameters:

target (list) – Target list.
source (list) – Source list.
key (str, optional) – Selected key to merge the lists of dictionaries.
key_type (type, optional) – Key type to enforce.
sort (bool, optional) – Sort the returned list on the key.

Returns:

The updated list.

Return type:

list

list_to_string(a): Return a list of pairs of integers marking consecutive ranges of integers in string notation.

not_zero(value): Return value with a minimal absolute size of tiny, preserving the sign.

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

quick_imshow(a, title=None, row_label='row index', column_label='column index', path=None, name=None, show_fig=True, save_fig=False, return_fig=False, block=None, extent=None, show_grid=False, grid_color='w', grid_linewidth=1, **kwargs): Display and or save a 2D image and or return an in-memory object as a byte stream represention.

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.

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.

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.

round_to_n(x, n=1): Round to a specific number of sig figs.

round_up_to_n(x, n=1): Round up to a specific number of sig figs.

save_iobuf_fig(buf, filename, force_overwrite=False)

Save a byte stream represention of a Matplotlib figure to file.

Parameters:

buf (_io.BytesIO) – Byte stream representation of the Matplotlib figure.
filename (str) – Filename (with a valid extension).
force_overwrite (bool, optional) – Flag to allow filename to be overwritten if it already exists, defaults to False.

Raises:

RuntimeError – If a file already exists and force_overwrite is False.

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, return_buf=False)

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.
preselected_indices (tuple(int), list(int), optional) – Preselected image indices.
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.
min_num_indices (int, optional) – The minimum number of selected indices.
max_num_indices (int, optional) – The maximum number of selected indices.
title (str, optional) – Title for the displayed figure.
title_a (str, optional) – Title for the image of a.
title_b (str, optional) – Title for the image of b.
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.
return_buf (bool, optional) – Return an in-memory object as a byte stream represention of the Matplotlib figure instead of the matplotlib figure, defaults to False.

Returns:

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

Return type:

Union[matplotlib.figure.Figure, io.BytesIO], tuple(int, int, int, int)

select_mask_1d(y, x=None, 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, return_buf=False)

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.
preselected_index_ranges (Union(list[tuple(int, int)], list[list[int]], list[tuple(float, float)], list[list[float]]), optional) – List of preselected index ranges to mask (bounds are inclusive).
preselected_mask (numpy.ndarray, optional) – Preselected boolean mask array.
title (str, optional) – Title for the displayed figure.
xlabel (str, optional) – Label for the x-axis of the displayed figure.
ylabel (str, optional) – Label for the y-axis of the displayed figure.
min_num_index_ranges (int, optional) – The minimum number of selected index ranges.
max_num_index_ranges (int, optional) – The maximum number of selected index ranges.
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.
return_buf (bool, optional) – Return an in-memory object as a byte stream represention of the Matplotlib figure, defaults to False.

Returns:

A byte stream represention of the Matplotlib figure if return_buf is True (None otherwise), a boolean mask array, and the list of selected index ranges.

Return type:

Union[io.BytesIO, None], numpy.ndarray, list[list[int, int]]

select_roi_1d(y, x=None, preselected_roi=None, title=None, xlabel=None, ylabel=None, interactive=True, filename=None, return_buf=False)

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
preselected_roi (tuple(int, int), optional) – Preselected region of interest.
title (str, optional) – Title for the displayed figure.
xlabel (str, optional) – Label for the x-axis of the displayed figure.
ylabel (str, optional) – Label for the y-axis of the displayed figure.
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.
return_buf (bool, optional) – Return an in-memory object as a byte stream represention of the Matplotlib figure, defaults to False.

Returns:

A byte stream represention of the Matplotlib figure if return_buf is True (None otherwise), and the selected region of interest.

Return type:

Union[io.BytesIO, None], tuple(int, int)

select_roi_2d(a, preselected_roi=None, title=None, title_a=None, row_label='row index', column_label='column index', interactive=True, filename=None, return_buf=False)

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.
title (str, optional) – Title for the displayed figure.
title_a (str, optional) – Title for the image of a.
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.
return_buf (bool, optional) – Return an in-memory object as a byte stream represention of the Matplotlib figure, defaults to False.

Returns:

A byte stream represention of the Matplotlib figure if return_buf is True (None otherwise), and the selected region of interest.

Return type:

Union[io.BytesIO, None], tuple(int, int, int, int)

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]

Parameters:

s (str) – Input string.
split_on_dash (bool, optional) – Allow dashes in input string, defaults to True.
remove_duplicates (bool, optional) – Removes duplicates (may also change the order), defaults to True.
sort (bool, optional) – Sort in ascending order, defaults to True.
raise_error (bool, optional) – Raise an exception upon any error, defaults to False.

Returns:

Input list or none upon an illegal input.

Return type:

list

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

trunc_to_n(x, n=1): Truncate to a specific number of sig figs.

unwrap_tuple(_tuple): Unwrap a tuple.

CHAP.utils.material module

File : general.py Author : Rolf Verberg <rolfverberg AT gmail dot com> Description: Module defining the Material class

class Material(material_name=None, material_file=None, sgnum=None, lattice_parameters_angstroms=None, atoms=None, pos=None, enrgy=None)

Bases: object

Base class for materials in an sin2psi or EDD analysis. Right now it assumes a single material, extend its ability to do differently when test data is available.

add_material(material_name, material_file=None, sgnum=None, lattice_parameters_angstroms=None, atoms=None, pos=None, dmin_angstroms=0.6): Add a material.

ds_unique(tth_tol=None, tth_max=None, round_sig=8): Return the unique lattice spacings.

get_ds_unique(tth_tol=None, tth_max=None, round_sig=8)

Get the list of unique lattice spacings from material HKLs.

Parameters:

tth_tol (float, optional) – Two-theta tolerance (in degrees).
tth_max (float, optional) – Maximum two-theta value (in degrees).
round_sig (int, optional) – Significant digits, passed to round() function, defaults to 8.

Returns:

The list of hkl’s corresponding to the unique lattice spacings and the list of the unique lattice spacings.

Return type:

list, list

hkls_unique(tth_tol=None, tth_max=None, round_sig=8): Return the unique HKLs.

lattice_parameters(index=0): Convert from internal nm units to angstrom.

static make_material(material_name, material_file=None, sgnum=None, lattice_parameters_angstroms=None, atoms=None, pos=None, dmin_angstroms=0.6): Use HeXRD to get material properties when a materials file is provided. Use xrayutilities otherwise.

CHAP.utils.models module

Utils Pydantic model classes.

class Constant(*, model: Literal['constant'], parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], prefix: str | None = '')

Bases: CHAPBaseModel

Class representing a Constant model component.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
parameters – Function parameters, defaults to those auto generated from the function signature (excluding the independent variable), defaults to [].
prefix – The model prefix, defaults to ‘’.

model: Literal['constant']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None), FieldInfo(annotation=NoneType, required=True, validate_default=True)]

prefix: str | None

class Exponential(*, model: Literal['exponential'], parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], prefix: str | None = '')

Bases: CHAPBaseModel

Class representing an Exponential model component.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
parameters – Function parameters, defaults to those auto generated from the function signature (excluding the independent variable), defaults to [].
prefix – The model prefix, defaults to ‘’.

model: Literal['exponential']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None), FieldInfo(annotation=NoneType, required=True, validate_default=True)]

prefix: str | None

class Expression(*, model: Literal['expression'], expr: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], prefix: str | None = '')

Bases: CHAPBaseModel

Class representing an Expression model component.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
expr – Mathematical expression to represent the model component.
parameters – Function parameters, defaults to those auto generated from the model expression (excluding the independent variable), defaults to [].
prefix – The model prefix, defaults to ‘’.

expr: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)]

model: Literal['expression']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None), FieldInfo(annotation=NoneType, required=True, validate_default=True)]

prefix: str | None

class FitConfig(*, code: Literal['lmfit', 'scipy'] = 'scipy', parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], models: Annotated[list[Constant | Linear | Quadratic | Exponential | Gaussian | Lorentzian | Rectangle | Expression | Multipeak], Len(min_length=1, max_length=None)], method: Literal['leastsq', 'trf', 'dogbox', 'lm', 'least_squares'] = 'leastsq', rel_height_cutoff: Annotated[float, None, Interval(gt=0, ge=None, lt=1.0, le=None), None, AllowInfNan(allow_inf_nan=False)] | None = None, num_proc: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None] = 1, plot: Annotated[bool, Strict(strict=True)] = False, print_report: Annotated[bool, Strict(strict=True)] = False, memfolder: str = 'joblib_memmap')

Bases: CHAPBaseModel

Class representing the configuration for the fit processor.

Variables:

code – Specifies is lmfit is used to perform the fit or if the scipy fit method is called directly, default to ‘lmfit’.
parameters – Fit model parameters in addition to those implicitly defined through the build-in model functions, defaults to []’
models – The component(s) of the (composite) fit model.
rel_height_cutoff – Relative peak height cutoff for peak fitting (any peak with a height smaller than rel_height_cutoff times the maximum height of all peaks gets removed from the fit model).
num_proc – The number of processors used in fitting a map of data, defaults to 1.
plot – Weather a plot of the fit result is generated, defaults to False.
print_report – Weather to generate a fit result printout, defaults to False.

code: Literal['lmfit', 'scipy']

memfolder: str

method: Literal['leastsq', 'trf', 'dogbox', 'lm', 'least_squares']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

models: Annotated[list[Constant | Linear | Quadratic | Exponential | Gaussian | Lorentzian | Rectangle | Expression | Multipeak], Len(min_length=1, max_length=None)]

num_proc: Annotated[int, None, Interval(gt=0, ge=None, lt=None, le=None), None]

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)]

plot: Annotated[bool, Strict(strict=True)]

print_report: Annotated[bool, Strict(strict=True)]

rel_height_cutoff: Annotated[float, None, Interval(gt=0, ge=None, lt=1.0, le=None), None, AllowInfNan(allow_inf_nan=False)] | None

classmethod validate_method(method, info)

Validate the specified method.

Parameters:

method (str) – The value of method to validate.
info (pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator info object.

Returns:

Fit method.

Return type:

str

class FitParameter(*, name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)], value: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None = None, min: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, None] | None = -inf, max: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, None] | None = inf, vary: Annotated[bool, Strict(strict=True)] = True, expr: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)] | None = None)

Bases: CHAPBaseModel

Class representing a specific fit parameter for the fit processor.

property default: Return the _default attribute.

expr: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)] | None

property init_value: Return the _init_value attribute.

max: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, None] | None

min: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, None] | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

name: Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=None, pattern=None)]

property prefix: Return the _prefix attribute.

set(value=None, min=None, max=None, vary=None, expr=None)

Set or update FitParameter attributes.

Parameters:

value (float, optional) – Parameter value.
min (bool, optional) – Lower Parameter value bound. To remove the lower bound you must set min to numpy.inf.
max (bool, optional) – Upper Parameter value bound. To remove the lower bound you must set max to numpy.inf.
vary (bool, optional) – Whether the Parameter is varied during a fit.
expr (str, optional) – Mathematical expression used to constrain the value during the fit. To remove a constraint you must supply an empty string.

property stderr: Return the _stderr attribute.

classmethod validate_max(value)

Validate the specified max.

Parameters:: value (Union[float, None]) – Field value to validate (max).
Returns:: Upper bound of fit parameter.
Return type:: float

classmethod validate_min(value)

Validate the specified min.

Parameters:: value (Union[float, None]) – Field value to validate (min).
Returns:: Lower bound of fit parameter.
Return type:: float

value: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None

vary: Annotated[bool, Strict(strict=True)]

class Gaussian(*, model: Literal['gaussian'], parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], prefix: str | None = '')

Bases: CHAPBaseModel

Class representing a Gaussian model component.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
parameters – Function parameters, defaults to those auto generated from the function signature (excluding the independent variable), defaults to [].
prefix – The model prefix, defaults to ‘’.

model: Literal['gaussian']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None), FieldInfo(annotation=NoneType, required=True, validate_default=True)]

prefix: str | None

class Linear(*, model: Literal['linear'], parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], prefix: str | None = '')

Bases: CHAPBaseModel

Class representing a Linear model component.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
parameters – Function parameters, defaults to those auto generated from the function signature (excluding the independent variable), defaults to [].
prefix – The model prefix, defaults to ‘’.

model: Literal['linear']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None), FieldInfo(annotation=NoneType, required=True, validate_default=True)]

prefix: str | None

class Lorentzian(*, model: Literal['lorentzian'], parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], prefix: str | None = '')

Bases: CHAPBaseModel

Class representing a Lorentzian model component.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
parameters – Function parameters, defaults to those auto generated from the function signature (excluding the independent variable), defaults to [].
prefix – The model prefix, defaults to ‘’.

model: Literal['lorentzian']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None), FieldInfo(annotation=NoneType, required=True, validate_default=True)]

prefix: str | None

class Multipeak(*, model: Literal['multipeak'], centers: Annotated[list[Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)]], Len(min_length=1, max_length=None)], centers_range: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None = None, fit_type: Literal['uniform', 'unconstrained'] | None = 'unconstrained', fwhm_min: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None = None, fwhm_max: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None = None, peak_models: Literal['gaussian', 'lorentzian'] = 'gaussian')

Bases: CHAPBaseModel

Class representing a multipeak model.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
centers – Peak centers.
centers_range – Range of peak centers around their centers.
fit_type – Type of fit, defaults to ‘unconstrained’.
fwhm_min – Lower limit of the fwhm of the peaks.
fwhm_max – Upper limit of the fwhm of the peaks.
peak_models – Type of peaks, defaults to ‘gaussian’.

centers: Annotated[list[Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)]], Len(min_length=1, max_length=None)]

centers_range: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None

fit_type: Literal['uniform', 'unconstrained'] | None

fwhm_max: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None

fwhm_min: Annotated[float, None, Interval(gt=None, ge=None, lt=None, le=None), None, AllowInfNan(allow_inf_nan=False)] | None

model: Literal['multipeak']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

peak_models: Literal['gaussian', 'lorentzian']

class Quadratic(*, model: Literal['quadratic'], parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], prefix: str | None = '')

Bases: CHAPBaseModel

Class representing a Quadratic model component.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
parameters – Function parameters, defaults to those auto generated from the function signature (excluding the independent variable), defaults to [].
prefix – The model prefix, defaults to ‘’.

model: Literal['quadratic']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None), FieldInfo(annotation=NoneType, required=True, validate_default=True)]

prefix: str | None

class Rectangle(*, model: Literal['rectangle'], parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None)] = [], prefix: str | None = '')

Bases: CHAPBaseModel

Class representing a Rectangle model component.

Variables:

model – The model component base name (a prefix will be added if multiple identical model components are added).
parameters – Function parameters, defaults to those auto generated from the function signature (excluding the independent variable), defaults to [].
prefix – The model prefix, defaults to ‘’.

model: Literal['rectangle']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: Annotated[list[FitParameter], Len(min_length=0, max_length=None), FieldInfo(annotation=NoneType, required=True, validate_default=True)]

prefix: str | None

constant(x, c=0.0)

Return a linear function.

constant(x, c) = c

exponential(x, amplitude=1.0, decay=1.0)

Return an exponential function.

exponential(x, amplitude, decay) = amplitude * exp(-x/decay)

gaussian(x, amplitude=1.0, center=0.0, sigma=1.0)

Return a 1-dimensional Gaussian function.

gaussian(x, amplitude, center, sigma) =: (amplitude/(s2pi*sigma)) * exp(-(x-center)**2 / (2*sigma**2))

linear(x, slope=1.0, intercept=0.0)

Return a linear function.

linear(x, slope, intercept) = slope * x + intercept

lorentzian(x, amplitude=1.0, center=0.0, sigma=1.0)

Return a 1-dimensional Lorentzian function.

lorentzian(x, amplitude, center, sigma) =: (amplitude/(1 + ((1.0*x-center)/sigma)**2)) / (pi*sigma)

quadratic(x, a=0.0, b=0.0, c=0.0)

Return a parabolic function.

parabolic(x, a, b, c) = a * x**2 + b * x + c

rectangle(x, amplitude=1.0, center1=0.0, sigma1=1.0, center2=1.0, sigma2=1.0, form='linear')

Return a rectangle function.

Starts at 0.0, rises to amplitude (at center1 with width sigma1), then drops to 0.0 (at center2 with width sigma2)

Parameters:

x (float or numpy.ndarray) – Input values where the function is evaluated.
amplitude (float, optional) – Maximum height of the rectangle, defaults to 1.0.
center1 (float, optional) – Location of the rising edge, defaults to 0.0.
sigma1 (float, optional) – Width or smoothness of the rising edge, defaults to 1.0.
center2 (float, optional) – Location of the falling edge, defaults to 1.0.
sigma2 (float, optional) – Width or smoothness of the falling edge, defaults to 1.0.
form (str, optional) –
Shape type of the transition edges:
- 'linear': Simple ramp-up and ramp-down.
- 'atan' or 'arctan': Inverse tangent transitions.
- 'erf': Error function (Gaussian-like) transitions.
- 'logistic': Sigmoidal (logistic function) transitions.

Returns:

The evaluated rectangle function values.

Return type:

float or numpy.ndarray

Note

The output is calculated based on the selected form:

atan: \(\frac{A}{\pi} [ \arctan(arg_1) + \arctan(arg_2) ]\)
erf: \(\frac{1}{2} A [ \text{erf}(arg_1) + \text{erf}(arg_2) ]\)
logistic: \(A [ \frac{1}{1 + \exp(-arg_1)} + \frac{1}{1 + \exp(-arg_2)} - 1 ]\)

The function is constructed using normalized arguments for the rising and falling edges: \(arg_1 = \frac{x - center_1}{\sigma_1}\) and \(arg_2 = \frac{center_2 - x}{\sigma_2}\)

validate_parameters(parameters, info)

Validate the parameters.

Parameters:

parameters (list[FitParameter]) – Fit model parameters.
info (pydantic_core._pydantic_core.ValidationInfo) – Pydantic validator info object.

Returns:

List of fit model parameters.

Return type:

list[FitParameter]

CHAP.utils.parfile module

Utilities for interacting with scans using an SMB-style .par file as input.

class ParFile(par_file, scan_numbers=None, scann_col_name='SCAN_N')

Bases: object

Representation of a .par file.

Variables:

par_file – Name of the .par file.
json_file – Name of the .json file containing the keys for the column names of the .par file.
spec_file – Name of the SPEC data file associated with this .par file.
column_names – List of the names of each column in the par file.
data – A 2D array of the data in this .par file. 0th index: row. 1st index: column

get_map(experiment_type, station, par_dims, other_dims=None)

Return a map configuration based on this par file.

Parameters:

experiment_type (Literal['SAXSWAXS', 'EDD', 'XRF', 'TOMO']) – Experiment type name for the map that this .par file represents.
station (Literal['id1a3','id3a','id3b']) – Station name at which the data were collected.
par_dims (list[dict[str, str]]) – List of dictionaries configuring the map’s independent dimensions.
other_dims (list[dict[str,str]], optional) – List of other dimensions to include in the returned MapConfig’s independednt_dimensions. Use this if each scans in thhis par ile captured more than one frame of data. Defaults to None

Returns:

The map configuration.

Return type:

CHAP.common.models.map.MapConfig

get_values(column, scan_numbers=None)

Return values from a single column of the par file.

Parameters:

column (str or int) – The string name OR index of the column to return values for.
scan_numbers (list[int], optional) – List of specific scan numbers to return values in the given column for (instead of the default behavior: return the entire column of values).

Raise:

ValueError: Unavailable column name. TypeError: Illegal column name type.

Returns:

A list of values from a single column in the par file.

Return type:

list[object]

good_scan_numbers(good_col_name='1/0')

Return the numbers of scans marked with a “1” in the indicated “good” column of the .par file.

Parameters:: good_col_name (str, optional) – The name of the “good” column of the par file, defaults to “1/0”
Raises:: ValueError – If this .par file does not have a column with the same name as good_col_name.
Returns:: “good” scan numbers.
Return type:: list[int]

map_values(map_config, values)

Return a reshaped array of the 1D list values so that it matches up with the coordinates of map_config.

Parameters:

map_config (MapConfig) – The map configuration according to which values will be reshaped.
values (list or np.ndarray) – A 1D list of values to reshape.

Returns:

Reshaped array of values.

Return type:

np.ndarray

Module contents

This subpackage contains generic utilities for fitting, parsing CHESS scan data, collecting interactive user input, and finding lattice properties of materials (among others).