Burst selection¶
After performing a burst search is common to select bursts according to different criteria (burst size, FRET efficiency, etc…).
In FRETBursts this can be easily accomplished using the method
Data.select_bursts()
. This method takes
a selection function
as parameters. Data.select_bursts()
returns a new Data
object
containing only the new sub-set of bursts. A new selection can be applied
to this new object as well. In this way, different
selection criteria can be freely combined in order to obtain a
burst population satisfying arbitrary constrains.
FRETBursts provides a large number of
selection functions. Moreover, creating a new
selection function is extremely simple, requiring (usually) 2-3 lines of code.
You can take the functions in select_bursts.py
as examples to create your
own selection rule.
In the next section we list all the selection functions. You may also want
to check the Data
methods that deal with burst selection:
Selection functions¶
The module select_bursts
defines functions to select
bursts according to different criteria.
These functions are usually passed to
Data.select_bursts()
.
For example:
ds = d.select_bursts(select_bursts.E, th1=0.2, th2=0.6)
returns a new object ds
containing only the bursts of d
that pass the
specified selection criterium (E
between 0.2 and 0.6 in this case).
- fretbursts.select_bursts.E(d, ich=0, E1=-inf, E2=inf)¶
Select bursts with E between E1 and E2.
- fretbursts.select_bursts.ES(d, ich=0, E1=-inf, E2=inf, S1=-inf, S2=inf, rect=True)¶
Select bursts with E between
E1
andE2
and S betweenS1
andS2
.When
rect
is True the selection is rectangular otherwise is elliptical.See also
For plotting the ES region selected by (
E1
,E2
,S1
,S2
,rect
):
- fretbursts.select_bursts.ES_ellips(d, ich=0, E1=-1000.0, E2=1000.0, S1=-1000.0, S2=1000.0)¶
Select bursts with E-S inside an ellipsis inscribed in E1, E2, S1, S2.
- fretbursts.select_bursts.ES_rect(d, ich=0, E1=-inf, E2=inf, S1=-inf, S2=inf)¶
Select bursts inside the rectangle defined by E1, E2, S1, S2.
- fretbursts.select_bursts.brightness(d, ich=0, th1=0, th2=inf, add_naa=False, gamma=1, beta=1, donor_ref=True)¶
Select bursts with size/width between th1 and th2 (cps).
- fretbursts.select_bursts.consecutive(d, ich=0, th1=0, th2=inf, kind='both')¶
Select consecutive bursts with th1 <= separation <= th2 (in sec.).
- Parameters
kind (string) – valid values are ‘first’ to select the first burst of each pair, ‘second’ to select the second burst of each pair and ‘both’ to select both bursts in each pair.
- fretbursts.select_bursts.na(d, ich=0, th1=20, th2=inf)¶
Select bursts with (na >= th1) and (na <= th2).
- fretbursts.select_bursts.na_bg(d, ich=0, F=5)¶
Select bursts with (na >= bg_ad*F).
- fretbursts.select_bursts.na_bg_p(d, ich=0, P=0.05, F=1.0)¶
Select bursts w/ AD signal using P{F*BG>=na} < P.
- fretbursts.select_bursts.naa(d, ich=0, th1=20, th2=inf, gamma=1.0, beta=1.0, donor_ref=True, naa_comp=False, naa_aexonly=True)¶
Select bursts with (naa >= th1) and (naa <= th2).
The
naa
quantity can be optionally corrected using gamma and beta factors.- Parameters
th1, th2 (floats) – lower (
th1
) and upper (th2
) bounds for selectingnaa
. By defaultth2 = inf
(i.e. no upper limit).gamma, beta (floats) – arguments used to compute gamma- and beta-corrected burst sizes. See
fretbursts.burstlib.Data.burst_sizes_ich()
for details.donor_ref (bool) – Select the convention for
naa
correction. If True (default), usesnaa / (beta * gamma)
. Otherwise, usesnaa / beta
. It is suggested to use the samedonor_ref
convention when combiningDex size
andnaa
burst selections so that the thresholds values of the two selections will be commensurable.na_comp (bool) – [PAX-only] If True, multiply the
na
term by(1 + Wa/Wd)
, where Wa and Wd are the D and A alternation durations (typically Wa/Wd = 1).naa_aexonly (bool) – [PAX-only] if True, the
naa
term is corrected to include only A emission due to A excitation. If False, thenaa
term includes all the counts in DAexAem. Thenaa
term also depends on thenaa_comp
argument.naa_comp (bool) – [PAX-only] If True, multiplies the
naa
term by(1 + Wa/Wd)
where Wa and Wd are the D and A alternation durations (typically Wa/Wd = 1). Thenaa
term also depends on thenaa_aexonly
argument.
- fretbursts.select_bursts.naa_bg(d, ich=0, F=5)¶
Select bursts with (naa >= bg_aa*F).
- fretbursts.select_bursts.naa_bg_p(d, ich=0, P=0.05, F=1.0)¶
Select bursts w/ AA signal using P{F*BG>=naa} < P.
- fretbursts.select_bursts.nd(d, ich=0, th1=20, th2=inf)¶
Select bursts with (nd >= th1) and (nd <= th2).
- fretbursts.select_bursts.nd_bg(d, ich=0, F=5)¶
Select bursts with (nd >= bg_dd*F).
- fretbursts.select_bursts.nd_bg_p(d, ich=0, P=0.05, F=1.0)¶
Select bursts w/ DD signal using P{F*BG>=nd} < P.
- fretbursts.select_bursts.nda_percentile(d, ich=0, q=50, low=False, gamma=1.0, add_naa=False)¶
Select bursts with SIZE >= q-percentile (or <= if
low
is True)gamma
andadd_naa
are passed tofretbursts.burstlib.Data.burst_sizes_ich()
to compute the burst size.
- fretbursts.select_bursts.nt_bg(d, ich=0, F=5)¶
Select bursts with (nt >= bg*F).
- fretbursts.select_bursts.nt_bg_p(d, ich=0, P=0.05, F=1.0)¶
Select bursts w/ signal using P{F*BG>=nt} < P.
- fretbursts.select_bursts.peak_phrate(d, ich=0, th1=0, th2=inf)¶
Select bursts with peak phtotons rate between th1 and th2 (cps).
Note that this function requires to compute the peak photon rate first using
fretbursts.burstlib.Data.calc_max_rate()
.
- fretbursts.select_bursts.period(d, ich=0, bp1=0, bp2=None)¶
Select bursts from period bp1 to period bp2 (included).
- fretbursts.select_bursts.sbr(d, ich=0, th1=0, th2=inf)¶
Select bursts with SBR between
th1
andth2
.
- fretbursts.select_bursts.single(d, ich=0, th=1)¶
Select bursts that are at least th millisec apart from the others.
- fretbursts.select_bursts.size(d, ich=0, th1=20, th2=inf, add_naa=False, gamma=1.0, beta=1.0, donor_ref=True, ph_sel=None, naa_aexonly=False, naa_comp=False, na_comp=False)¶
Select bursts with burst sizes (i.e. counts) between
th1
andth2
.The burst size is the number of photon in a burst. By default it includes all photons during donor excitation (
Dex
). To add AexAem photons to the burst size useadd_naa=True
. Ifph_sel
is specified use a PAX-specific definition of size as defined infretbursts.burstlib.Data.burst_sizes_pax_ich()
.- Parameters
d (Data object) – the object containing the measurement.
ich (int) – the spot number, only relevant for multi-spot. In single-spot data there is only CH-0 so this argument may be omitted. Default 0.
th1, th2 (floats) – select bursts with
th1 <= size <= th2
. Defaultth2 = inf
(i.e. no upper limit).add_naa (boolean) – when True, add AexAem photons when computing burst burst size. Default False.
gamma, beta (floats) – arguments used to compute gamma- and beta-corrected burst sizes. See
fretbursts.burstlib.Data.burst_sizes_ich()
for details.donor_ref (bool) – Select the convention for
naa
correction. Seefretbursts.burstlib.Data.burst_sizes_ich()
for details.ph_sel (Ph_sel object or None) – if not None, use PAX-specific burst size definition. ph_sel defines which terms are included in the burst size.
na_comp (bool) – [PAX-only] If True, multiply the
na
term by(1 + Wa/Wd)
, where Wa and Wd are the D and A alternation durations (typically Wa/Wd = 1).naa_aexonly (bool) – [PAX-only] if True, the
naa
term is corrected to include only A emission due to A excitation. If False, thenaa
term includes all the counts in DAexAem. Thenaa
term also depends on thenaa_comp
argument.naa_comp (bool) – [PAX-only] If True, multiply the
naa
term by(1 + Wa/Wd)
where Wa and Wd are the D and A alternation durations (typically Wa/Wd = 1). Thenaa
term also depends on thenaa_aexonly
argument.
- Returns
A tuple containing an array (the burst mask) and a string which briefly describes the selection.
- fretbursts.select_bursts.str_G(gamma, donor_ref)¶
A string indicating gamma value and convention for burst size correction.
- fretbursts.select_bursts.time(d, ich=0, time_s1=0, time_s2=None)¶
Select the burst starting from time_s1 to time_s2 (in seconds).
- fretbursts.select_bursts.topN_max_rate(d, ich=0, N=500)¶
Select
N
bursts with the highest max burst rate.
- fretbursts.select_bursts.topN_nda(d, ich=0, N=500, gamma=1.0, add_naa=False)¶
Select the N biggest bursts in the channel.
gamma
andadd_naa
are passed tofretbursts.burstlib.Data.burst_sizes_ich()
to compute the burst size.
- fretbursts.select_bursts.topN_sbr(d, ich=0, N=200)¶
Select the top
N
bursts with highest SBR.
- fretbursts.select_bursts.width(d, ich=0, th1=0.5, th2=inf)¶
Select bursts with (width >= th1) and (width <= th2), in ms.