mcetl.fitting.fitting_utils¶

Provides utility functions, classes, and constants for the fitting module.

Useful functions are put here in order to prevent circular importing within the other files.

@author : Donald Erb Created on Nov 18, 2020

Notes

The functions get_model_name, get_model_object, and get_gui_name are to be used, rather than referring to the constants _TOTAL_MODELS and _GUI_MODELS because the implementation of these constants may change in the future while the output of the functions can be kept constant.

Module Contents¶

Functions¶

`get_gui_name`	Returns the name used in GUIs for the input model, eg. 'GaussianModel' -> 'Gaussian'.
`get_is_peak`	Determines if the input model is registered as a peak function.
`get_model_name`	Converts the model name used in GUIs to the model class name.
`get_model_object`	Returns the model object given a model name, eg. 'Gaussian' -> lmfit.models.GaussianModel.
`numerical_area`	Computes the numerical area of a peak using the trapezoidal method.
`numerical_extremum`	Computes the numerical maximum or minimum for a peak.
`numerical_fwhm`	Computes the numerical full-width-at-half-maximum of a peak.
`numerical_mode`	Computes the numerical mode (x-value at which the extremum occurs) of a peak.
`print_available_models`	Prints out a dictionary of all models supported by mcetl.
`r_squared`	Calculates r^2 and adjusted r^2 for a fit.
`r_squared_model_result`	Calculates r^2 and adjusted r^2 for a fit, given an lmfit.ModelResult.
`subtract_linear_background`	Returns y-values after subtracting a linear background constructed from points.

mcetl.fitting.fitting_utils.get_gui_name(model)¶

Returns the name used in GUIs for the input model, eg. 'GaussianModel' -> 'Gaussian'.

Parameters: model (str) -- The input model string.
Returns: The model's name as it appears in GUIs.
Return type: str

Notes

This is a convenience function to be used so that the internals of how model names are specified can change while code can always use this function.

mcetl.fitting.fitting_utils.get_is_peak(model)¶

Determines if the input model is registered as a peak function.

Parameters: model (str) -- The name of the model. Can either be the GUI name (eg. 'Gaussian') or the class name (eg. 'GaussianModel').
Returns: is_peak -- True if the input model is within _TOTAL_MODELS and _TOTAL_MODELS[model]['is_peak'] is True. If the model cannot be found, or if _TOTAL_MODELS[model]['is_peak'] is False, then returns False.
Return type: bool

mcetl.fitting.fitting_utils.get_model_name(model)¶

Converts the model name used in GUIs to the model class name.

For example, converts 'Gaussian' to 'GaussianModel' and 'Skewed Gaussian' to 'SkewedGaussianModel'.

Useful so that code can always refer to the original model name and not be affected if the name of the model used in GUIs changes. Also ensures that user-input model names are correctly interpreted.

Parameters: model (str) -- The model name used within a GUI or input by a user.
Returns: output -- The class name of the model, which can give other information by using _TOTAL_MODELS[output].
Return type: str
Raises: KeyError: -- Raised if the input model name is not valid.

mcetl.fitting.fitting_utils.get_model_object(model)¶

Returns the model object given a model name, eg. 'Gaussian' -> lmfit.models.GaussianModel.

Parameters: model (str) -- The name of the model desired. Can either be the model class name, such as 'GaussianModel', or the name used in GUIs, such as 'Gaussian.
Returns: output -- The class corresponding to the input model name.
Return type: lmfit.Model

mcetl.fitting.fitting_utils.numerical_area(x, y)¶

Computes the numerical area of a peak using the trapezoidal method.

Parameters

x (array-like) -- The x-values for the peak model.
y (array-like) -- The y-values for the peak model.

Returns

The integrated area of the peak, using the trapezoidal method.

Return type

float

mcetl.fitting.fitting_utils.numerical_extremum(y)¶

Computes the numerical maximum or minimum for a peak.

Parameters: y (array-like) -- The y-values for the peak model.
Returns: extremum -- The extremum with the highest absolute value from the input y data. Assumes the peak is negative if abs(min(y)) > abs(max(y)).
Return type: float

Notes

Use np.nanmin and np.nanmax instead of min and max in order to convert the output to a numpy dtype. This way, all of the numerical calculations using the output of this function will work, even if y is a list or tuple.

mcetl.fitting.fitting_utils.numerical_fwhm(x, y)¶

Computes the numerical full-width-at-half-maximum of a peak.

Parameters

x (array-like) -- The x-values for the peak model.
y (array-like) -- The y-values for the peak model.

Returns

The calculated full-width-at-half-max of the peak. If there are not at least two x-values at which y = extremum_y / 2, then None is returned.

Return type

float or None

Notes

First finds the x-values where y - extremum_y / 2 changes signs, and then uses linear interpolation to approximate the x-values at which y - extremum_y / 2 = 0

mcetl.fitting.fitting_utils.numerical_mode(x, y)¶

Computes the numerical mode (x-value at which the extremum occurs) of a peak.

Parameters

x (array-like) -- The x-values for the peak model.
y (array-like) -- The y-values for the peak model.

Returns

The x-value at which the extremum in y occurs.

Return type

float

mcetl.fitting.fitting_utils.print_available_models()¶

Prints out a dictionary of all models supported by mcetl.

Also prints out details for each model, including its class, the name used when displaying in GUIs, its parameters, and whether it is considered a peak function.

mcetl.fitting.fitting_utils.r_squared(y_data, y_fit, num_variables=1)¶

Calculates r^2 and adjusted r^2 for a fit.

Parameters

y_data (array-like) -- The experimental y data.
y_fit (array-like) -- The calculated y from fitting.
num_variables (int, optional) -- The number of variables used by the fitting model.

Returns

r_sq (float) -- The r squared value for the fitting.
r_sq_adj (float) -- The adjusted r squared value for the fitting, which takes into account the number of variables in the fitting model.

mcetl.fitting.fitting_utils.r_squared_model_result(fit_result)¶

Calculates r^2 and adjusted r^2 for a fit, given an lmfit.ModelResult.

Parameters: fit_result (lmfit.ModelResult) -- The ModelResult object from a fit.
Returns: The r^2 and adjusted r^2 values for the fitting.
Return type: tuple(float, float)

mcetl.fitting.fitting_utils.subtract_linear_background(x, y, background_points)¶

Returns y-values after subtracting a linear background constructed from points.

Parameters

x (array-like) -- The x-values of the data.
y (array-like) -- The y-values of the data.
background_points (list(list(float, float))) -- A list containing the [x, y] values for each point representing the background.

Returns

y_subtracted -- The input y-values, after subtracting the background.

Return type

np.ndarray

Notes

Assumes the background is represented by lines connecting each of the specified background points.