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:

• Data.select_bursts()

• Data.select_bursts_mask()

• Data.select_bursts_mask_apply()

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 and E2 and S between S1 and S2.

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.burst_plot.plot_ES_selection()

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 selecting naa. By default th2 = 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), uses naa / (beta * gamma). Otherwise, uses naa / beta. It is suggested to use the same donor_ref convention when combining Dex size and naa 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, the naa term includes all the counts in DAexAem. The naa term also depends on the naa_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). The naa term also depends on the naa_aexonly argument.

See also

• fretbursts.burstlib.Data.burst_sizes_pax_ich().

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 and add_naa are passed to fretbursts.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 and th2.

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

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 use add_naa=True. If ph_sel is specified use a PAX-specific definition of size as defined in fretbursts.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. Default th2 = 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. See fretbursts.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, the naa term includes all the counts in DAexAem. The naa term also depends on the naa_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). The naa term also depends on the naa_aexonly argument.

Returns:

A tuple containing an array (the burst mask) and a string which briefly describes the selection.

See also

• fretbursts.burstlib.Data.burst_sizes_ich().

• fretbursts.burstlib.Data.burst_sizes_pax_ich().

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 and add_naa are passed to fretbursts.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.