import numpy as np
[docs]
def periodic_bin_exponential(tau, n_bins, period):
"""
Fraction of the photons of a periodically excited mono-exponential decay (lifetime
``tau``, any shape ``S``) that falls in each of ``n_bins`` equal bins covering one
repetition ``period`` (same time unit as ``tau``). In steady state the tails of all
earlier pulses add up to the same exponential shape, so bin ``k`` receives
``exp(-k dt / tau) (1 - exp(-dt / tau)) / (1 - exp(-period / tau))`` with
``dt = period / n_bins``. Returns ``S + (n_bins,)``, summing to 1 along the last axis.
"""
tau = np.asarray(tau, dtype=float)[..., None]
dt = period / n_bins
m = np.arange(n_bins)
return -np.expm1(-dt / tau) * np.exp(-m * dt / tau) / -np.expm1(-n_bins * dt / tau)
[docs]
def periodic_instrument_exponential(tau, n_bins, period):
"""
Per-bin photon distribution of a periodically excited mono-exponential decay as a
real time-resolved instrument records it: excitation (IRF) photons arrive anywhere
inside their bin, not at its start, so this is the decay kernel that, circularly
convolved with the binned IRF, gives the binned measurement when the IRF density is
uniform within each bin. With ``x = dt / tau`` and ``dt = period / n_bins``:
* bin 0: ``1 - (1 - e^-x) / x`` (decays starting and ending in the excitation bin)
plus the wrapped tails of earlier pulses;
* bin ``m >= 1``: ``e^(-m x) (1 - e^-x)(e^x - 1) / x``, divided by
``1 - exp(-period / tau)`` for the periodic steady state.
Its discrete Fourier transform at the laser frequency equals the continuous
phasor ``1 / (1 - i omega tau)`` up to ~1e-4, so IRF-calibrated phasors of such data
lie on the universal semicircle. :func:`periodic_bin_exponential` is the kernel when
every excitation is at a bin start (pyfli's ``PhotonCountSimulator``). Returns
``S + (n_bins,)``, summing to 1 along the last axis.
"""
tau = np.asarray(tau, dtype=float)[..., None]
dt = period / n_bins
x = dt / tau
m = np.arange(n_bins)
inner = -np.expm1(-x) * np.expm1(x) / x
steady = 1.0 / -np.expm1(-n_bins * x)
out = np.exp(-m * x) * inner * steady
first = 1.0 - (-np.expm1(-x)) / x + np.exp(-n_bins * x) * inner * steady
out[..., 0] = first[..., 0]
return out
[docs]
def gate_starts(period, n_gates):
"""
Start times ``m * period / n_gates``, ``m = 0..n_gates-1``, of `n_gates` equal gates
covering ``[0, period)``: the time axis of the fitters, reconstruction, simulators
and phasors (``linspace(0, period, n_gates, endpoint=False)``).
"""
return np.arange(n_gates) * (period / n_gates)
[docs]
def circular_convolve(x, h, axis=-1):
"""
Circular convolution ``y[n] = sum_m x[m] h[(n - m) mod N]`` along `axis` (inputs
broadcast, both of length ``N`` there): the discrete periodic measurement model
``F = I (*) f`` over one repetition period, under which phasors factorise,
``z_k(F) = z_k(I) z_k(f)``.
"""
x = np.asarray(x, dtype=float)
h = np.asarray(h, dtype=float)
n = x.shape[axis]
if h.shape[axis] != n:
raise ValueError(f"length mismatch along axis {axis}: {n} vs {h.shape[axis]}")
return np.fft.irfft(
np.fft.rfft(x, axis=axis) * np.fft.rfft(h, axis=axis), n=n, axis=axis
)
[docs]
def circular_convolve_torch(x, h, dim=-1):
"""Torch form of :func:`circular_convolve` (differentiable)."""
import torch
n = x.shape[dim]
if h.shape[dim] != n:
raise ValueError(f"length mismatch along dim {dim}: {n} vs {h.shape[dim]}")
return torch.fft.irfft(
torch.fft.rfft(x, dim=dim) * torch.fft.rfft(h, dim=dim), n=n, dim=dim
)
def _periodic_exponential_cdf(x, tau, h_shift, period, expm1):
u = x - h_shift
r = u % period
return (u - r) / period + expm1(-r / tau) / expm1(-period / tau)
[docs]
def periodic_gate_integral(a, b, tau, h_shift, period, expm1=np.expm1):
"""
Fraction of the photons of a periodically excited exponential (lifetime `tau`, onset
`h_shift` after each pulse, repetition `period`) that falls in ``[a, b)``, in steady
state. With ``u = x - h_shift`` the cumulative count since ``t = h_shift`` is
``Psi(x) = floor(u / T) + (1 - e^{-(u mod T) / tau}) / (1 - e^{-T / tau})``, continuous
in `x` and `h_shift`, and the gate holds ``Psi(b) - Psi(a)``; gates tiling one period
sum to 1. For ``h_shift = 0`` on :func:`gate_starts` gates this is
:func:`periodic_bin_exponential`. Pass ``expm1=torch.expm1`` for tensors.
"""
return _periodic_exponential_cdf(
b, tau, h_shift, period, expm1
) - _periodic_exponential_cdf(a, tau, h_shift, period, expm1)
[docs]
def fourier_shift(x, shift):
"""
Delay `x` by `shift` samples (fractional; scalar or broadcast against
``x.shape[:-1]``) along the last axis with the phase ramp ``e^{-2 pi i k shift / N}``:
``x[n] -> x[n - shift]``
circularly, exact for integer shifts and for band-limited periodic signals. A
positive shift delays, as :meth:`pyfli.data_cc.irfAligner.IRFAligner.estimate_shift`
reports it; delaying the IRF by ``s`` gates is the solver's onset
``h_shift = s * dt``.
"""
x = np.asarray(x, dtype=float)
n = x.shape[-1]
shift = np.asarray(shift, dtype=float)[..., None]
phase = np.exp(-2j * np.pi * np.fft.rfftfreq(n) * shift)
return np.fft.irfft(np.fft.rfft(x, axis=-1) * phase, n=n, axis=-1)
NLSF_WEIGHTINGS = ("irls", "none", "neyman")
[docs]
def residual_variance(model, data, weighting, variance_floor=1.0):
"""
Per-gate variance ``v_k`` of weighted least squares ``sum_k (d_k - mu_k)^2 / v_k``
(NumPy arrays or torch tensors): ``"irls"`` ``max(mu_k, variance_floor)`` from the
model held fixed (Poisson variance; see :func:`irls`), ``"neyman"`` ``max(d_k, 1)``
from the data, ``"none"`` 1.
"""
if weighting == "irls":
return model.clip(min=variance_floor)
if weighting == "neyman":
return data.clip(min=1.0)
if weighting == "none":
return data * 0 + 1
raise ValueError(f"weighting must be one of {NLSF_WEIGHTINGS}, got {weighting!r}")
def _relative_change(old, new):
return np.max(np.abs(new - old) / np.maximum(np.abs(old), 1e-12))
[docs]
def irls(solve, predict, x0, variance_floor=1.0, max_rounds=20, tol=1e-6, change=None):
"""
Iteratively reweighted least squares for Poisson counts: each round solves the
weighted problem with the variance frozen at ``max(mu, variance_floor)`` of the
previous round, ``x_{r+1} = solve(x_r, residual_variance(predict(x_r)))``, until
``change(x_r, x_{r+1}) < tol`` (default: largest element-wise relative change) or
`max_rounds`. A `change` returning one value per row of ``x`` (pixels) freezes
each row at its own convergence, so a batch reproduces per-pixel runs exactly. At
convergence ``sum_k (d_k - mu_k) / mu_k * dmu_k/dx = 0``, the
Poisson likelihood equations.
Parameters
----------
solve : callable
``solve(x, variance) -> (x_new, extra)``.
predict : callable
``predict(x) -> mu``, the model counts on the fitted gates.
x0 : array_like
Starting parameters.
Returns
-------
tuple
``(x, extra)`` of the last round.
"""
change = _relative_change if change is None else change
x, extra = np.asarray(x0, dtype=float), None
active = np.ones(np.shape(change(x, x)), dtype=bool)
for _ in range(max_rounds):
variance = residual_variance(
np.asarray(predict(x)), None, "irls", variance_floor
)
x_new, extra = solve(x, variance)
delta = change(x, x_new)
if active.ndim:
x = np.where(active[:, None], x_new, x)
else:
x = x_new
active = active & ~(delta < tol)
if not active.any():
break
return x, extra
[docs]
def weighted_linear_lstsq(V, d, variance=None, penalty=None, reg_strength=0.0):
"""
Per-pixel solution of ``min_c sum_t (d_t - (V c)_t)^2 / v_t + lam sum_k p_k c_k^2``
with ``lam = reg_strength * mean_k sum_t V_tk^2 / v_t``, by QR of the
sqrt-weighted, penalty-augmented design.
Parameters
----------
V : np.ndarray
Design ``(T, K)`` shared by all pixels, or ``(P, T, K)`` per pixel.
d : np.ndarray
Data ``(P, T)``.
variance : np.ndarray | None
``(P, T)`` per-gate variances (:func:`residual_variance`); ``None`` is 1.
penalty : np.ndarray | None
``(K,)`` penalty weights ``p_k`` for `reg_strength`.
Returns
-------
np.ndarray
``(P, K)`` coefficients.
"""
d = np.asarray(d, dtype=float)
V = np.asarray(V, dtype=float)
if V.ndim == 2 and variance is None and reg_strength == 0.0:
return np.linalg.lstsq(V, d.T, rcond=None)[0].T
P, T = d.shape
K = V.shape[-1]
sw = np.ones((P, T)) if variance is None else 1.0 / np.sqrt(variance)
A = sw[..., None] * np.broadcast_to(V, (P, T, K))
y = sw * d
if reg_strength > 0.0:
p = np.ones(K) if penalty is None else np.asarray(penalty, dtype=float)
lam = reg_strength * np.mean(np.sum(A**2, axis=1), axis=-1)
aug = np.sqrt(lam)[:, None, None] * np.diag(np.sqrt(p))
A = np.concatenate([A, aug], axis=1)
y = np.concatenate([y, np.zeros((P, K))], axis=1)
q, r = np.linalg.qr(A)
try:
return np.linalg.solve(r, np.einsum("ptk,pt->pk", q, y)[..., None])[..., 0]
except np.linalg.LinAlgError:
return np.einsum("pkt,pt->pk", np.linalg.pinv(A), y)
[docs]
def decay_histogram(taus, fractions, irf, period, periodic=True):
"""
Expected fraction of the emitted photons in each of the ``n`` gates tiling one
`period` (:func:`gate_starts`), for a decay whose photons come from exponential
components `taus` with photon fractions `fractions`, each excitation at the start of an
IRF gate (``irf`` normalised here). ``periodic=True``: steady state of the pulse train
(photons wrapped over the period), :func:`periodic_gate_integral` circularly convolved
with the IRF; sums to 1, as pyfli's photon simulator with ``pileup_mode="wrap"`` and the
solver's ``shift_method="circular"``. ``periodic=False``: a single pulse, photons past
the period lost, gate-integrated exponentials linearly convolved and truncated, as
``pileup_mode="truncate"`` and ``shift_method="zero_pad"``.
"""
irf = np.asarray(irf, dtype=float)
irf = irf / irf.sum()
n = irf.size
dt = period / n
t = gate_starts(period, n)
kernel = np.zeros(n)
for tau, fraction in zip(np.atleast_1d(taus), np.atleast_1d(fractions)):
if periodic:
kernel += fraction * periodic_gate_integral(
t, t + dt, float(tau), 0.0, period
)
else:
kernel += fraction * -np.diff(np.exp(-np.append(t, period) / float(tau)))
if periodic:
return circular_convolve(kernel, irf)
return np.convolve(kernel, irf)[:n]
[docs]
def mono_reconstruction(t, tau, S=1.0):
return (S / tau) * np.exp(-t / tau)
[docs]
def bi_reconstruction(t, tau1, tau2, A1, A2):
return (A1 / tau1) * np.exp(-t / tau1) + (A2 / tau2) * np.exp(-t / tau2)
[docs]
def mono_reconstruction_torch(t, tau, S=1.0):
return (S / tau) * (-t / tau).exp()
[docs]
def bi_reconstruction_torch(t, tau1, tau2, A1, A2):
return (A1 / tau1) * (-t / tau1).exp() + (A2 / tau2) * (-t / tau2).exp()