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

When `rect` is True the selection is rectangular otherwise is elliptical.

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

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.

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.

`gamma` and `add_naa` are passed to `fretbursts.burstlib.Data.burst_sizes_ich()` to compute the burst size.
Select the top `N` bursts with highest SBR.