mcetl.fitting.peak_fitting¶

Functions for creating and fitting a model with peaks and a background and plotting the results.

Also contains two classes that create windows to allow selection of peak positions and background points.

@author: Donald Erb Created on Sep 14, 2019

Module Contents¶

Classes¶

`BackgroundSelector`	A window for selecting points to define the background of data.
`PeakSelector`	A window for selecting peaks on a plot, along with peak width and type.

Functions¶

`find_peak_centers`	Creates a list containing the peaks found and peaks accepted.
`fit_peaks`	Takes x,y data, finds the peaks, fits the peaks, and returns all relevant information.
`plot_confidence_intervals`	Plot the data, the fit, and the fit +- n_sig * sigma confidence intervals.
`plot_fit_results`	Plot the raw data, best fit, and residuals.
`plot_individual_peaks`	Plots each individual peak in the composite model and the total model.
`plot_peaks_for_model`	Plot the peaks found or added, as well as the ones found but rejected from the fitting.

class mcetl.fitting.peak_fitting.BackgroundSelector(x, y, click_list=None)¶

Bases: mcetl.plot_utils.EmbeddedFigure

A window for selecting points to define the background of data.

Parameters

x (array-like) -- The x-values to be plotted.
y (array-like) -- The y-values to be plotted.
click_list (list(list(float, float)), optional) -- A list of selected points (lists of x, y values) on the plot.

axis_2¶

The secondary axis on the figure which has no events.

Type: plt.Axes

Initialize self. See help(type(self)) for accurate signature.

event_loop(self)¶

Handles the event loop for the GUI.

Returns: A list of the [x, y] values for the selected points on the figure.
Return type: list(list(float, float))

class mcetl.fitting.peak_fitting.PeakSelector(x, y, click_list=None, initial_peak_width=1, subtract_background=False, background_type='PolynomialModel', background_kwargs=None, bkg_min=- np.inf, bkg_max=np.inf, default_model=None)¶

Bases: mcetl.plot_utils.EmbeddedFigure

A window for selecting peaks on a plot, along with peak width and type.

Parameters

x (array-like) -- The x-values to be plotted and fitted.
y (array-like) -- The y-values to be plotted and fitted.
click_list (list, optional) -- A nested list, with each entry corresponding to a peak. Each entry has the following layout: [[lmfit model, sigma function, aplitude function], [peak center, peak height, peak width]] where lmfit model is something like 'GaussianModel'. The first entry in the list comes directly from the mcetl.peak_fitting.peak_transformer function.
initial_peak_width (int or float) -- The initial peak width input in the plot.
subtract_background (bool) -- If True, will subtract the background before showing the plot.
background_type (str) -- String corresponding to a model in lmfit.models; used to fit the background.
background_kwargs (dict) -- Any keyword arguments needed to initialize the background model
bkg_min (float or int) -- Minimum x value to use for initially fitting the background.
bkg_max (float or int) -- Maximum x value to use for initially fitting the background.
default_model (str) -- The initial model to have selected on the plot, corresponds to a model in lmfit.models.

background¶

The y-values for the background function.

Type: array-like

Initialize self. See help(type(self)) for accurate signature.

event_loop(self)¶

Handles the event loop for the GUI.

Returns: A nested list, with each entry corresponding to a peak. Each entry has the following layout: [model, peak center, peak height, peak width] where model is something like 'Gaussian'. The first entry in the list comes directly from the mcetl.peak_fitting.peak_transformer function.
Return type: list

mcetl.fitting.peak_fitting.find_peak_centers(x, y, additional_peaks=None, height=None, prominence=np.inf, x_min=- np.inf, x_max=np.inf)¶

Creates a list containing the peaks found and peaks accepted.

Parameters

y (x,) -- x and y values for the fitting.
additional_peaks (list, optional) -- Peak centers that are input by the user and automatically accepted as peaks if within x_min and x_max.
height (int or float, optional) -- Height that a peak must have for it to be considered a peak by scipy's find_peaks.
prominence (int or float) -- Prominence that a peak must have for it to be considered a peak by scipy's find_peaks.
x_min (int or float) -- Minimum x value used in fitting the data.
x_max (int or float) -- Maximum x value used in fitting the data.

Returns

peaks_found (list) -- A list of all the peak centers found.
peaks_accepted (list) -- A list of peak centers that were accepted because they were within x_min and x_max.

Notes

Uses scipy's signal.find_peaks to find peaks matching the specifications, and adds those peaks to a list of additionally specified peaks.

