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()
andfit_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 (defaultmean
) 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 indx
.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 whilephoton_id
identifies each photon in a burst.burst_id
is the same number used as index in theDataFrame
returned byburst_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=Ph_sel(Dex='DAem', Aex=None), ph_sel2=Ph_sel(Dex=None, Aex='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
andph_sel2
.m (int or tuple) – Burst search parameter m. If it is a 2-element tuple, specifies m separately for
ph_sel1
andph_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 forph_sel1
andph_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 inburstlib.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.
See also
fretbursts.burstlib.Data.burst_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 datasave_fitter (bool) – if True save the
MultiFitter
object in thedx
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.
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.
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=Ph_sel(Dex='DAem', Aex='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.
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=Ph_sel(Dex='DAem', Aex='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 databurst_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 thedx
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=Ph_sel(Dex='DAem', Aex='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=Ph_sel(Dex='DAem', Aex='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 singleData
object containing all the bursts (like it was a single acquisition). TheData
objects to be merged need to already contain burst data. The inputData
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 additionalgap
(which is 0 by default).The index of the first/last photon in the burst (
istart
andiend
) are kept unmodified and refer to the original timestamp array. The timestamp arrays are not copied: the newData
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 attributesLim
andPh_p
are concatenated and left unchanged. Therefore different sections will refer to different original timestamp arrays. The retunedData
object will have a new attributei_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 ind_list
. This object will not contain timestamps, therefore it is possible to perform burst selections but not a new burst search.
Example
If
d1
andd2
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.
See also:
moving_window_dataframe()
.
- fretbursts.burstlib_ext.moving_window_dataframe(start, stop, step, window=None, time_zero=0)¶
Create a DataFrame for storing moving-window data.
Create and return a DataFrame for storing columns of moving-window data. Three columns are initialize with “time axis” data: ‘tstart’, ‘tstop’ and ‘tmean’. The returned DataFrame is typically used to store (in new columns) quantities as function of the moving time-window. Examples of such quantities are number of bursts, mean burst size/duration, fitted E peak position, etc.
- Parameters
start, stop (scalars) – range spanned by the moving window.
step (scalar) – window shift at each “step”.
window (scalar) – window duration. If None, window = step.
- Returns
DataFrame with 3 columns (tstart, tstop, tmean), one row for each window position.
See also:
moving_window_chunks()
.
- fretbursts.burstlib_ext.moving_window_startstop(start, stop, step, window=None)¶
Computes list of (start, stop) values defining a moving-window.
- Parameters
start, stop (scalars) – range spanned by the moving window.
step (scalar) – window shift at each “step”.
window (scalar) – window duration. If None, window = step.
- Returns
A list of (start, stop) values for the defined moving-window range.
- fretbursts.burstlib_ext.ph_burst_stats(d, ich=0, func=<function mean>, ph_sel=Ph_sel(Dex='DAem', Aex='DAem'))¶
Applies function
func
to the timestamps of each burst.- Parameters
d (Data) – Data() object
ich (int) – channel index
func (function) – a function that take an array of burst-timestamps and return a scalar. Default
numpy.mean
.ph_sel (Ph_sel) – photon selection. It allows to select timestamps from a specific photon selection. Default Ph_sel(‘all’). See
fretbursts.ph_sel
for details.
- Returns
An array containing per-burst timestamp statistics.