# Photon rates functions¶

This module provides functions to compute photon rates from timestamps arrays. Different methods to compute rates are implemented:

1. Consecutive set of m timestamps (“sliding m-tuple”)

2. KDE-based methods with Gaussian or Laplace distribution or rectangular kernels.

Note

When using of “sliding m-tuple” method (1), rates can be only computed for each consecutive set of m timestamps. The time-axis can be computed from the mean timestamp in each m-tuple.

When using the KDE method, rates can be computed at any time point. Practically, the time points at which rates are computed are timestamps (in a photon stream). In other words, we don’t normally use a uniformly sampled time axis but we use a timestamps array as time axis for the rate.

Note that computing rates with a fixed sliding time window and sampling the function by centering the window on each timestamp is equivalent to a KDE-based rate computation using a rectangular kernel.

fretbursts.phtools.phrates.kde_gaussian(timestamps, tau, time_axis=None)

Computes Gaussian KDE for `timestamps` evaluated at `time_axis`.

Computes KDE rates of `timestamps` using a Gaussian kernel:

```kernel = exp( -(t - t0)^2 / (2 * tau^2)) )
```

The rate is computed for each time point in `time_axis`. When `time_axis` is None, then `timestamps` is used as time axis.

Parameters
• timestamps (array) – arrays of photon timestamps

• tau (float) – sigma of the Gaussian kernel

• time_axis (array or None) – array of time points where the rate is computed. If None, uses `timestamps` as time axis.

Returns

rates (array) – non-normalized rates (just the sum of the Gaussian kernels). To obtain rates in Hz divide the array by `2.5*tau`.

fretbursts.phtools.phrates.kde_laplace(timestamps, tau, time_axis=None)

Computes exponential KDE for `timestamps` evaluated at `time_axis`.

Computes KDE rates of `timestamps` using a laplace distribution kernel (i.e. symmetric-exponential):

```kernel = exp( -|t - t0| / tau)
```

The rate is computed for each time point in `time_axis`. When `time_axis` is None, then `timestamps` is used as time axis.

Parameters
• timestamps (array) – arrays of photon timestamps

• tau (float) – time constant of the exponential kernel

• time_axis (array or None) – array of time points where the rate is computed. If None, uses `timestamps` as time axis.

Returns

rates (array) – non-normalized rates (just the sum of the exponential kernels). To obtain rates in Hz divide the array by `2*tau` (or other conventional x*tau duration).

fretbursts.phtools.phrates.kde_rect(timestamps, tau, time_axis=None)

Computes KDE with rect kernel for `timestamps` evaluated at `time_axis`.

Computes KDE rates of `timestamps` using a rectangular kernel which is 1 in the range `[-tau/2, tau/2]` and 0 otherwise.

The rate is computed for each time point in `time_axis`. When `time_axis` is None, then `timestamps` is used as time axis.

Parameters
• timestamps (array) – arrays of photon timestamps

• tau (float) – duration of the rectangular kernel

• time_axis (array or None) – array of time points where the rate is computed. If None, uses `timestamps` as time axis.

Returns

rates (array) – non-normalized rates (just the sum of the rectangular kernels). To obtain rates in Hz divide the array by `tau`.

fretbursts.phtools.phrates.mtuple_delays(ph, m)

Compute array of m-photons delays of size ph.size - m + 1.

The m-photons delay is defined as the difference between the last and first timestamp in each set of m consecutive timestamps. The m-photons delay expression is:

```t[i + m - 1] - t[i]
```

for each i in `[0 .. ph.size - m]`.

Parameters
• ph (array) – photon timestamps array

• m (int) – number of timestamps to use

Returns

Array of m-photons delays, with size equal to `ph.size -  m + 1`.

fretbursts.phtools.phrates.mtuple_delays_min(ph, m)

Compute the min m-photons delay in `ph`.

fretbursts.phtools.phrates.mtuple_rates(ph, m, c=1)

Compute the instantaneous rates for timestamps in `ph` using `m` photons.

Compute the rates for all the consecutive sets of m photons. Noting that the number of inter-photon delays is n = m - 1, the rate is computed with the expression:

```(n - c) / (t[last] - t[first])
```

where “last” and “first” refer to the last and first timestamp in each group of m consecutive timestamps.

By changing `c` we obtain estimators with different properties. When c=1 (default), the result is the unbiased estimator of the rate. When c=1/3 we obtain the estimator whose median is equal to the the rate. Empirically, the minimal RMS error is committed with c=2. All the previous considerations are valid under the assumption that we are estimating the rate of events generated by a stationary Poisson process.

Parameters
• ph (array) – photon timestamps array

• m (int) – number of timestamps to use for computing the rate

• c (float) – correction factor for the rate estimation.

Returns

Array of rates, with size equal to `ph.size -  m + 1`.

fretbursts.phtools.phrates.mtuple_rates_max(ph, m, c=1)

Compute max m-photon rate in `ph`.

fretbursts.phtools.phrates.mtuple_rates_t(ph, m)

Compute mean time for each rate computed by `mtuple_rates`.