FRETBursts plugins¶

The module burtlib_ext.py (by default imported as bext) contains extensions to burstslib.py. It can be though as a simple plugin system for FRETBursts.

Functions here defined operate on fretbursts.burstlib.Data() objects extending the functionality beyond the core functions and methods defined in burstlib. This modularization allows to implement new functions without overloading the fretbursts.burstlib.Data with an high number of non-core methods.

The type of functions here implemented are quite diverse. A short summary follows.

burst_search_and_gate() performs the AND-gate burst search taking intersection of the bursts detected in two photons streams.
burst_data() returns a pandas DataFrame with burst data (one burst per row). Burst data includes sizes, duration, E, S, etc….
burst_photons() returns a pandas DataFrame with photon data such as timestamps or nanotimes inside bursts (one photon per row).
bursts_fitter() and fit_bursts_kde_peak() help to build and fit histograms and KDEs for E or S.
calc_mdelays_hist() computes the histogram of the m-delays distribution of photon intervals.
moving_window_chunks(): slices the measurement using a moving-window (along the time axis). Used to follow or detect kinetics.
join_data() joins different measurements to create a single “virtual” measurement from a series of measurements.

Finally a few functions deal with burst timestamps:

ph_burst_stats() compute any statistics (for example mean or median) on the timestamps of each burst.
asymmetry() returns a burst “asymmetry index” based on the difference between Donor and Acceptor timestamps.

fretbursts.burstlib_ext.asymmetry(dx, ich=0, func=<function mean>, dropnan=True)¶

Compute an asymmetry index for each burst in channel ich.

It computes each burst the difference func({t_D}) - func({t_A}) where func is a function (default mean) that computes some statistics on the timestamp and {t_D} and {t_A} are the sets of D or A timestamps in a bursts (during D excitation).

Parameters:

d (Data) – Data() object
ich (int) – channel index
func (function) – the function to be used to extract D and A photon statistics in each bursts.

Returns:

An arrays of photon timestamps (one array per burst).

fretbursts.burstlib_ext.burst_data(dx, include_bg=False, include_ph_index=False, skip_ch=None)¶

Return a table (pd.DataFrame) of burst data (one row per burst).

Columns include:

E and S: FRET and stoichiometry for each burst.
nd, na, naa, nda: burst counts in DexDem, DexAem, AexAem and AexDem photon streams.
t_start, t_stop: time (in seconds) of first and last photon inside the burst
width_ms: burst duration in milliseconds
size_raw: the total uncorrected burst counts in the photon stream used for burst search

Optional columns include:

i_start, i_stop: index of burst start and stop relative to the original timestamps array (requires include_ph_index=True)
bg_dd, bg_ad, bg_aa, bg_da: background contribution in the DexDem, DexAem, AexAem, AexDem photon streams (requires include_bg=True).

If the peak photon-counts in each bursts has been computed (see fretbursts.burstlib.Data.calc_max_rate()), it will be included as a column called max_rate.

Parameters:

include_bg (bool) – if True includes additional columns for burst background (see above). Default False.
include_ph_index (bool) – if True includes additional two columns for index of first and last timestamp in each burst. Default False.
skip_ch (list or None) – List of channels to skip if measurement is multispot.

Returns:

A pandas’s DataFrame containing burst data (one row per burst).

fretbursts.burstlib_ext.burst_data_period_mean(dx, burst_data)¶

Compute mean burst_data in each period.

Parameters:

dx (Data object) – contains the burst data to process
burst_data (list of arrays) – one array per channel, each array has one element of “burst data” per burst.

Returns:

2D of arrays with shape (nch, nperiods).

Example

burst_period_mean(dx, dx.nt)

fretbursts.burstlib_ext.burst_photons(dx, skip_ch=None)¶

Return a pandas.DataFrame of photon-data for bursts in dx.

The returned DataFrame has one row per “photon”. Columns include:

timestamp: the timestamp of each photon
nantotime: the TCSPC nanotime of each photon (if available)
stream: a categorical column indicating the stream of each photon.
spot: (multispot only) the spot number for each photon

