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….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:
get_burst_photons()
returns a list of timestamps for each burst.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: |
|
---|---|
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:
Optional columns include:
include_ph_index=True
)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: |
|
---|---|
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: |
|
---|---|
Returns: | 2D of arrays with shape (nch, nperiods). |
Example
burst_period_mean(dx, dx.nt)
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: |
|
---|---|
Returns: | A new |
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)¶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: |
|
---|---|
Returns: | The |
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: |
|
---|---|
Returns: | Two arrays with best threshold (us) and best background. If
|
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: |
|
---|---|
Returns: | Two arrays with best threshold (us) and best background. If
|
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: |
|
---|---|
Returns: | Tuple of values –
|
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: |
|
---|---|
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: |
|
---|---|
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.
Parameters: |
|
---|---|
Returns: | A list of arrays of photon timestamps (one array per burst). |
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: |
|
---|---|
Returns: | A |
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: |
|
---|---|
Returns: | A |
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: |
|
---|---|
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: |
|
---|---|
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: |
|
---|---|
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: |
|
---|---|
Returns: | An array containing per-burst timestamp statistics. |