"""
Implement Laguerre-basis deconvolution for FLI decay reconstruction.
This module belongs to :mod:`pyfli.laguerre` and is part of PyFLI's Laguerre-basis
deconvolution and fitting method. Public API includes classes :class:`LaguerreFLI`.
"""
import os
from typing import Any
import h5py
import numpy as np
from scipy.optimize import least_squares, minimize_scalar, nnls
from scipy.signal import fftconvolve, lfilter
from tqdm.auto import tqdm
from pyfli import logging
from pyfli.reconstruction.common_reconstruct import (
NLSF_WEIGHTINGS,
circular_convolve,
fourier_shift,
irls,
residual_variance,
weighted_linear_lstsq,
)
from ..cm_funcs.forward_model import (
gate_integrated_kernel,
negative_lag_gates,
validate_excitation,
validate_gate_width,
validate_shift_method,
)
from ..cm_stats.chi_square import degrees_of_freedom
from ..cm_stats.goodness_of_fit import r_squared
from ..cm_stats.shared_metrics import pearson_chi_square, reduced_poisson_deviance
from ..solver.base_static import moment_based_guess
[docs]
class LaguerreFLI:
"""
Run the laguerre FLI routine.
Laguerre basis, projects decays into coefficient space, reconstructs denoised
decays, and supports lifetime estimation from the reconstructed signal.
Parameters
----------
n_components : int
Number of exponential lifetime components to fit.
n_laguerre : Optional[int]
Number of Laguerre basis functions used for reconstruction.
alpha : float
Regularization strength or statistical threshold value, depending on context.
dt : float
Sampling interval between adjacent decay bins.
auto_alpha : bool
If ``True``, estimate the Laguerre alpha parameter from the data.
taus_init : Optional[np.ndarray]
Initial lifetime estimates used to seed exponential fitting.
laser_period_ns : Optional[float]
Laser repetition period in nanoseconds.
reg_strength : float
Regularization weight applied to higher-order Laguerre coefficients.
reg_power : float
Exponent controlling how regularization increases across coefficient order.
nonneg : bool
If ``True``, constrain fitted coefficients or amplitudes to be non-negative.
verbose : bool
If ``True``, report progress and diagnostic messages during processing.
shift_method : str
IRF convolution, as in :func:`pyfli.cm_funcs.forward_model.model_numpy`:
``"zero_pad"`` (linear) or ``"circular"`` (periodic steady state; the window
``T * dt`` must be one laser period).
fit_background : bool
If ``True``, fit a constant per-gate background (the solver's ``v_shift``). With
``shift_method="zero_pad"`` it is an extra linear term next to the Laguerre
coefficients; with ``"circular"`` the circularly convolved Laguerre functions span
a constant, so it is fitted in the exponential stage instead (a constant ``b`` in
the deconvolved kernel is the same ``b`` in the data, the IRF summing to 1).
weighting : str
Weights of the coefficient least squares, as the solver's NLSF
(:func:`~pyfli.reconstruction.common_reconstruct.residual_variance`):
``"irls"`` (Poisson, iteratively reweighted;
:func:`~pyfli.reconstruction.common_reconstruct.irls`), ``"none"`` or
``"neyman"``.
variance_floor, irls_max_rounds, irls_tol : float, int, float
IRLS variance floor (counts), maximum rounds and per-pixel relative tolerance.
excitation : str
Excitation within each IRF gate, ``"bin_start"`` (default) or ``"uniform"``, as
in :func:`pyfli.cm_funcs.forward_model.model_numpy`.
gate_width : float | None
Detection-gate width in ns (``None``: `dt`); only for an IRF not recorded
through the same gate.
Notes
-----
Each pixel's exponential model is the solver's gate-integrated kernel
(:func:`pyfli.cm_funcs.forward_model.gate_integrated_kernel`, periodic for
``"circular"``), ``h[n] = sum_i (S a_i) g_n(tau_i, onset)``, so the amplitudes are
photons and ``photon_count_map``, the ``alpha`` maps (photon fractions) and
``tau_mean_map`` (photon-weighted) follow the solver's definitions; the onset is the
fractional part of ``irf_shift`` (see :meth:`fit`). ``chi2_map``,
``reduced_chi2_map``, ``R2_map`` and ``fit_map`` describe that exponential model
convolved with the IRF (``n_params = 2N``, plus 1 with `fit_background`);
``laguerre_*`` maps describe the Laguerre expansion fit (``n_params`` = the number of
basis functions, plus 1 with `fit_background` for ``"zero_pad"``); both add 1 for a
per-pixel ``irf_shift`` map (see :meth:`fit`).
"""
def __init__(
self,
n_components: int = 2,
n_laguerre: int | None = None,
alpha: float = 0.85,
dt: float = 1.0,
auto_alpha: bool = False,
taus_init: np.ndarray | None = None,
laser_period_ns: float | None = None,
reg_strength: float = 0.0,
reg_power: float = 2.0,
nonneg: bool = True,
verbose: bool = True,
shift_method: str = "zero_pad",
fit_background: bool = False,
weighting: str = "irls",
variance_floor: float = 1.0,
irls_max_rounds: int = 20,
irls_tol: float = 1e-6,
excitation: str = "bin_start",
gate_width: float | None = None,
) -> None:
if n_components < 1:
raise ValueError("n_components must be >= 1.")
if not (0.0 < alpha < 1.0):
raise ValueError("alpha must lie strictly in (0, 1).")
if dt <= 0:
raise ValueError("dt must be positive.")
if laser_period_ns is not None and laser_period_ns <= 0:
raise ValueError("laser_period_ns must be positive.")
self.n_components = int(n_components)
self.n_laguerre = (
int(n_laguerre) if n_laguerre is not None else max(4, 2 * n_components)
)
if self.n_laguerre < self.n_components:
raise ValueError("n_laguerre must be >= n_components.")
self.alpha = float(alpha)
self.dt = float(dt)
self.auto_alpha = bool(auto_alpha)
self.laser_period_ns = (
float(laser_period_ns) if laser_period_ns is not None else None
)
self.taus_init = np.asarray(taus_init, float) if taus_init is not None else None
self.reg_strength = float(reg_strength)
self.reg_power = float(reg_power)
self.nonneg = bool(nonneg)
self.verbose = bool(verbose)
self.shift_method = validate_shift_method(shift_method)
self.excitation = validate_excitation(excitation)
self.gate_width = validate_gate_width(gate_width)
self.fit_background = bool(fit_background)
if weighting not in NLSF_WEIGHTINGS:
raise ValueError(
f"weighting must be one of {NLSF_WEIGHTINGS}, got {weighting!r}"
)
self.weighting = weighting
self.variance_floor = float(variance_floor)
self.irls_max_rounds = int(irls_max_rounds)
self.irls_tol = float(irls_tol)
self._bg_column = self.fit_background and self.shift_method == "zero_pad"
self._bg_in_exp = self.fit_background and self.shift_method == "circular"
self.basis_: np.ndarray | None = None
self.V_: np.ndarray | None = None
self.coeffs_: np.ndarray | None = None
self.taus_: np.ndarray | None = None
self.n_unique_irf_: int | None = None
self.amplitudes_: np.ndarray | None = None
self.fractions_: np.ndarray | None = None
self.tau_mean_: np.ndarray | None = None
self.converged_: np.ndarray | None = None
self.reconstructed_: np.ndarray | None = None
self.residuals_: np.ndarray | None = None
self.fit_curve_: np.ndarray | None = None
self.residual_curve_: np.ndarray | None = None
self.decay_: np.ndarray | None = None
self.irf_lead_: int = 0
self.onset_: np.ndarray = np.zeros((1, 1))
self.background_: np.ndarray | None = None
self.photons_: np.ndarray | None = None
self.photon_fractions_: np.ndarray | None = None
self.exp_fit_curve_: np.ndarray | None = None
@staticmethod
def _discrete_laguerre_basis(T: int, alpha: float, L: int) -> np.ndarray:
"""
Build the discrete Laguerre basis matrix.
Parameters
----------
T : int
Time axis or acquisition period used by the calculation.
alpha : float
Regularization strength, fraction value, or significance threshold used by the
routine.
L : int
Number of Laguerre basis functions or coefficient dimension.
Returns
-------
np.ndarray
Discrete Laguerre basis matrix with basis functions along rows.
"""
b = np.zeros((L, T), dtype=np.float64)
n = np.arange(T)
b[0] = np.sqrt(1.0 - alpha) * alpha ** (n / 2.0)
sa = np.sqrt(alpha)
a_coef = [1.0, -sa]
for j in range(1, L):
prev = b[j - 1]
shifted = np.empty_like(prev)
shifted[0] = 0.0
shifted[1:] = prev[:-1]
u = sa * prev - shifted
b[j] = lfilter([1.0], a_coef, u)
return b
@staticmethod
def _convolve_with_irf(
basis: np.ndarray, irf: np.ndarray, circular: bool = False, lead: int = 0
) -> np.ndarray:
"""
Convolve each Laguerre basis function with the IRF.
Parameters
----------
basis : np.ndarray
Laguerre basis matrix before or after IRF convolution.
irf : np.ndarray
Instrument response function aligned with the decay signal.
circular : bool
Circular instead of linear (truncated) convolution.
lead : int
Linear convolution only: index of time 0 in `irf`, which may extend
``lead`` gates before it (an IRF advanced by a negative shift).
Returns
-------
np.ndarray
Laguerre design matrix after convolution with the IRF.
"""
_, T = basis.shape
irf = np.asarray(irf, float).ravel()
s = irf.sum()
if s > 0:
irf = irf / s
if circular:
return circular_convolve(basis, irf[None, :]).T
full = fftconvolve(basis, irf[None, :], mode="full", axes=1)
return full[:, lead : lead + T].T
def _design(self, basis: np.ndarray, irf: np.ndarray) -> np.ndarray:
"""IRF-convolved Laguerre design matrix ``(T, L)``, plus a constant column with `fit_background`."""
V = self._convolve_with_irf(
basis, irf, self.shift_method == "circular", self.irf_lead_
)
if self._bg_column:
V = np.hstack([V, np.ones((V.shape[0], 1))])
return V
def _design_batch(self, irf_2d: np.ndarray) -> np.ndarray:
"""Per-pixel designs ``(P, T, K)`` for IRFs ``(P, T')``, as :meth:`_design` row by row."""
T = self.basis_.shape[-1]
lead = self.irf_lead_
s = irf_2d.sum(axis=-1, keepdims=True)
irf = np.divide(irf_2d, s, out=irf_2d.astype(float).copy(), where=s > 0)
basis = self.basis_[None]
if self.shift_method == "circular":
conv = circular_convolve(basis, irf[:, None, :])
else:
conv = fftconvolve(basis, irf[:, None, :], mode="full", axes=-1)
conv = conv[..., lead : lead + T]
V = np.swapaxes(conv, -1, -2)
if self._bg_column:
V = np.concatenate([V, np.ones((*V.shape[:-1], 1))], axis=-1)
return V
def _convolve_stack(self, kernel: np.ndarray, irf: np.ndarray) -> np.ndarray:
"""Convolve ``(X, Y, T)`` kernels with a ``(T',)`` or ``(X, Y, T')`` IRF, normalised per pixel."""
T = kernel.shape[-1]
lead = self.irf_lead_
irf = np.asarray(irf, float)
irf = irf[None, None, :] if irf.ndim == 1 else irf
s = irf.sum(-1, keepdims=True)
irf = np.divide(irf, s, out=np.zeros_like(irf), where=s > 0)
if self.shift_method == "circular":
return circular_convolve(kernel, irf)
return fftconvolve(kernel, irf, mode="full", axes=-1)[..., lead : lead + T]
@staticmethod
def _unique_irf_groups(irf_2d: np.ndarray, decimals: int = 6) -> tuple[Any, ...]:
"""
Group pixels that share numerically identical IRFs.
Parameters
----------
irf_2d : np.ndarray
Two-dimensional array of per-pixel IRFs, flattened over pixels by time.
decimals : int
Decimal precision used when grouping IRFs.
Returns
-------
tuple[Any, ...]
Tuple containing the IRF group index for each pixel and representative group
indices.
"""
_, _ = irf_2d.shape
s = irf_2d.sum(axis=1, keepdims=True)
norm = np.divide(irf_2d, s, out=np.zeros_like(irf_2d), where=s > 0)
keys = np.round(norm, decimals)
_, first_idx, inverse = np.unique(
keys, axis=0, return_index=True, return_inverse=True
)
inverse = inverse.ravel()
rep_idx = first_idx.tolist()
return inverse, rep_idx
def _penalty(self, L: int) -> np.ndarray:
"""
Build the coefficient regularization penalty matrix.
Parameters
----------
L : int
Number of Laguerre basis functions or coefficient dimension.
Returns
-------
np.ndarray
Regularization weights for the Laguerre coefficients.
"""
return (np.arange(L, dtype=float) + 1.0) ** self.reg_power
def _solve_coefficients(self, V: np.ndarray, Y2d: np.ndarray) -> np.ndarray:
"""
Solve Laguerre coefficients for all valid decays.
Parameters
----------
V : np.ndarray
Design ``(T, K)`` shared by all decays, or ``(P, T, K)`` per decay.
Y2d : np.ndarray
Decays ``(T, P)``.
Returns
-------
np.ndarray
Coefficients ``(K, P)``, from
:func:`~pyfli.reconstruction.common_reconstruct.weighted_linear_lstsq`
with :attr:`weighting` (IRLS converged per decay).
"""
d = np.asarray(Y2d, dtype=float).T
penalty = None
if self.reg_strength > 0.0:
penalty = self._penalty(self.n_laguerre)
if self.basis_.shape[0] > self.n_laguerre:
penalty = np.append(penalty, 0.0)
if self._bg_column:
penalty = np.append(penalty, 0.0)
def solve(_: Any, variance: np.ndarray | None) -> tuple[np.ndarray, None]:
return (
weighted_linear_lstsq(V, d, variance, penalty, self.reg_strength),
None,
)
def predict(C: np.ndarray) -> np.ndarray:
return C @ V.T if V.ndim == 2 else np.einsum("ptk,pk->pt", V, C)
def row_change(old: np.ndarray, new: np.ndarray) -> np.ndarray:
scale = np.maximum(np.max(np.abs(old), axis=-1), 1e-12)
return np.max(np.abs(new - old), axis=-1) / scale
start = (
residual_variance(None, d, "neyman") if self.weighting == "neyman" else None
)
C, _ = solve(None, start)
if self.weighting == "irls":
C, _ = irls(
solve,
predict,
C,
self.variance_floor,
self.irls_max_rounds,
self.irls_tol,
change=row_change,
)
return C.T
def _optimize_alpha(
self, avg_decay: np.ndarray, avg_irf: np.ndarray, T: int
) -> float:
"""
Optimize the Laguerre alpha value against an average decay.
Parameters
----------
avg_decay : np.ndarray
Average decay trace used during alpha optimization.
avg_irf : np.ndarray
Average IRF used as the representative response for global fitting.
T : int
Time axis or acquisition period used by the calculation.
Returns
-------
float
Floating-point result computed by optimize alpha.
"""
def obj(a: np.ndarray) -> float:
"""
Run the obj routine.
Parameters
----------
a : np.ndarray
Lower integration or interval bound.
Returns
-------
float
Floating-point result computed by obj.
"""
if not (1e-3 < a < 0.999):
return 1e30
B = self._discrete_laguerre_basis(T, float(a), self.n_laguerre)
V = self._design(B, avg_irf)
c, *_ = np.linalg.lstsq(V, avg_decay, rcond=None)
return float(((V @ c - avg_decay) ** 2).sum())
res = minimize_scalar(
obj, bounds=(0.05, 0.98), method="bounded", options={"xatol": 1e-3}
)
return float(res.x)
@staticmethod
def _nnls_safe(E: np.ndarray, h: np.ndarray, maxiter: int) -> np.ndarray:
"""
Solve a non-negative least-squares problem with a fallback path.
Parameters
----------
E : np.ndarray
GUI or plotting event object supplied by the framework.
h : np.ndarray
IRF, image height, or temporal kernel used by the routine.
maxiter : int
Maximum number of optimization iterations.
Returns
-------
np.ndarray
Non-negative least-squares solution, with zeros when fitting fails.
"""
try:
a, _ = nnls(E, h, maxiter=maxiter)
return a
except RuntimeError:
a, *_ = np.linalg.lstsq(E, h, rcond=None)
return np.clip(a, 0.0, None)
def _solve_amps(self, E: np.ndarray, h: np.ndarray, maxiter: int) -> np.ndarray:
"""
Estimate exponential amplitudes for a fixed lifetime set.
Parameters
----------
E : np.ndarray
GUI or plotting event object supplied by the framework.
h : np.ndarray
IRF, image height, or temporal kernel used by the routine.
maxiter : int
Maximum number of optimization iterations.
Returns
-------
np.ndarray
Estimated exponential amplitudes for the supplied lifetimes.
"""
if self.nonneg:
return self._nnls_safe(E, h, maxiter)
a, *_ = np.linalg.lstsq(E, h, rcond=None)
return a
def _tau_bounds(self, T: int) -> tuple[Any, ...]:
"""
Build lifetime bounds for exponential fitting.
Parameters
----------
T : int
Time axis or acquisition period used by the calculation.
Returns
-------
tuple[Any, ...]
Tuple containing lower and upper lifetime bounds.
"""
tau_lo = self.dt
tau_hi = (
self.laser_period_ns if self.laser_period_ns is not None else T * self.dt
)
tau_hi = max(tau_hi, tau_lo + 1e-6)
return tau_lo, tau_hi
def _safe_tau0(self, tau0: np.ndarray, tau_lo: float, tau_hi: float) -> np.ndarray:
"""
Clip an initial lifetime guess into valid bounds.
Parameters
----------
tau0 : np.ndarray
Initial lifetime guess before clipping to valid bounds.
tau_lo : float
Lower lifetime bound.
tau_hi : float
Upper lifetime bound.
Returns
-------
np.ndarray
Initial lifetime estimates clipped to the allowed tau bounds.
"""
return np.clip(tau0, tau_lo + 1e-7, tau_hi - 1e-7)
def _exp_basis(self, T: int, taus: np.ndarray, onset: Any) -> np.ndarray:
"""
Unit-photon gate-integrated exponentials ``(..., N, T)`` with lifetimes `taus`
``(..., N)`` and onset `onset` (ns, broadcast against ``(...)``), as the solver's
:func:`~pyfli.cm_funcs.forward_model.gate_integrated_kernel`.
"""
period = T * self.dt if self.shift_method == "circular" else None
kernel, _ = gate_integrated_kernel(
np.arange(T) * self.dt,
self.dt,
(1.0, np.asarray(taus, dtype=float)[..., None], 0.0),
"mono-exponential",
h_shift=np.asarray(onset, dtype=float)[..., None, None],
period=period,
excitation=self.excitation,
gate_width=self.gate_width,
)
return kernel
def _spike_gates(self, T: int) -> list[int]:
"""
Gates where the exponential kernel is not geometric in the gate index, each given
a unit spike in the Laguerre basis: gates starting before the end of the
excitation window (``onset`` plus ``dt`` for uniform excitation) and, for
``"circular"``, gates reaching the next pulse's onset.
"""
width = self.dt if self.gate_width is None else self.gate_width
reach = float(np.max(self.onset_)) + (
self.dt if self.excitation == "uniform" else 0.0
)
gates = {m for m in range(T) if m * self.dt < reach}
if self.shift_method == "circular" and width > self.dt:
nxt = T * self.dt + float(np.min(self.onset_))
gates |= {m for m in range(T) if m * self.dt + width > nxt}
return sorted(gates)
def _exp_design(self, T: int, taus: np.ndarray, onset: Any) -> np.ndarray:
"""``(T, N)`` exponential design of :meth:`_exp_basis`, plus a constant column when the background is fitted in the exponential stage."""
E = self._exp_basis(T, taus, onset).T
if self._bg_in_exp:
E = np.hstack([E, np.ones((T, 1))])
return E
def _estimate_global_taus(self, h_avg: np.ndarray) -> np.ndarray:
"""
Estimate global taus.
Parameters
----------
h_avg : np.ndarray
Average reconstructed decay used to estimate global lifetimes.
Returns
-------
np.ndarray
Estimated global lifetime values shared across pixels.
"""
T = h_avg.shape[0]
N = self.n_components
tau_lo, tau_hi = self._tau_bounds(T)
if self.taus_init is not None and self.taus_init.size == N:
tau0 = self._safe_tau0(self.taus_init.astype(float), tau_lo, tau_hi)
else:
T_acq = T * self.dt
T_laser = (
self.laser_period_ns if self.laser_period_ns is not None else T_acq
)
t_axis = np.arange(T, dtype=float) * self.dt
model_str = "mono-exponential" if N == 1 else "bi-exponential"
guess = moment_based_guess(t_axis, h_avg, T_acq, T_laser, model_str)
if N == 1:
tau0 = np.array([guess["tau"]])
elif N == 2:
tau0 = np.array([guess["tau1"], guess["tau2"]])
else:
tau_start = guess.get("tau1", 0.05 * T_acq)
tau_end = guess.get("tau2", 0.5 * T_acq)
tau0 = np.geomspace(
max(tau_start, tau_lo), min(tau_end, tau_hi * 0.9), N
)
tau0 = self._safe_tau0(tau0, tau_lo, tau_hi)
def residual(params: Any) -> Any:
"""
Run the residual routine.
Parameters
----------
params : Any
Model, detector, or plotting parameters used by the routine.
Returns
-------
Any
Object produced by residual.
"""
E = self._exp_design(T, params, np.median(self.onset_))
a = self._solve_amps(E, h_avg, 200 * N)
return E @ a - h_avg
res = least_squares(
residual,
tau0,
method="trf",
bounds=([tau_lo] * N, [tau_hi] * N),
max_nfev=2000,
)
return np.sort(np.clip(np.abs(res.x), tau_lo, tau_hi))
def _fit_pixel_exponentials(
self,
h_stack: np.ndarray,
tau_init: np.ndarray,
mask: np.ndarray | None = None,
) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
"""
Fit pixel exponentials.
Parameters
----------
h_stack : np.ndarray
Stack of reconstructed decays fitted pixel by pixel.
tau_init : np.ndarray
Initial lifetime vector for pixel-wise exponential fitting.
mask : Optional[np.ndarray]
Boolean or labeled mask selecting pixels for the operation.
Returns
-------
tuple[np.ndarray, np.ndarray, np.ndarray]
Per-pixel fitted amplitudes, fractions, lifetimes, and convergence flags.
"""
X, Y, T = h_stack.shape
N = self.n_components
tau_lo, tau_hi = self._tau_bounds(T)
tau_init_safe = self._safe_tau0(tau_init, tau_lo, tau_hi)
bounds = ([tau_lo] * N, [tau_hi] * N)
taus_map = np.zeros((X, Y, N), dtype=np.float64)
amps_map = np.zeros((X, Y, N + int(self._bg_in_exp)), dtype=np.float64)
converged_map = np.zeros((X, Y), dtype=np.float32)
total_px = int(mask.sum()) if mask is not None else X * Y
with tqdm(
total=total_px,
desc=" Pixels",
unit="px",
leave=False,
disable=not self.verbose,
) as pbar:
for x in range(X):
for y in range(Y):
if mask is not None and not mask[x, y]:
continue
h = h_stack[x, y, :]
if h.sum() >= 1e-10:
onset = self.onset_[x, y]
def residual(
params: Any, h: np.ndarray = h, onset: float = onset
) -> Any:
E = self._exp_design(T, params, onset)
a = self._solve_amps(E, h, 200 * N)
return E @ a - h
try:
res = least_squares(
residual,
tau_init_safe.copy(),
method="trf",
bounds=bounds,
max_nfev=1000,
)
taus_px = np.sort(np.clip(np.abs(res.x), tau_lo, tau_hi))
converged_map[x, y] = float(res.success)
except Exception:
taus_px = tau_init_safe.copy()
converged_map[x, y] = 0.0
E_px = self._exp_design(T, taus_px, onset)
taus_map[x, y, :] = taus_px
amps_map[x, y, :] = self._solve_amps(E_px, h, 200 * N)
pbar.update(1)
return taus_map, amps_map, converged_map
[docs]
def fit(
self,
decay: np.ndarray,
irf: np.ndarray,
mask: np.ndarray | None = None,
irf_shift: float | np.ndarray | None = None,
h_shift: float | np.ndarray | None = None,
) -> "LaguerreFLI":
"""
Fit the model to decay and IRF data.
Parameters
----------
decay : np.ndarray
Time-resolved decay signal or decay cube.
irf : np.ndarray
Instrument response function aligned with the decay signal.
mask : Optional[np.ndarray]
Boolean or labeled mask selecting pixels for the operation.
irf_shift : float | np.ndarray | None
IRF delay in gates, scalar or ``(X, Y)``, e.g. from
:meth:`pyfli.data_cc.irfAligner.IRFAligner.estimate_shift_debiased` or
:meth:`~pyfli.data_cc.irfAligner.IRFAligner.estimate_shift_rmse` (positive
when the decay starts later). The IRF is delayed by it
by its whole gates (floor) and the remaining fraction ``f`` in ``[0, 1)``
is the onset of the exponential kernel, which together are exactly the
solver's onset ``h_shift = irf_shift * dt``, reported as ``h_shift_map``.
With ``f > 0`` the kernel is geometric from gate 1 and differs only in gate
0, so a unit spike at gate 0 is added to the Laguerre basis (one more
expansion coefficient) to represent it exactly. A per-pixel map counts as
one fitted parameter.
h_shift : float | np.ndarray | None
The same offset in the solver's convention, in ns (scalar or ``(X, Y)``):
``HarmonicOffset.estimate()["h_shift_map"]``
(:mod:`pyfli.phasor.harmonic_offset`), a solver fit's ``h_shift_map``, or
any other estimate; used as ``irf_shift = h_shift / dt``. Give at most one
of `irf_shift` and `h_shift`.
Returns
-------
'LaguerreFLI'
Object produced by fit.
"""
decay = np.asarray(decay, dtype=np.float64)
irf = np.asarray(irf, dtype=np.float64)
if decay.ndim == 1:
decay = decay[None, None, :]
if decay.ndim != 3:
raise ValueError("decay must have shape (X, Y, T) or (T,).")
X, Y, T = decay.shape
self.decay_ = decay.astype(np.float32)
if (
irf.shape != decay.shape
if irf.ndim == 3
else not (irf.ndim == 1 and irf.shape[0] == T)
):
raise ValueError("irf must be (T,) or match the decay shape (X, Y, T).")
self.h_shift_ = np.zeros((X, Y))
self.n_shift_params_ = 0
self.irf_lead_ = 0
self.onset_ = np.zeros((X, Y))
if h_shift is not None:
if irf_shift is not None:
raise ValueError("give at most one of irf_shift and h_shift.")
irf_shift = np.asarray(h_shift, dtype=float) / self.dt
wide_lags = (
negative_lag_gates(0.0, self.dt, self.gate_width)
if self.shift_method == "zero_pad"
else 0
)
if wide_lags and irf_shift is None:
irf_shift = 0.0
if irf_shift is not None:
shift = np.asarray(irf_shift, dtype=float)
if shift.ndim not in (0, 2) or (shift.ndim == 2 and shift.shape != (X, Y)):
raise ValueError(f"irf_shift must be a scalar or ({X}, {Y}) map.")
if shift.ndim == 2 and irf.ndim == 1:
irf = np.broadcast_to(irf, (X, Y, T))
fraction = shift - np.floor(shift)
whole = np.floor(shift) - wide_lags
if self.shift_method == "zero_pad":
self.irf_lead_ = int(max(-whole.min(), 0.0))
trail = int(max(whole.max(), 0.0))
pad = [(0, 0)] * (irf.ndim - 1) + [(self.irf_lead_, trail)]
irf = np.pad(irf, pad)
irf = fourier_shift(irf, whole)
self.onset_ = np.broadcast_to(
(fraction + wide_lags) * self.dt, (X, Y)
).astype(float)
self.h_shift_ = np.broadcast_to(shift * self.dt, (X, Y)).astype(float)
self.n_shift_params_ = int(shift.ndim == 2)
self.irf_ = irf
if (
self.shift_method == "circular"
and self.laser_period_ns is not None
and not np.isclose(T * self.dt, self.laser_period_ns)
):
raise ValueError(
"shift_method='circular' needs T * dt to equal laser_period_ns, got "
f"{T * self.dt} ns vs {self.laser_period_ns} ns"
)
if mask is not None:
mask = np.asarray(mask, dtype=bool)
if mask.shape != (X, Y):
raise ValueError(
f"mask shape {mask.shape} must match image shape ({X}, {Y})."
)
self.mask_ = mask
ppirf = irf.ndim == 3
decay_flat = decay.reshape(-1, T)
if mask is not None:
avg_decay = decay_flat[mask.ravel()].mean(0)
else:
avg_decay = decay_flat.mean(0)
if ppirf:
irf_2d = irf.reshape(-1, irf.shape[-1])
_, rep_idx = self._unique_irf_groups(irf_2d)
self.n_unique_irf_ = len(rep_idx)
else:
self.n_unique_irf_ = 1
single_irf = (not ppirf) or self.n_unique_irf_ == 1
if not ppirf:
alpha_irf = irf
elif self.n_unique_irf_ == 1:
alpha_irf = irf_2d[rep_idx[0]]
else:
alpha_irf = irf_2d.mean(0)
with tqdm(
total=5, desc="LaguerreFLI", unit="stage", disable=not self.verbose
) as pbar:
pbar.set_description("Building Laguerre basis")
if self.auto_alpha:
self.alpha = self._optimize_alpha(avg_decay, alpha_irf, T)
self.basis_ = self._discrete_laguerre_basis(T, self.alpha, self.n_laguerre)
spikes = self._spike_gates(T)
if spikes:
spike = np.zeros((len(spikes), T))
spike[np.arange(len(spikes)), spikes] = 1.0
self.basis_ = np.vstack([self.basis_, spike])
n_basis = self.basis_.shape[0]
pbar.update(1)
pbar.set_description("Solving Laguerre coefficients")
Y2d = decay_flat.T
if single_irf:
self.V_ = self._design(self.basis_, alpha_irf)
C = self._solve_coefficients(self.V_, Y2d)
model_y = (self.V_ @ C).T.reshape(X, Y, T)
else:
P = Y2d.shape[1]
self.V_ = None
C = np.zeros((n_basis + self._bg_column, P), dtype=np.float64)
fit_2d = np.zeros((P, T), dtype=np.float64)
for start in range(0, P, 1024):
cols = slice(start, start + 1024)
Vb = self._design_batch(irf_2d[cols])
Cb = self._solve_coefficients(Vb, Y2d[:, cols])
C[:, cols] = Cb
fit_2d[cols] = np.einsum("ptk,kp->pt", Vb, Cb)
model_y = fit_2d.reshape(X, Y, T)
self.background_ = (
C[-1].reshape(X, Y) if self._bg_column else np.zeros((X, Y))
)
C = C[:n_basis]
self.coeffs_ = C.T.reshape(X, Y, n_basis)
self.fit_curve_ = model_y
self.residual_curve_ = decay - model_y
self.residuals_ = (self.residual_curve_**2).sum(-1)
h_stack = (self.basis_.T @ C).T.reshape(X, Y, T)
self.reconstructed_ = h_stack
pbar.update(1)
pbar.set_description("Estimating global lifetimes")
h_flat = h_stack.reshape(-1, T)
h_avg = h_flat[mask.ravel()].mean(0) if mask is not None else h_flat.mean(0)
taus_init = self._estimate_global_taus(h_avg)
pbar.update(1)
pbar.set_description("Fitting per-pixel exponentials")
self.taus_, A, self.converged_ = self._fit_pixel_exponentials(
h_stack, taus_init, mask=mask
)
if self._bg_in_exp:
self.background_ = A[..., -1]
A = A[..., :-1]
self.amplitudes_ = A
tau_safe = np.where(self.taus_ > 0, self.taus_, 1.0)
density = A / tau_safe
total_density = density.sum(axis=-1, keepdims=True)
with np.errstate(invalid="ignore", divide="ignore"):
self.fractions_ = np.where(
total_density > 0, density / total_density, 0.0
)
pbar.update(1)
pbar.set_description("Computing lifetime maps")
self.photons_ = A
total_photons = self.photons_.sum(axis=-1, keepdims=True)
with np.errstate(invalid="ignore", divide="ignore"):
self.photon_fractions_ = np.where(
total_photons > 0, self.photons_ / total_photons, 0.0
)
self.tau_mean_ = (self.photon_fractions_ * self.taus_).sum(axis=-1)
kernel = np.einsum(
"xyi,xyin->xyn", A, self._exp_basis(T, tau_safe, self.onset_)
)
self.exp_fit_curve_ = (
self._convolve_stack(kernel, irf) + self.background_[..., None]
)
pbar.update(1)
return self
[docs]
def get_parameters(self, data_name: str = "LaguerreFLI_Dataset") -> dict:
"""
Return parameters.
Parameters
----------
data_name : str
Label assigned to the fitted or processed dataset.
Returns
-------
dict
Dictionary containing the data produced by get parameters.
"""
if self.coeffs_ is None:
raise RuntimeError("Call .fit(decay, irf) first.")
N = self.n_components
X, Y = self.tau_mean_.shape
T = self.reconstructed_.shape[-1]
decay_d = self.decay_.astype(np.float64)
exp_fit = self.exp_fit_curve_.astype(np.float64)
lag_fit = self.fit_curve_.astype(np.float64)
sdf_map = self.reconstructed_.astype(np.float32)
photon_count = self.photons_.sum(axis=-1).astype(np.float32)
n_params = 2 * N + int(self.fit_background) + self.n_shift_params_
n_params_laguerre = (
self.basis_.shape[0] + int(self._bg_column) + self.n_shift_params_
)
chi_sq_raw, chi_sq_reduced = reduced_poisson_deviance(
exp_fit, decay_d, n_params
)
lag_chi_raw, lag_chi_reduced = reduced_poisson_deviance(
lag_fit, decay_d, n_params_laguerre
)
pearson_raw = pearson_chi_square(exp_fit, decay_d).astype(np.float32)
dof = degrees_of_freedom(T, n_params)
residuals_d = decay_d - exp_fit
r2_map = r_squared(residuals_d, decay_d).astype(np.float32)
pixel_health = (photon_count > 0).astype(np.float32)
if N == 1:
tau_maps = {"tau_map": self.taus_[..., 0].astype(np.float32)}
alpha_maps = {
"alpha_map": self.photon_fractions_[..., 0].astype(np.float32)
}
else:
tau_maps = {
f"tau{i + 1}_map": self.taus_[..., i].astype(np.float32)
for i in range(N)
}
alpha_maps = {
f"alpha{i + 1}_map": self.photon_fractions_[..., i].astype(np.float32)
for i in range(N)
}
if N >= 2:
tau1_m = self.taus_[..., 0]
tau2_m = self.taus_[..., 1]
fret_eff = np.where(tau2_m > 0, 1.0 - tau1_m / tau2_m, 0.0).astype(
np.float32
)
else:
fret_eff = np.zeros((X, Y), dtype=np.float32)
convergence = (
self.converged_.astype(np.float32)
if self.converged_ is not None
else pixel_health.copy()
)
maps = {
**tau_maps,
**alpha_maps,
"photon_count_map": photon_count,
"tau_mean_map": self.tau_mean_.astype(np.float32),
"v_shift_map": self.background_.astype(np.float32),
"h_shift_map": self.h_shift_.astype(np.float32),
"fret_efficiency_map": fret_eff,
"R2_map": r2_map,
"chi2_map": chi_sq_raw.astype(np.float32),
"reduced_chi2_map": chi_sq_reduced.astype(np.float32),
"pearson_chi2_map": pearson_raw,
"pearson_reduced_chi2_map": (pearson_raw / dof).astype(np.float32),
"laguerre_chi2_map": lag_chi_raw.astype(np.float32),
"laguerre_reduced_chi2_map": lag_chi_reduced.astype(np.float32),
"convergence_map": convergence,
"pixel_health_map": pixel_health,
}
internal_popt_len = 2 * N + 2
error_maps = np.zeros((X, Y, internal_popt_len), dtype=np.float32)
tr_maps = {
"fit_map": exp_fit.astype(np.float32),
"residual_map": residuals_d.astype(np.float32),
"laguerre_fit_map": lag_fit.astype(np.float32),
"laguerre_residual_map": (decay_d - lag_fit).astype(np.float32),
"sdf_map": sdf_map,
}
mask = photon_count > 0
mean_chi_sq = float(chi_sq_reduced[mask].mean()) if mask.any() else float("nan")
logging.info(f"Mean Reduced Chi-Squared (Active Pixels): {mean_chi_sq:.4f}")
return {
"name": data_name,
"method": f"LaguerreFLI_{N}exp",
"results": {
"maps": maps,
"error_maps": error_maps,
"TR_maps": tr_maps,
},
}
[docs]
def save_results(self, dataset: dict, folder: str = "results") -> None:
"""
Save results.
Parameters
----------
dataset : dict
Dataset dictionary or fit result collection to save.
folder : str
Output directory used when saving results.
Returns
-------
None
No object is returned; the function save results.
"""
if dataset is None:
return
os.makedirs(folder, exist_ok=True)
h5_path = os.path.join(folder, f"{dataset['name']}_results.h5")
with h5py.File(h5_path, "w") as f:
f.attrs["method"] = dataset["method"]
res_grp = f.create_group("results")
maps_grp = res_grp.create_group("maps")
for k, v in dataset["results"]["maps"].items():
maps_grp.create_dataset(
k, data=v, compression="gzip", compression_opts=4
)
res_grp.create_group("error_maps").create_dataset(
"errors",
data=dataset["results"]["error_maps"],
compression="gzip",
compression_opts=4,
)
tr_grp = res_grp.create_group("TR_maps")
for k, v in dataset["results"]["TR_maps"].items():
tr_grp.create_dataset(k, data=v, compression="gzip", compression_opts=4)
logging.info(f"Analysis complete. Results saved to: {h5_path}")
[docs]
def load_map(self, h5_path: str, map_name: str = "tau1_map") -> np.ndarray | None:
"""
Load a map from a .h5 file.
Parameters
----------
h5_path : str
Filesystem path used by the routine.
map_name : str
Name of the saved parameter map to load.
Returns
-------
Optional[np.ndarray]
Map array loaded from disk.
"""
import h5py
with h5py.File(h5_path, "r") as f:
key = f"results/maps/{map_name}"
if key in f:
return f[key][()]
logging.warning(f"Map '{map_name}' not found in {h5_path}")
return None
[docs]
def predict(self) -> np.ndarray:
"""
Return reconstructed value.
Returns
-------
np.ndarray
Reconstructed decay array predicted from the fitted Laguerre model.
"""
if self.reconstructed_ is None:
raise RuntimeError("Call .fit(decay, irf) first.")
return self.reconstructed_
def __repr__(self) -> str:
period = (
f"{self.laser_period_ns} ns"
if self.laser_period_ns is not None
else "not set"
)
return (
f"LaguerreFLI(n_components={self.n_components}, "
f"n_laguerre={self.n_laguerre}, alpha={self.alpha:.3f}, "
f"dt={self.dt} ns, laser_period={period}, "
f"reg_strength={self.reg_strength})"
)