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.

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 and xmax.

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 in self.hist_bins). If bins is not None, binwidth is ignored and self.hist_binwidth is computed from self.hist_bins.

The kwargs and bins are passed to numpy.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 in weight_kwargs are arguments of weight_func. Values in weight_kwargs are either scalars, in which case they are passed to weight_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 and p2_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 and br_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 in bridge_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 single sigma 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.