The returned DataFrame has a hierarchical index made of two integers: (burst_id, photon_id). burst_id identifies the burst while photon_id identifies each photon in a burst. burst_id is the same number used as index in the DataFrame returned by burst_data(). photon_id always starts at 0 for the first photon in each burst.

Parameters:

dx (Data) – the Data object containing the measurement
skip_ch (list or None) – List of channels to skip if measurement is multispot. Default None

Returns:

A pandas’s DataFrame containing the photon data for the bursts in dx. The DataFrame has one row per photon.

fretbursts.burstlib_ext.burst_search_and_gate(dx, F=6, m=10, min_rate_cps=None, c=-1, ph_sel1=('DAem', None), ph_sel2=(None, 'Aem'), compact=False, mute=False)¶

Return a Data object containing bursts obtained by and-gate burst-search.

The and-gate burst search is a composition of 2 burst searches performed on different photon selections. The bursts in the and-gate burst search are the overlapping bursts in the 2 initial burst searches, and their duration is the intersection of the two overlapping bursts.

By default the 2 photon selections are D+A photons during D excitation (Ph_sel(Dex='DAem')) and A photons during A excitation (Ph_sel(Aex='Aex')).

Parameters:

dx (Data object) – contains the data on which to perform the burst search. Background estimation must be performed before the search.
F (float or tuple) – burst search parameter F. If it is a 2-element tuple, specifies F separately for ph_sel1 and ph_sel2.
m (int or tuple) – Burst search parameter m. If it is a 2-element tuple, specifies m separately for ph_sel1 and ph_sel2.
min_rate_cps (float or tuple) – min. rate in cps for burst detection. If not None, min_rate_cps overrides any value passed in F. If a 2-element tuple specifies min_rate_cps separately for ph_sel1 and ph_sel2. In multispot data, it can also be an array (or a 2-tuple or arrays) with size equal to the number of spots.
c (float) – parameter used set the definition of the rate estimatator. See c parameter in burstlib.Data.burst_search() for details.
ph_sel1 (Ph_sel object) – photon selections used for bursts search 1.
ph_sel2 (Ph_sel object) – photon selections used for bursts search 2.
mute (bool) – if True nothing is printed. Default: False.

Returns:

A new Data object containing bursts from the and-gate search.

fretbursts.burstlib_ext.bursts_fitter(dx, burst_data='E', save_fitter=True, weights=None, gamma=1, add_naa=False, skip_ch=None, binwidth=None, bandwidth=None, model=None, verbose=False, fit_tot=True)¶

Create a mfit.MultiFitter object (for E or S) add it to dx.

A MultiFitter object allows to fit multi-channel data with the same model.

Parameters:

dx (Data) – Data object containing the FRET data
save_fitter (bool) – if True save the MultiFitter object in the dx object with name: burst_data + ‘_fitter’.
burst_data (string) – name of burst-data attribute (i.e ‘E’ or ‘S’).
weights (string or None) – kind of burst-size weights. See fretbursts.fret_fit.get_weights().
gamma (float) – gamma factor passed to get_weights().
add_naa (bool) – if True adds naa to the burst size.
binwidth (float or None) – bin width used to compute the histogram. If None the histogram is not computed.
bandwidth (float or None) – bandwidth used to compute the KDE If None the KDE is not computed.
model (lmfit.Model object or None) – lmfit Model used for histogram fitting. If None the histogram is not fitted.
verbose (bool) – if False avoids printing any output.
fit_tot (bool) – whether to perform histogram fitting on combination of all arrays

Returns:

The mfit.MultiFitter object with the specified burst-size weights.

fretbursts.burstlib_ext.calc_bg_brute(dx, min_ph_delay_list=None, return_all=False, error_metrics='KS')¶

Compute background for all the ch, ph_sel and periods.

This function performs a brute-force search of the min ph delay threshold. The best threshold is the one the minimizes the error function. The best background fit is the rate fitted using the best threshold.

Parameters:

min_ph_delay_list (sequence) – sequence of values used for the brute-force search. Background and error will be computed for each value in min_ph_delay_list.
return_all (bool) – if True return all the fitted backgrounds and error functions. Default False.
error_metrics (string) – Specifies the error metric to use. See fretbursts.background.exp_fit() for more details.

Returns:

