tcspcfit

Module for fitting TCSPC data.

The function distfluofit is based on MATLAB code by Jörg Enderlein: https://www.uni-goettingen.de/en/513325.html

Bertus van Heerden and Joshua Botha, University of Pretoria

Module Contents

Classes

FluoFit	Base class for fit of a multi-exponential decay curve.
OneExp	Single exponential fit.
TwoExp	Double exponential fit.
ThreeExp	Triple exponential fit.
FittingParameters	This class encapsulates lifetime fitting parameters.
FittingDialog	Class for dialog that is used to choose lifetime fit parameters.

Functions

moving_avg(→ numpy.ndarray)	Moving average filter.
max_continuous_zeros(→ int)	Find the maximum number of continuous zeros in data.
makerow(vector)	Reshape 1D vector into a 2D row
colorshift(irf, shift)	Shift irf left or right 'periodically'.
minfunc(p0, fitfunc, t, measured)
ml_curve_fit(fitfunc, t, measured, bounds, p0[, ...])

Attributes

__docformat__
logger
fitting_dialog_file
BACKGROUND_SECTION_LENGTH

tcspcfit.__docformat__ = "'NumPy'"

tcspcfit.logger = "'tcspcfit'"

tcspcfit.fitting_dialog_file

tcspcfit.BACKGROUND_SECTION_LENGTH = '50'

tcspcfit.moving_avg(vector: list | numpy.ndarray, window_length: int, pad_same_size: bool = True) → numpy.ndarray

Moving average filter.

This function is used to smooth the decay histgram before determining a suitable fitting endpoint.

Parameters:

• vector (1D ndarray) – data moving average is to be applied to

• window_length (int) – moving average window size in number of datapoints

• pad_same_size (bool, default True) – whether to pad the data with zeros before calculating moving average

Returns:

new_vector – filtered data

Return type:

1D ndarray

tcspcfit.max_continuous_zeros(vector: numpy.ndarray) → int

Find the maximum number of continuous zeros in data.

Used by FluoFit.estimate_bg, this function finds the maximum number of consecutive zeros in the input data.

Parameters:

vector (1D ndarray) – input data

Returns:

maxzeros – maximum number of consecutive zeros

Return type:

int

tcspcfit.makerow(vector)

Reshape 1D vector into a 2D row

tcspcfit.colorshift(irf, shift)

Shift irf left or right ‘periodically’.

A shift past the start or end results in those values of irf ‘wrapping around’.

Parameters:

• irf (row vector or 1D) – data to be shifted

• shift (float) – amount to be shifted in number of channels

Returns:

irs – shifted irf, as row vector

Return type:

ndarray

tcspcfit.minfunc(p0, fitfunc, t, measured)

tcspcfit.ml_curve_fit(fitfunc, t, measured, bounds, p0, constraints=None)

class tcspcfit.FluoFit(irf, measured, t, channelwidth, tau=None, amp=None, shift=None, bg=None, irfbg=None, boundaries=None, ploton=False, fwhm=None, method='ls', normalize_amps=True, numexp=None)

Base class for fit of a multi-exponential decay curve.

This class is only used for subclassing.

Parameters:

• irf (ndarray) – Instrumental Response Function

• measured (ndarray) – The measured decay data

• channelwidth (float) – Time width of one TCSPC channel (in nanoseconds)

• tau (array_like, optional) – Initial guess times (in ns). This is either in the format [tau1, tau2, …] or [[tau1, min1, max1, fix1], [tau2, …], …]. When the “fix” value is False, the min and max values are ignored.

• amp (array_like, optional) – Initial guess amplitude. Format [amp1, amp2, …] or [[amp1, fix1], [amp2, fix2], …]

• shift (array_like, optional) – Initial guess IRF shift. Either a float, or [shift, min, max, fix].

• bg (float) – Background value for decay. Will be estimated if not given.

• irfbg (float) – Background value for IRF. Will be estimated if not given.

• boundaries (list) – Start and end of fitting range as well as options for automatic determination of the parameters as used by calculate_boundaries.

• ploton (bool) – Whether to automatically plot the irf_data.

• fwhm (float = None) – Full-width at half maximum of simulated irf. IRF is not simulated if fwhm is None.

• normalize_amps (bool = True) – Whether to use normalized lifetime amplitudes.

