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 m-tuple”)
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 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) – 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 attime_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
. 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) – 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 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) – 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
usingm
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
.