MultiFitter reference documentation¶
This model provides a class for fitting multi-channel data
(MultiFitter
) and a series of predefined functions for common
models used to fit E or S histograms.
Contents
The MultiFitter class¶
- class fretbursts.mfit.MultiFitter(data_list, skip_ch=None)¶
A class handling a list of 1-D datasets for histogramming, KDE, fitting.
This class takes a list of 1-D arrays of samples (such as E values per burst). The list contains one 1-D array for each channel in a multispot experiment. In single-spot experiments the list contains only one array of samples. For each dataset in the list, this class compute histograms, KDEs and fits (both histogram fit and KDE maximum). The list of datasets is stored in the attribute
data_list
. The histograms can be fitted with an arbitrary model (lmfit.Model). From KDEs the peak position in a range can be estimated.Optionally weights can be assigned to each element in a dataset. To assign weights a user can assign the
.weights
attribute with a list of arrays; corresponding arrays in.weights
and.data_list
must have the same size.Alternatively a function returning the weights can be used. In this case, the method
.set_weights_func
allows to set the function to be called to generate weights.- calc_kde(bandwidth=0.03, calc_tot=True)¶
Compute the list of kde functions and save it in
.kde
.
- find_kde_max(x_kde, xmin=None, xmax=None, calc_tot=True)¶
Finds the peak position of kde functions between
xmin
andxmax
.Results are saved in the list
.kde_max_pos
.
- fit_histogram(model=None, pdf=True, fit_tot=True, **fit_kwargs)¶
Fit the histogram of each channel using the same lmfit model.
A list of
lmfit.Minimizer
is stored in.fit_res
. The fitted values for all the parameters and all the channels are save in a Pandas DataFrame.params
.- Parameters
model (lmfit.Model object) – lmfit Model with all the parameters already initialized used for fitting.
pdf (bool) – if True fit the normalized histogram (.hist_pdf) otherwise fit the raw counts (.hist_counts).
fit_kwargs (dict) – keyword arguments passed to
model().fit
.fit_tot (bool) – if True then fit the sum of the data as well
- histogram(binwidth=0.03, bins=None, verbose=False, **kwargs)¶
Compute the histogram of the data for each channel.
If
bins
is None,binwidth
determines the bins array (saved inself.hist_bins
). Ifbins
is not None,binwidth
is ignored andself.hist_binwidth
is computed fromself.hist_bins
.The kwargs and
bins
are passed tonumpy.histogram
.
- set_weights_func(weight_func, weight_kwargs=None)¶
Setup of the function returning the weights for each data-set.
To compute the weights for each dataset the
weight_func
is called multiple times. Keys inweight_kwargs
are arguments ofweight_func
. Values inweight_kwargs
are either scalars, in which case they are passed toweight_func
, or lists. When an argument is a list, only one element of the list is passed each time.- Parameters
weight_func (function) – function that returns the weights
weight_kwargs (dict) – keyword arguments to be passed to
weight_func
.
Model factory functions¶
In this section you find the documentation for the factory-functions that return pre-initialized models for fitting E and S data.
- fretbursts.mfit.factory_gaussian(center=0.1, sigma=0.1, amplitude=1)¶
Return an lmfit Gaussian model that can be used to fit data.
Arguments are initial values for the model parameters.
- Returns
An
lmfit.Model
object with all the parameters already initialized.
- fretbursts.mfit.factory_asym_gaussian(center=0.1, sigma1=0.1, sigma2=0.1, amplitude=1)¶
Return a lmfit Asymmetric Gaussian model that can be used to fit data.
For the definition of asymmetric Gaussian see
asym_gaussian()
. Arguments are initial values for the model parameters.- Returns
An
lmfit.Model
object with all the parameters already initialized.
- fretbursts.mfit.factory_two_gaussians(add_bridge=False, p1_center=0.1, p2_center=0.9, p1_sigma=0.03, p2_sigma=0.03)¶
Return a 2-Gaussian + (optional) bridge model that can fit data.
The optional “bridge” component (i.e. a plateau between the two peaks) is a function that is non-zero only between
p1_center
andp2_center
and is defined as:br_amplitude * (1 - g(x, p1_center, p1_sigma) - g(x, p1_center, p2_sigma))
where
g
is a gaussian function with amplitude = 1 andbr_amplitude
is the height of the plateau and the only additional parameter introduced by the bridge. Note that both centers and sigmas parameters in the bridge are the same ones of the adjacent Gaussian peaks. Therefore a 2-Gaussian + bridge model has 7 free parameters: 3 for each Gaussian and an additional one for the bridge. The bridge function is implemented inbridge_function()
.- Parameters
p1_center, p2_center (float) – initial values for the centers of the two Gaussian components.
p1_sigma, p2_sigma (float) – initial values for the sigmas of the two Gaussian components.
add_bridge (bool) – if True adds a bridge function between the two gaussian peaks. If False the model has only two Gaussians.
- Returns
An
lmfit.Model
object with all the parameters already initialized.
- fretbursts.mfit.factory_two_asym_gaussians(add_bridge=False, p1_center=0.1, p2_center=0.9, p1_sigma=0.03, p2_sigma=0.03)¶
Return a 2-Asym-Gaussians + (optional) bridge model that can fit data.
The Asym-Gaussian function is
asym_gaussian()
.- Parameters
add_bridge (bool) – if True adds a bridge function between the two gaussian peaks. If False the model has only two Asym-Gaussians.
The other arguments are initial values for the model parameters.
- Returns
An
lmfit.Model
object with all the parameters already initialized.
- fretbursts.mfit.factory_three_gaussians(p1_center=0.0, p2_center=0.5, p3_center=1, sigma=0.05)¶
Return a 3-Gaussian model that can fit data.
The other arguments are initial values for the
center
for each Gaussian component plus an singlesigma
argument that is used as initial sigma for all the Gaussians. Note that during the fitting the sigma of each Gaussian is varied independently.- Returns
An
lmfit.Model
object with all the parameters already initialized.
Utility functions¶
The following functions are utility functions used to build the the model functions (i.e. the “factory functions”) for the fitting.
- fretbursts.mfit.bridge_function(x, center1, center2, sigma1, sigma2, amplitude)¶
A “bridge” function, complementary of two gaussian peaks.
Let
g
be a Gaussian function (with amplitude = 1), the bridge function is defined as:amplitude * (1 - g(x, center1, sigma1) - g(x, center2, sigma2))
for
center1 < x < center2
. The function is 0 otherwise.- Parameters
x (array) – 1-D array for the independent variable
center1 (float) – center of the first gaussian (left side)
center2 (float) – center of the second gaussian (right side)
sigma1 (float) – sigma of the left-side gaussian
sigma2 (float) – sigma of the right-side gaussian
amplitude (float) – maximum (asymptotic) value of the bridge (plateau)
- Returns
An array (same shape as
x
) with the function values.
- fretbursts.mfit.asym_gaussian(x, center, sigma1, sigma2, amplitude)¶
A asymmetric gaussian function composed by two gaussian halves.
This function is composed from two gaussians joined at their peak, so that the left and right side decay with different sigmas.
- Parameters
x (array) – 1-D array for the independent variable
center (float) – function peak position
sigma1 (float) – sigma of the left-side gaussian (for x < center)
sigma2 (float) – sigma of the right-side gaussian (for x > center)
amplitude (float) – maximum value reach for x = center.
- Returns
An array (same shape as
x
) with the function values.