mcetl.fitting.peak_fitting.fit_peaks(x, y, height=None, prominence=np.inf, center_offset=1.0, peak_width=1.0, default_model='PseudoVoigtModel', subtract_background=False, bkg_min=- np.inf, bkg_max=np.inf, min_sigma=0.0, max_sigma=np.inf, min_method='least_squares', x_min=- np.inf, x_max=np.inf, additional_peaks=None, model_list=None, background_type='PolynomialModel', background_kwargs=None, fit_kws=None, vary_voigt=False, fit_residuals=False, num_resid_fits=5, min_resid=0.05, debug=False, peak_heights=None)¶

Takes x,y data, finds the peaks, fits the peaks, and returns all relevant information.

Parameters

y (x,) -- x and y values for the fitting.
height (int or float) -- Height that a peak must have for it to be considered a peak by scipy's find_peaks.
prominence (int or float) -- Prominence that a peak must have for it to be considered a peak by scipy's find_peaks.
center_offset (int or float) -- Value that determines the min and max parameters for the center of each peak. min = center - center_offset, max = center + center_offset.
peak_width (int or float) -- A guess at the full-width-half-max of the peaks. When first estimating the peak parameters, only the data from x - peak_width / 2 to x + peak_width / 2 is used to fit the peak.
default_model (str) -- Model used if the model_list is None or does not have enough values for the number of peaks found. Must correspond to one of the built-in models in lmfit.models.
subtract_background (bool) -- If True, it will fit the background with the model in background_type.
bkg_min (int or float) -- Minimum x value to use for initially fitting the background.
bkg_max (int or float) -- Maximum x value to use for initially fitting the background.
min_sigma (int or float) -- Minimum value for the sigma for each peak; typically better to not set to any value other than 0.
max_sigma (int or float) -- maximum value for the sigma for each peak; typically better to not set to any value other than infinity.
min_method (str) -- Minimization method used for fitting.
x_min (int or float) -- Minimum x value used in fitting the data.
x_max (int or float) -- Maximum x value used in fitting the data.
additional_peaks (list) -- Peak centers that are input by the user and automatically accepted as peaks.
model_list (list) -- List of strings, with each string corresponding to one of the models in lmfit.models.
background_type (str) -- String corresponding to a model in lmfit.models; used to fit the background.
background_kwargs (dict, optional) -- Any keyword arguments needed to initialize the background model.
fit_kws (dict) -- Keywords to be passed on to the minimizer.
vary_voigt (bool) -- If True, will allow the gamma parameter in the Voigt model to be varied as an additional variable; if False, gamma will be set equal to sigma.
fit_residuals (bool) -- If True, it will attempt to fit the residuals after the first fitting to find hidden peaks, add them to the model, and fit the data again.
num_resid_fits (int) -- Maximum number of times the program will loop to fit the residuals.
min_resid (int or float) -- used as the prominence when finding peaks in the residuals, in which the prominence is set to min_resid * (y_max - y_min).
debug (bool) -- If True, will create plots at various portions of the code showing the peak initialization, initial fits and backgrounds, and residuals.
peak_heights (list) -- A list of peak heights.

Returns

output -- A dictionary of lists. For most lists, each entry corresponds to the results of a peak fitting. The dictionary has the following keys (in this order if unpacked into a list):

'resid_peaks_found':
All peak centers found during fitting of the residuals. Each list entry corresponds to a separate fitting.

'resid_peaks_accepted':
Peak centers found during fitting of the residuals which were accepted as true peak centers. Each list entry corresponds to a separate fitting.

'peaks_found':
All peak centers found during the initial peak fitting of the original data.

'peaks_accepted':
Peaks centers found during the initial peak fitting of the original data which were accepted as true peak centers

'initial_fits':
List of initial fits. Each list entry corresponds to a separate fitting.

'fit_results':
List of lmfit's ModelResult objects, which contain the majority of information needed. Each list entry corresponds to a separate fitting.

'individual_peaks':
Nested list of y-data values for each peak. Each list entry corresponds to a separate fitting.

'best_values:
Nested list of best fit parameters (such as amplitude, fwhm, etc.) for each fitting. Each list entry corresponds to a separate fitting.

Return type

dict

Notes

Uses several of the functions within this module to directly take (x,y) data and do peak fitting. All relevant data is returned from this function, so it has quite a dense input and output, but it is well worth it!

For the minimization method (min_method), the 'least_squares' method gives fast performance compared to most other methods while still having good convergence. The 'leastsq' is also very good, and seems less succeptible to getting caught in local minima compared to 'least_squares', but takes longer to evaluate. A best practice could be to use 'least_squares' during initial testing and then using 'leastsq' for final calculations.