• method (str = 'ls') – Method for fitting - ‘ls’ for least-squares or ‘ml’ for maximum likelihood.

• numexp (int, optional) – Number of exponential components in fit.

numexp = 'None'

normalize_amps = 'True'

channelwidth

ploton = 'False'

t

method = "'ls'"

tau = '[]'

taumin = '[]'

taumax = '[]'

amp = '[]'

ampmin = '[]'

ampmax = '[]'

shift = 'None'

shiftmin = 'None'

shiftmax = 'None'

fwhm = 'None'

fwhmmin = 'None'

fwhmmax = 'None'

stds = '[]'

settings

bg = 'None'

irfbg = 'None'

startpoint = 'None'

endpoint = 'None'

meas_bef_bg

measured_unbounded

measured_not_normalized

meas_sum

bg_n = 'None'

meas_std = 'None'

dtau = 'None'

chisq = 'None'

residuals = 'None'

dw = 'None'

dw_bound = 'None'

convd = 'None'

is_fit = 'False'

load_settings()

Load configuration from settings.json file.

static calculate_boundaries(measured, boundaries, bg, settings, channel_width, fitmethod='ls')

Set the start and endpoints.

Sets the values to the given ones or automatically find good ones. The start value is chosen as earliest point that is at least 80% of the maximum point of the measured decay, and the end value is chosen as either the point where the decay is 1 % of maximum or 20 times the background value, whichever is highest. These values can be modified in the settings dialog.

Parameters:

• measured (ndarray) – The measured decay data.

• boundaries (list) – [startpoint, endpoint, autostart, autoend].

• bg (float) – Calculated decay background.

• settings (settings_dialog.Settings() object) – Contains config settings.

• channel_width (float) – Duration of a single channel.

• fitmethod (string) – Fitting method for lifetime fit - ‘ls’ for least squares or ‘ml’ for maximum likelihood.

calculate_bg(bg, irf, irf_bg, measured)

Calculate decay and IRF background values

If not given, the background value is estimated from the first part of the curve, before the rise.

Parameters:

• bg (float) – Decay background value

• irf (ndarray) – Instrument response function

• irfbg (float) – IRF background value

• measured (ndarray) – Measured decay data

static estimate_bg(measured, return_bglim=False, settings=None)

Estimate decay background

Optionally returns only the index of rise start.

Parameters:

• measured (ndarray) – measured decay data

• return_bglim (bool) – whether to return index of rise start instead of bg

• settings (settings_dialog.Settings() object) – Contains config settings

setup_params(amp, shift, tau, fwhm=None, bg=None)

Setup fitting parameters.

This method handles the input of initial parameters for fitting. The input system is flexible, allowing optional input of min and max values as well as choosing to fix a value.

Parameters:

• amp (list or float) – Amplitude(s)

• shift (list or float) – IRF colour shift

• tau (list or float) – Lifetime(s)

• fwhm (list or float) – simulated IRF fwhm

static df_len(test_obj) → int

Find the ‘length’ of an object

Returns len(obj) if possible, else returns 1 iff obj is not None

results(tau, stds, avtaustd, shift, amp=1, fwhm=None, bg=None)

Handle results after fitting

After fitting, the results are processed. Chi-squared is calculated and optional plotting is done.

Parameters:

• tau (ndarray or float) – Fitted lifetime(s)

• dtau (ndarray or float) – Error in fitted lifetimes

• shift (float) – Fitted colourshift value

• amp (ndarray or float) – Fitted amplitude(s)

makeconvd(shift, model, fwhm=None, bg=0)

Makes a convolved decay using IRF and exponential model

The IRF is either self.irf or, if fwhm is provided, a simulated Gaussian.

Parameters:

• shift (float) – IRF colour shift

• model (ndarray) – Exponential model function

Returns:

convd – convolution of model with shifted IRF

Return type:

1D ndarray

static sim_irf(channelwidth, fwhm, measured)

Return a simulated Gaussian IRF.

The IRF is shifted and scaled to have its peak lined up with the peak of the provided measured data.

Parameters:

• channelwidth (float) – TCSPC channelwidth in ns

• fwhm (float) – full width at half maximum of Gaussian IRF

• measured (1D ndarray) – measured decay function

Returns:

• irf (1D ndarray) – simulated IRF

