Photon rates functions¶
This module provides functions to compute photon rates from timestamps arrays. Different methods to compute rates are implemented:
 Consecutive set of m timestamps (“sliding mtuple”)
 KDEbased methods with Gaussian or Laplace distribution or rectangular kernels.
Note
When using of “sliding mtuple” method (1), rates can be only computed for each consecutive set of m timestamps. The timeaxis can be computed from the mean timestamp in each mtuple.
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 KDEbased rate computation using a rectangular kernel.

fretbursts.phtools.phrates.
kde_gaussian
(timestamps, tau, time_axis=None)¶ Computes Gaussian KDE for
timestamps
evaluated attime_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
. Whentime_axis
is None, thentimestamps
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) – nonnormalized 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 attime_axis
.Computes KDE rates of
timestamps
using a laplace distribution kernel (i.e. symmetricexponential):kernel = exp( t  t0 / tau)
The rate is computed for each time point in
time_axis
. Whentime_axis
is None, thentimestamps
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) – nonnormalized 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 attime_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
. Whentime_axis
is None, thentimestamps
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) – nonnormalized 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 mphotons delays of size ph.size  m + 1.
The mphotons delay is defined as the difference between the last and first timestamp in each set of m consecutive timestamps. The mphotons 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 mphotons delays, with size equal to
ph.size  m + 1
.

fretbursts.phtools.phrates.
mtuple_delays_min
(ph, m)¶ Compute the min mphotons delay in
ph
.

fretbursts.phtools.phrates.
mtuple_rates
(ph, m, c=1)¶ Compute the instantaneous rates for timestamps in
ph
usingm
photons.Compute the rates for all the consecutive sets of m photons. Noting that the number of interphoton 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 mphoton rate in
ph
.

fretbursts.phtools.phrates.
mtuple_rates_t
(ph, m)¶ Compute mean time for each rate computed by
mtuple_rates
.