Global optimizers do not seem to work on complicated models (or rather I cannot get them to work), so using the local optimizers 'least_squares' or 'leastsq' and adjusting the inputs will have to suffice.

Most relevant data is contained within output['fit_results'], such as the parameters for each peak, as well as all the error associated with the fitting.

Within this function:

params == parameters for all of the peaks bkg_params == parameters for the background composite_params == parameters for peaks + background

model == CompositeModel object for all of the peaks background == Model object for the background composite_model == CompositeModel object for the peaks + background

peaks_accepted are not necessarily the peak centers after fitting, just the peak centers that were found. These values can be used for understanding the peak selection process.

mcetl.fitting.peak_fitting.plot_confidence_intervals(fit_result, n_sig=3, return_figure=False)¶

Plot the data, the fit, and the fit +- n_sig * sigma confidence intervals.

Parameters

fit_result (lmfit.ModelResult) -- The ModelResult object for the fitting.
n_sig (float, optional) -- The multiple of the standard error to use as the plotted error. The default is 3.
return_figure (bool, optional) -- If True, will return the created figure; otherwise, it will display the figure using plt.show(block=False) (default).

Returns

If return_figure is True, the figure is returned; otherwise, None is returned.

Return type

plt.Figure or None

Notes

This function assumes that the independant variable in the fit_result was labeled 'x', as is standard for all built-in lmfit models.

mcetl.fitting.peak_fitting.plot_fit_results(fit_result, label_rsq=False, plot_initial=False, return_figure=False)¶

Plot the raw data, best fit, and residuals.

Parameters

fit_result (lmfit.ModelResult or list(lmfit.ModelResult)) -- A ModelResult object from lmfit; can be a list of ModelResults, in which case, the initial fit will use fit_result[0], and the best fit will use fit_result[-1].
label_rsq (bool, optional) -- If True, will put a label with the adjusted r squared value of the fitting.
plot_initial (bool, optional) -- If True, will plot the initial fitting as well as the best fit.
return_figure (bool, optional) -- If True, will return the created figure; otherwise, it will display the figure using plt.show(block=False) (default).

Returns

If return_figure is True, the figure is returned; otherwise, None is returned.

Return type

plt.Figure or None

Notes

This function assumes that the independant variable in the fit_result was labeled 'x', as is standard for all built-in lmfit models.

mcetl.fitting.peak_fitting.plot_individual_peaks(fit_result, individual_peaks, background_subtracted=False, plot_subtract_background=False, plot_separate_background=False, plot_w_background=False, return_figures=False)¶

Plots each individual peak in the composite model and the total model.

Parameters

fit_result (lmfit.ModelResult) -- The ModelResult object from the fitting.
individual_peaks (dict) -- A dictionary with keys corresponding to the model prefixes in the fitting, and their values corresponding to their y values.
background_subtracted (bool) -- Whether or not the background was subtracted in the fitting.
plot_subtract_background (bool) -- If True, subtracts the background from the raw data as well as all the peaks, so everything is nearly flat.
plot_separate_background (bool) -- If True, subtracts the background from just the individual peaks, while also showing the raw data with the composite model and background.
plot_w_background (bool) -- If True, has the background added to all peaks, i.e. it shows exactly how the composite model fits the raw data.
return_figures (bool, optional) -- If True, will return the created figures; otherwise, it will display the figures using plt.show(block=False) (default).

Returns

If return_figures is True, the list of created figures is returned. Otherwise, None is returned.

Return type

list(plt.Figure) or None

Notes

This function assumes that the independant variable in the fit_result was labeled 'x', as is standard for all built-in lmfit models.

mcetl.fitting.peak_fitting.plot_peaks_for_model(x, y, x_min, x_max, peaks_found, peaks_accepted, additional_peaks)¶

Plot the peaks found or added, as well as the ones found but rejected from the fitting.

Parameters

x (array-like) -- x data used in the fitting.
y (array-like) -- y data used in the fitting.
x_min (float or int) -- Minimum x values used for the fitting procedure.
x_max (float or int) -- Maximum x values used for the fitting procedure.
peaks_found (list) -- A list of x values corresponding to all peaks found throughout the peak fitting and peak finding process, as well as those input by the user.
peaks_accepted (list) -- A list of x values corresponding to peaks found throughout the peak fitting and peak finding process that were accepted into the model.
additional_peaks (list) -- A list of peak centers that were input by the user.