• irft (1D ndarray) – time axis for IRF

durbinwatson()

Calculates Durbin-Watson lower bound.

Based on Turner 2020 https://doi.org/10.1080/13504851.2019.1691711 We use 0.1%, 0.3%, 1% or 5% critical bound for lower bound d_L of DW parameter.

class tcspcfit.OneExp(irf, measured, t, channelwidth, tau=None, amp=None, shift=None, bg=None, irfbg=None, boundaries=None, addopt=None, ploton=False, fwhm=None, method='ls')

Bases: FluoFit

Single exponential fit.

Takes exact same arguments as FluoFit with the addition of addopt.

Parameters:

addopt (Dict = None) – Additional options for curve_fit.

fitfunc_ls(t, tau1, a, shift, fwhm=None)

Single exponential model function passed to curve_fit, to be fitted to data.

fitfunc_ml(t, tau1, shift, bg, fwhm=None)

Single exponential model function passed to curve_fit, to be fitted to data.

class tcspcfit.TwoExp(irf, measured, t, channelwidth, tau=None, amp=None, shift=None, bg=None, irfbg=None, boundaries=None, addopt=None, ploton=False, fwhm=None, normalize_amps=True, method='ls')

Bases: FluoFit

Double exponential fit.

Takes exact same arguments as FluoFit with the addition of addopt.

Parameters:

addopt (Dict = None) – Additional options for curve_fit.

fitfunc_ls(t, tau1, tau2, a1, a2, shift, fwhm=None)

Double exponential model function passed to curve_fit, to be fitted to data.

fitfunc_ml(t, tau1, tau2, a1, shift, bg, fwhm=None)

Double exponential model function passed to curve_fit, to be fitted to data.

class tcspcfit.ThreeExp(irf, measured, t, channelwidth, tau=None, amp=None, shift=None, bg=None, irfbg=None, boundaries=None, addopt=None, ploton=False, fwhm=None, normalize_amps=True, method='ls')

Bases: FluoFit

Triple exponential fit.

Takes exact same arguments as FluoFit with the addition of addopt.

Parameters:

addopt (Dict = None) – Additional options for curve_fit.

fitfunc_ls(t, tau1, tau2, tau3, a1, a2, a3, shift, fwhm=None)

Triple exponential model function passed to curve_fit, to be fitted to data

fitfunc_ml(t, tau1, tau2, tau3, a1, a2, shift, bg, fwhm=None)

Triple exponential model function passed to curve_fit, to be fitted to data

class tcspcfit.FittingParameters(parent: controllers.LifetimeController)

This class encapsulates lifetime fitting parameters.

An instance of the class is created by LifetimeController to get the fitting parameters from the FittingDialog and a copy of this instance is passed to the fitting thread.

Parameters:

parent (controllers.LifetimeController) – the parent object

parent

fpd

irf = 'None'

tau = 'None'

amp = 'None'

shift = 'None'

decaybg = 'None'

irfbg = 'None'

start = 'None'

autostart = "'Manual'"

end = 'None'

autoend = 'False'

numexp = 'None'

addopt = 'None'

fwhm = 'None'

normalize_amps = 'True'

maximum_likelihood = 'False'

getfromdialog()

get_from_gui(guiobj)

Get cleaned-up values from gui

This function checks the validity of gui values in the fitting dialog and returns them to getfromdialog.

class tcspcfit.FittingDialog(mainwindow, lifetime_controller)

Bases: PyQt5.QtWidgets.QDialog, UI_Fitting_Dialog

Class for dialog that is used to choose lifetime fit parameters.

Parameters:

• mainwindow (main.MainWindow) – the current mainwindow instance

• lifetime_controller (controllers.LifetimeController) – the parent of this object

mainwindow

lifetime_controller

settings

tau_edits

tau_min_edits

tau_max_edits

amp_edits

amp_min_edits

amp_max_edits

bg_edits

time_edits

irf_shift_edits

_reg_exp_validator

load_settings()

Load configuration from settings.json file.

enable_sim_vals(enable)

Called to enable the IRF simulation parameter input widgets.

disable_amps(disable)

Called to enable the secondary amplitudes when not normalized.

updateplot(*args)

Update the plot using the current input values.

getparams()

Return fit parameters from FittingParameters object.

make_model()

Return multi-exponential model based on fitting parameters.