Two arrays with best threshold (us) and best background. If return_all = True also returns the dictionaries containing all the fitted backgrounds and errors.

fretbursts.burstlib_ext.calc_bg_brute_cache(dx, min_ph_delay_list=None, return_all=False, error_metrics='KS', force_recompute=False)¶

Compute background for all the ch, ph_sel and periods caching results.

Results are cached to disk and loaded transparently when needed. The cache file is an HDF5 file named dx.fname[:-5] + '_BKG.hdf5'.

Parameters:

min_ph_delay_list (sequence) – sequence of values used for the brute-force search. Background and error will be computed for each value in min_ph_delay_list.
return_all (bool) – if True return all the fitted backgrounds and error functions. Default False.
error_metrics (string) – Specifies the error metric to use. See fretbursts.background.exp_fit() for more details.
force_recompute (bool) – if True, recompute results even if a cache is found.

Returns:

Two arrays with best threshold (us) and best background. If return_all = True also returns the dictionaries containing all the fitted backgrounds and errors.

fretbursts.burstlib_ext.calc_mdelays_hist(d, ich=0, m=10, period=(0, -1), bins_s=(0, 10, 0.02), ph_sel=('DAem', 'DAem'), bursts=False, bg_fit=True, bg_F=0.8)¶

Compute histogram of m-photons delays (or waiting times).

Parameters:

dx (Data object) – contains the burst data to process.
ich (int) – the channel number. Default 0.
period (tuple) – tuple of the range of periods for calculating
m (int) – number of photons used to compute each delay.
period (int or 2-element tuple) – index of the period to use. If tuple, the period range between period[0] and period[1] (included) is used.
bins_s (3-element tuple) – start, stop and step for the bins
ph_sel (Ph_sel object) – photon selection to use.

Returns:

Tuple of values –

bin_x (array): array of bins centers
histograms_y (array): arrays of histograms, contains 1 or 2 histograms (when bursts is False or True)
bg_dist (random distribution): erlang distribution with same rate as background (kcps)
a, rate_kcps (floats, optional): amplitude and rate for an Erlang distribution fitted to the histogram for bin_x > bg_mean*bg_F. Returned only if bg_fit is True.

fretbursts.burstlib_ext.calc_mean_lifetime(dx, t1=0, t2=inf, ph_sel=('DAem', 'DAem'))¶

Compute the mean lifetime in each burst.

Parameters:

t1, t2 (floats) – min and max value (in TCSPC bin units) for the nanotime to be included in the mean
ph_sel (Ph_sel object) – object defining the photon selection. See fretbursts.ph_sel for details.

Returns:

List of arrays of per-burst mean lifetime. One array per channel.

fretbursts.burstlib_ext.fit_bursts_kde_peak(dx, burst_data='E', bandwidth=0.03, weights=None, gamma=1, add_naa=False, x_range=(-0.1, 1.1), x_ax=None, save_fitter=True)¶

Fit burst data (typ. E or S) by finding the KDE max on all the channels.

Parameters:

dx (Data) – Data object containing the FRET data
burst_data (string) – name of burst-data attribute (i.e ‘E’ or ‘S’).
bandwidth (float) – bandwidth for the Kernel Density Estimation
weights (string or None) – kind of burst-size weights. See fretbursts.fret_fit.get_weights().
gamma (float) – gamma factor passed to get_weights().
add_naa (bool) – if True adds naa to the burst size.
save_fitter (bool) – if True save the MultiFitter object in the dx object with name: burst_data + ‘_fitter’.
x_range (tuple of floats) – min-max range where to search for the peak. Used to select a single peak in a multi-peaks distribution.
x_ax (array or None) – x-axis used to evaluate the Kernel Density

Returns:

An array of max peak positions (one per ch). If the number of channels is 1 returns a scalar.

fretbursts.burstlib_ext.get_burst_photons(d, ich=0, ph_sel=('DAem', 'DAem'))¶

Return a list of arrays of photon timestamps in each burst.

Deprecated since version 0.6.5: Use burst_photons() instead.

Parameters:

d (Data) – Data() object
ich (int) – channel index
ph_sel (Ph_sel) – photon selection. It allows to select timestamps from a specific photon selection. Example ph_sel=Ph_sel(Dex=’Dem’). See fretbursts.ph_sel for details.

