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