Returns:

A list of arrays of photon timestamps (one array per burst).

fretbursts.burstlib_ext.group_data(d_list)¶

Group a list of data objects into single data object as though each data object was a different set of set of spots, so the returned data object appears as a multi-spot experiment. Usefull for joining technical repeats, especially so that background calculation etc can be calculated equally on all members. This serves as an alternative to join_data() but has some key differences: 1. Data objects can be at any state of analysis 2. Photon data is maintained, so reassesment of background, burst search etc. all remain possible 3. Each data object is treated as a separate spot, so burst arrays are not concatenated

Parameters:

d_list (list of Data) – A list of data objects to be grouped into single data object

Raises:

RuntimeError – Mismatched fields indicating data are not technical repeats of each other
ValueError – Inconsistent FRET correction factors

Returns:

new_d (Data) – Data object of inputs grouped into new multi-spot measurment.

fretbursts.burstlib_ext.histogram_mdelays(d, ich=0, m=10, ph_sel=('DAem', 'DAem'), binwidth=0.001, dt_max=0.01, bins=None, inbursts=False)¶

Compute histogram of m-photons delays (or waiting times).

Parameters:

dx (Data object) – contains the burst data to process.
ich (int) – the channel number. Default 0.
m (int) – number of photons used to compute each delay.
ph_sel (Ph_sel object) – photon selection to use.
inbursts (bool) – if True, compute the histogram with only photons in bursts.

Returns:

A HistData object containing the computed histogram.

fretbursts.burstlib_ext.join_data(d_list, gap=0)¶

Joins burst data of different measurements in a single Data object.

Merge a list of Data objects (i.e. a set of different measurements) into a single Data object containing all the bursts (like it was a single acquisition). The Data objects to be merged need to already contain burst data. The input Data objects are required to have undergone background estimation (all with the same background period) and burst search. For each measurement, the time of burst start is offset by the duration of the previous measurement + an additional gap (which is 0 by default).

The index of the first/last photon in the burst (istart and iend) are kept unmodified and refer to the original timestamp array. The timestamp arrays are not copied: the new Data object will not contain any timestamp arrays (ph_times_m). This may cause errors when calling functions that require the timestamps data such as burst search.

The background arrays (bg, bg_dd, etc…) are concatenated. The burst attribute bp is updated to refer to these new concatenated arrays. The attributes Lim and Ph_p are concatenated and left unchanged. Therefore different sections will refer to different original timestamp arrays. The retuned Data object will have a new attribute i_origin, containing, for each burst, the index of the original data object in the list.

Parameters:

d_list (list of Data objects) – the list of measurements to concatenate.
gap (float) – the time delay (or gap) in seconds to add to each concatenated measurement.

Returns:

A Data object containing bursts from the all the objects in d_list. This object will not contain timestamps, therefore it is possible to perform burst selections but not a new burst search.

Example

If d1 and d2 are two measurements to concatenate:

file_list = ['filename1', 'filename2']
d_list = [loader.photon_hdf5(f) for f in file_list]

for dx in d_list:
    loader.alex_apply_period(dx)
    dx.calc_bg(bg.exp_fit, time_s=30, tail_min_us='auto', F_bg=1.7)
    dx.burst_search()

d_merged = bext.join_data(d_list)

d_merged will contain bursts from both input files.

fretbursts.burstlib_ext.moving_window_chunks(dx, start, stop, step, window=None, time_zero=0)¶

Return a list of Data object, each containing bursts in one time-window.

Each returned Data object contains only bursts lying in the current time-window. Additionally, the start/stop values of current time-window are saved in Data’s attributes: name, slice_tstart and slice_tstop.

Parameters:

dx (Data) – the Data() object to be sliced with a moving window.
start, stop (scalars) – time-range in seconds spanned by the moving window.
step (scalar) – window time-shift at each step.
window (scalar) – window duration. If None, window = step.
time_zero (scalar) – shift the start/stop times saved in the Data attributes so that “time zero” falls at time_zero seconds. Default 0, no shift.

Returns:

A list of Data objects, one for each window position.