Source code for pyfli.phasor.harmonic_offset

"""
Fit-free pixelwise IRF-decay timing offset ``t0`` from multi-harmonic phasors: mono
estimate, bracket for any completely monotone decay, chi-square selection and correction.
"""

from typing import Any

import numpy as np
from joblib import Parallel, delayed
from numpy.typing import ArrayLike
from scipy.optimize import least_squares
from scipy.stats import chi2 as chi2_dist

from pyfli.cm_stats.chi_square import degrees_of_freedom
from pyfli.reconstruction.common_reconstruct import gate_starts

from .phasorS.phasor_locus_tools import _omega_rad_per_ns, modulation_lifetime
from .phasorS.phasor_simple import PhasorAnalyzer

_EPS = 1e-12


def _harmonic_axis(z: np.ndarray) -> np.ndarray:
    return np.arange(1, z.shape[0] + 1).reshape((-1,) + (1,) * (z.ndim - 1))


def _clipped_modulation(z: np.ndarray) -> np.ndarray:
    return np.clip(np.abs(z), 0.0, 1.0)


[docs] def harmonic_phasors( analyzer: PhasorAnalyzer, decay: ArrayLike, n_harmonics: int | None = None ) -> np.ndarray: """ Raw complex phasors ``G + iS`` of `decay` at harmonics ``1..n_harmonics``, from :meth:`PhasorAnalyzer.create_phasor_cpu`. Returns ------- np.ndarray ``(n_harmonics,) + decay.shape[:-1]``; `n_harmonics` defaults to the analyzer's. """ if n_harmonics is not None and n_harmonics != analyzer.n_harmonics: analyzer = PhasorAnalyzer( analyzer.frequency, analyzer.time_axis_ns, n_harmonics, device="cpu" ) G, S = analyzer.create_phasor_cpu(decay) return np.asarray(G) + 1j * np.asarray(S)
[docs] def calibrate_phasors(z_raw: ArrayLike, z_irf: ArrayLike) -> np.ndarray: """ Calibrated phasors ``z_k = z~_k / z~^I_k`` (as :meth:`PhasorAnalyzer.calibrate`) for the harmonics of `z_raw` ``(K, ...)``; `z_irf` is ``(>= K,)`` or ``(>= K, ...)``. """ z_raw = np.asarray(z_raw, dtype=complex) z_irf = np.asarray(z_irf, dtype=complex)[: z_raw.shape[0]] if z_irf.ndim == 1: z_irf = z_irf.reshape((-1,) + (1,) * (z_raw.ndim - 1)) with np.errstate(divide="ignore", invalid="ignore"): return z_raw / z_irf
[docs] def unwrap_phases( z: ArrayLike, frequency_hz: float, t0_guess_ns: ArrayLike = 0.0 ) -> np.ndarray: """ Phases ``phi_k`` of calibrated phasors ``z`` ``(K, ...)``, unwrapped beyond the principal value. Since ``phi_k`` lies in ``[k omega t0, k omega t0 + pi/2)``, each harmonic is taken within ``pi`` of ``k omega (L + U) / 2 + pi/4``, the centre of the bracket ``[L, U]`` of eq. 7 built from the lower harmonics; this is unique while ``k omega (U - L) < 3 pi / 2``. Unwrapping against ``k phi_1`` (paper section 9) instead fails for long lifetimes at ``k >= 4``. Harmonic 1 is centred on `t0_guess_ns` and needs ``|t0 - t0_guess| < 3T/8``. """ z = np.asarray(z, dtype=complex) w = _omega_rad_per_ns(frequency_hz, 1) m = _clipped_modulation(z) phi = np.empty(z.shape) lower = np.full(z.shape[1:], -np.inf) upper = np.full(z.shape[1:], np.inf) ref = w * np.asarray(t0_guess_ns, dtype=float) + np.pi / 4 for h in range(z.shape[0]): kw = (h + 1) * w if h: ref = kw * (lower + upper) / 2 + np.pi / 4 phi[h] = np.angle(z[h] * np.exp(-1j * ref)) + ref lower = np.maximum(lower, (phi[h] - np.arccos(m[h])) / kw) upper = np.minimum(upper, phi[h] / kw) return phi
[docs] def mono_offset( z: ArrayLike, frequency_hz: float, t0_guess_ns: ArrayLike = 0.0 ) -> tuple[np.ndarray, np.ndarray]: """ Per-harmonic mono-exponential offset and lifetime (paper eq. 6), ``t0_k = (phi_k - arccos m_k) / (k omega)`` and ``tau_k = sqrt(m_k^-2 - 1) / (k omega)``. Returns ------- tuple[np.ndarray, np.ndarray] ``(t0_k, tau_k)`` in ns, each ``(K, ...)``. Moduli above 1 are clipped to 1. """ z = np.asarray(z, dtype=complex) k = _harmonic_axis(z) w = _omega_rad_per_ns(frequency_hz, 1) phi = unwrap_phases(z, frequency_hz, t0_guess_ns) t0_k = (phi - np.arccos(_clipped_modulation(z))) / (k * w) tau_k = np.stack( [ modulation_lifetime(zk.real, zk.imag, frequency_hz, h + 1) for h, zk in enumerate(z) ] ) return t0_k, tau_k
[docs] def offset_bracket( z: ArrayLike, frequency_hz: float, t0_guess_ns: ArrayLike = 0.0 ) -> tuple[np.ndarray, np.ndarray]: """ Two-sided bracket ``max_k t0_k <= t0 <= min_k phi_k / (k omega)`` (paper eq. 7), valid for every completely monotone decay when ``c = 1``. The upper bound holds for any ``c > 0``. """ z = np.asarray(z, dtype=complex) k = _harmonic_axis(z) w = _omega_rad_per_ns(frequency_hz, 1) t0_k, _ = mono_offset(z, frequency_hz, t0_guess_ns) upper = unwrap_phases(z, frequency_hz, t0_guess_ns) / (k * w) return t0_k.max(axis=0), upper.min(axis=0)
[docs] def phasor_noise( z_raw: ArrayLike, z_irf: ArrayLike, n_photons: ArrayLike, n_harmonics: int, excess_noise: float = 1.0, ) -> dict[str, np.ndarray]: """ Shot-noise covariance of the calibrated phasors in each phasor's own rotated frame ``X + iY = e^{-i phi_k} z_k`` (paper eq. 8), including the cross-harmonic terms that involve ``z_{k+l}`` and ``z_{k-l}``. Parameters ---------- z_raw : array_like Raw (uncalibrated) sample phasors ``(>= 2K, ...)``. z_irf : array_like Raw IRF phasors ``(>= K,)`` or ``(>= K, ...)``. n_photons : array_like Detected counts per pixel (background included), shape ``(...)``. n_harmonics : int ``K``. excess_noise : float Variance multiplier: ICCD excess-noise factor times counts per photon. Returns ------- dict[str, np.ndarray] ``"XX"``, ``"YY"``, ``"XY"`` (``Cov(X_k, Y_l)``), ``"YX"``, each ``(..., K, K)``, and ``"m"``, the calibrated moduli ``(..., K)``. """ K = int(n_harmonics) z_raw = np.asarray(z_raw, dtype=complex) if z_raw.shape[0] < 2 * K: raise ValueError( f"z_raw needs at least {2 * K} harmonics, got {z_raw.shape[0]}" ) p = np.moveaxis(z_raw[: 2 * K], 0, -1) full = np.concatenate([np.conj(p[..., ::-1]), np.ones_like(p[..., :1]), p], axis=-1) k = np.arange(1, K + 1) pk = p[..., :K] rot = np.exp(-1j * np.angle(pk)) uv = ( full[..., 2 * K + k[:, None] + k[None, :]] - pk[..., :, None] * pk[..., None, :] ) uv = uv * rot[..., :, None] * rot[..., None, :] uvc = full[..., 2 * K + k[:, None] - k[None, :]] - pk[..., :, None] * np.conj( pk[..., None, :] ) uvc = uvc * rot[..., :, None] * np.conj(rot[..., None, :]) irf_mod = np.moveaxis(np.abs(np.asarray(z_irf, dtype=complex)[:K]), 0, -1) scale = excess_noise / ( np.asarray(n_photons, dtype=float)[..., None, None] * irf_mod[..., :, None] * irf_mod[..., None, :] ) return { "XX": 0.5 * (uv + uvc).real * scale, "YY": 0.5 * (uvc - uv).real * scale, "XY": 0.5 * (uv.imag - uvc.imag) * scale, "YX": 0.5 * (uv.imag + uvc.imag) * scale, "m": np.abs(pk) / irf_mod, }
[docs] def offset_covariance( noise: dict[str, np.ndarray], frequency_hz: float, include_lifetime: bool = False ) -> np.ndarray: """ Delta-method covariance of the per-harmonic offsets ``t0_k`` (paper eq. 9, with the full ``K x K`` cross-harmonic form), from :func:`phasor_noise`. With `include_lifetime`, the joint covariance of ``(t0_1..t0_K, tau_1..tau_K)``, using ``d tau_k = -dX_k / (k omega m_k^2 sqrt(1 - m_k^2))``. Returns ------- np.ndarray ``(..., K, K)``, or ``(..., 2K, 2K)`` with `include_lifetime`, in ns^2. """ m = np.clip(noise["m"], _EPS, 1.0 - _EPS) K = m.shape[-1] kw = np.arange(1, K + 1) * _omega_rad_per_ns(frequency_hz, 1) s = np.sqrt(1.0 - m**2) eye = np.eye(K) jac = np.concatenate( [eye / (kw * s)[..., None, :], eye / (kw * m)[..., None, :]], axis=-1 ) if include_lifetime: tau_x = -eye / (kw * m**2 * s)[..., None, :] tau_rows = np.concatenate([tau_x, np.zeros(tau_x.shape)], axis=-1) jac = np.concatenate([jac, tau_rows], axis=-2) sigma = np.concatenate( [ np.concatenate([noise["XX"], noise["XY"]], axis=-1), np.concatenate([noise["YX"], noise["YY"]], axis=-1), ], axis=-2, ) return jac @ sigma @ np.swapaxes(jac, -1, -2)
[docs] def combine_offsets( t0_k: ArrayLike, cov: ArrayLike, full_covariance: bool = True, tau_k: ArrayLike | None = None, ) -> dict[str, Any]: """ Generalised least-squares mono-exponential test across harmonics (paper eq. 10). With `t0_k` only, one parameter ``t0`` on ``K`` observations (``dof = K - 1``); with `tau_k` and a joint `cov` from ``offset_covariance(..., include_lifetime=True)``, two parameters ``(t0, tau)`` on ``2K`` observations (``dof = 2K - 2``), which also tests that the modulation lifetimes agree. ``full_covariance=False`` drops the cross terms. Returns ------- dict[str, Any] ``"t0"``, ``"t0_se"``, ``"tau"`` and ``"tau_se"`` (``None`` without `tau_k`), ``"chi2"``, ``"reduced_chi2"`` (``chi2 / dof``), ``"dof"`` and ``"n_params"``. Pixels with non-finite inputs are ``NaN``. """ y = np.moveaxis(np.asarray(t0_k, dtype=float), 0, -1) K = y.shape[-1] n_params = 1 if tau_k is None else 2 if tau_k is not None: y = np.concatenate([y, np.moveaxis(np.asarray(tau_k, dtype=float), 0, -1)], -1) n = y.shape[-1] C = np.asarray(cov, dtype=float) if C.shape[-1] != n: raise ValueError(f"cov is {C.shape[-1]}x{C.shape[-1]}, expected {n}x{n}") if not full_covariance: C = np.eye(n) * np.diagonal(C, axis1=-2, axis2=-1)[..., None, :] bad = ~(np.isfinite(y).all(-1) & np.isfinite(C).all((-2, -1))) C = np.where(bad[..., None, None], np.eye(n), C) y = np.where(bad[..., None], 0.0, y) design = np.zeros((n, n_params)) design[:K, 0] = 1.0 design[K:, n_params - 1] = 1.0 cinv_a = np.linalg.solve(C, np.broadcast_to(design, C.shape[:-2] + design.shape)) fisher_inv = np.linalg.inv(design.T @ cinv_a) beta = (fisher_inv @ (np.swapaxes(cinv_a, -1, -2) @ y[..., None]))[..., 0] r = y - beta @ design.T chi2 = (r * np.linalg.solve(C, r[..., None])[..., 0]).sum(-1) nan = np.where(bad, np.nan, 1.0) se = np.sqrt(np.diagonal(fisher_inv, axis1=-2, axis2=-1)) * nan[..., None] dof = degrees_of_freedom(n, n_params, None) return { "t0": beta[..., 0] * nan, "t0_se": se[..., 0], "tau": None if tau_k is None else beta[..., 1] * nan, "tau_se": None if tau_k is None else se[..., 1], "chi2": chi2 * nan, "reduced_chi2": chi2 * nan / dof, "dof": dof, "n_params": n_params, }
[docs] def select_mono(chi2: ArrayLike, dof: int, alpha: float = 0.05) -> np.ndarray: """ Pixels consistent with the offset model: ``chi2 < chi2_{dof, 1-alpha}`` (``dof`` from :func:`combine_offsets` or :func:`bi_exponential_offset`). """ with np.errstate(invalid="ignore"): return np.asarray(chi2) < chi2_dist.ppf(1.0 - alpha, dof)
def _bi_pixel(zk, rot, whiten, w, lo, up, margin): k = np.arange(1, zk.size + 1) * w def residual(p): t0, l1, l2, a = p model = np.exp(1j * k * t0) * ( a / (1 - 1j * k * np.exp(l1)) + (1 - a) / (1 - 1j * k * np.exp(l2)) ) d = (zk - model) / rot return whiten @ np.concatenate([d.real, d.imag]) low = [lo - margin, np.log(0.02), np.log(0.05), 0.0] high = [up + margin, np.log(30.0), np.log(50.0), 1.0] best = None for t0 in (lo, 0.5 * (lo + up)): for l1, l2 in ((np.log(0.3), np.log(3.0)), (np.log(0.8), np.log(4.0))): res = least_squares(residual, [t0, l1, l2, 0.5], bounds=(low, high)) if best is None or res.cost < best.cost: best = res t0, l1, l2, a = best.x if l1 > l2: l1, l2, a = l2, l1, 1.0 - a cov = np.linalg.pinv(best.jac.T @ best.jac) return t0, np.sqrt(max(cov[0, 0], 0.0)), np.exp(l1), np.exp(l2), a, 2.0 * best.cost
[docs] def bi_exponential_offset( z: ArrayLike, noise: dict[str, np.ndarray], frequency_hz: float, t0_guess_ns: ArrayLike = 0.0, margin_ns: float = 0.1, n_jobs: int = -1, ) -> dict[str, Any]: """ Per-pixel offset of a bi-exponential decay from ``K >= 3`` harmonics. Theorem 1 makes ``t0`` unidentifiable for an arbitrary completely monotone decay, but under the bi-exponential model ``z_k = e^{i k omega t0} (A / (1 - i k omega tau1) + (1 - A) / (1 - i k omega tau2))`` the ``2K`` real data determine the four unknowns ``(t0, tau1, tau2, A)``. Each pixel is fitted by weighted least squares, whitened by the shot-noise covariance of :func:`phasor_noise`, with ``t0`` inside its bracket (:func:`offset_bracket`) widened by `margin_ns`. ``A = 1`` is the mono estimate. Returns ------- dict[str, Any] ``"t0"``, ``"t0_se"``, ``"tau1"``, ``"tau2"``, ``"alpha1"`` (photon fraction of ``tau1``), ``"chi2"`` and ``"reduced_chi2"``, each ``(...)`` (``NaN`` where the noise is undefined), ``"dof"`` = ``2K - 4`` and ``"n_params"`` = 4. """ z = np.asarray(z, dtype=complex) K = z.shape[0] if K < 3: raise ValueError("the bi-exponential offset needs at least 3 harmonics") w = _omega_rad_per_ns(frequency_hz, 1) lower, upper = offset_bracket(z, frequency_hz, t0_guess_ns) sigma = np.concatenate( [ np.concatenate([noise["XX"], noise["XY"]], axis=-1), np.concatenate([noise["YX"], noise["YY"]], axis=-1), ], axis=-2, ) spatial = z.shape[1:] zf = np.moveaxis(z, 0, -1).reshape(-1, K) sf = sigma.reshape(-1, 2 * K, 2 * K) lo, up = lower.ravel(), upper.ravel() ok = np.isfinite(zf).all(-1) & np.isfinite(sf).all((-2, -1)) & np.isfinite(lo + up) idx = np.flatnonzero(ok) def run(i): try: whiten = np.linalg.cholesky(np.linalg.inv(sf[i])).T except np.linalg.LinAlgError: return (np.nan,) * 6 return _bi_pixel( zf[i], np.exp(1j * np.angle(zf[i])), whiten, w, lo[i], up[i], margin_ns ) rows = Parallel(n_jobs=n_jobs)(delayed(run)(i) for i in idx) out = np.full((zf.shape[0], 6), np.nan) if rows: out[idx] = np.asarray(rows) dof = degrees_of_freedom(2 * K, 4, None) keys = ("t0", "t0_se", "tau1", "tau2", "alpha1", "chi2") result = {key: out[:, i].reshape(spatial) for i, key in enumerate(keys)} result.update({"reduced_chi2": result["chi2"] / dof, "dof": dof, "n_params": 4}) return result
[docs] def imbalance_offset( z: ArrayLike, frequency_hz: float, noise: dict[str, np.ndarray] | None = None, t0_guess_ns: ArrayLike = 0.0, ) -> dict[str, np.ndarray]: """ Closed-form ``c``, ``tau`` and ``t0`` under modulation imbalance ``c != 1`` (paper eq. 12): weighted least squares of ``1 / m_k^2 = P + Q k^2``. Parameters ---------- z : array_like Calibrated phasors ``(K >= 2, ...)``. frequency_hz : float Laser repetition frequency in hertz. noise : dict | None :func:`phasor_noise` output; gives inverse-variance weights and makes ``chi2`` (``K - 2`` degrees of freedom) a test of constant ``c``. Unweighted if ``None``. t0_guess_ns : array_like See :func:`unwrap_phases`. Returns ------- dict[str, np.ndarray] ``"c"``, ``"tau"`` (ns), ``"t0"`` (ns, weighted mean of ``"t0_k"``), ``"t0_k"`` ``(K, ...)``, ``"chi2"``, ``"reduced_chi2"`` (``NaN`` for ``K = 2``), ``"dof"`` and ``"n_params"`` (``P``, ``Q``). """ z = np.asarray(z, dtype=complex) k = _harmonic_axis(z) kw = k * _omega_rad_per_ns(frequency_hz, 1) m = np.clip(np.abs(z), _EPS, None) y = 1.0 / m**2 x = (k**2).astype(float) * np.ones(z.shape) if noise is None: w_fit = np.ones(z.shape) w_t0 = np.ones(z.shape) else: var_x = np.moveaxis(np.diagonal(noise["XX"], axis1=-2, axis2=-1), -1, 0) var_y = np.moveaxis(np.diagonal(noise["YY"], axis1=-2, axis2=-1), -1, 0) w_fit = m**6 / (4.0 * var_x) w_t0 = (kw * m) ** 2 / var_y s0, s1, s2 = w_fit.sum(0), (w_fit * x).sum(0), (w_fit * x**2).sum(0) sy, sxy = (w_fit * y).sum(0), (w_fit * x * y).sum(0) det = s0 * s2 - s1**2 P = (s2 * sy - s1 * sxy) / det Q = (s0 * sxy - s1 * sy) / det with np.errstate(invalid="ignore"): c = P**-0.5 tau = np.sqrt(Q / P) / _omega_rad_per_ns(frequency_hz, 1) t0_k = (unwrap_phases(z, frequency_hz, t0_guess_ns) - np.arctan(kw * tau)) / kw chi2 = (w_fit * (y - P - Q * x) ** 2).sum(0) dof = degrees_of_freedom(z.shape[0], 2, None) return { "c": c, "tau": tau, "t0": (w_t0 * t0_k).sum(0) / w_t0.sum(0), "t0_k": t0_k, "chi2": chi2, "reduced_chi2": chi2 / dof if dof > 0 else np.full(chi2.shape, np.nan), "dof": dof, "n_params": 2, }
[docs] def modulation_factor( n_counts: ArrayLike, v_shift: ArrayLike, n_gates: int, irf_counts: ArrayLike | None = None, irf_v_shift: ArrayLike = 0.0, ) -> np.ndarray: """ Modulation imbalance ``c = (1 - beta) / (1 - beta_I)`` of paper eq. 3 from the constant per-gate backgrounds (the solver's ``v_shift``): ``beta = n_gates v_shift / n_counts`` for the sample and ``beta_I = n_gates irf_v_shift / irf_counts`` for the IRF trace. Dividing calibrated phasors by ``c`` restores ``c = 1`` exactly. """ with np.errstate(divide="ignore", invalid="ignore"): beta = ( n_gates * np.asarray(v_shift, dtype=float) / np.asarray(n_counts, dtype=float) ) if irf_counts is None: beta_i = 0.0 else: beta_i = ( n_gates * np.asarray(irf_v_shift, dtype=float) / np.asarray(irf_counts, dtype=float) ) return (1.0 - beta) / (1.0 - beta_i)
[docs] def h_shift_from_t0(t0_ns: ArrayLike, time_axis_ns: ArrayLike) -> np.ndarray: """ Solver/simulator ``h_shift`` for a harmonic offset ``t0``: ``t0 + dt/2``. The forward model (:func:`pyfli.cm_funcs.forward_model.model_numpy`, :class:`pyfli.reconstruction.ParamToDecay`) and the simulators excite at the start of each IRF gate and integrate the decay over gates ``[t, t + dt)``, so the calibrated phasor phase is ``k omega (h_shift - dt/2)``. """ t = np.asarray(time_axis_ns, dtype=float) return np.asarray(t0_ns, dtype=float) + 0.5 * (t[1] - t[0])
[docs] def t0_from_h_shift(h_shift_ns: ArrayLike, time_axis_ns: ArrayLike) -> np.ndarray: """Inverse of :func:`h_shift_from_t0`.""" t = np.asarray(time_axis_ns, dtype=float) return np.asarray(h_shift_ns, dtype=float) - 0.5 * (t[1] - t[0])
[docs] def correct_phasors( G: ArrayLike, S: ArrayLike, t0_ns: ArrayLike, frequency_hz: float ) -> tuple[np.ndarray, np.ndarray]: """ Remove the offset from calibrated phasor stacks ``(K, ...)``: ``z_k <- e^{-i k omega t0} z_k`` (paper eq. 13), exact for every decay. """ z = np.asarray(G, dtype=float) + 1j * np.asarray(S, dtype=float) k = _harmonic_axis(z) z = z * np.exp(-1j * k * _omega_rad_per_ns(frequency_hz, 1) * np.asarray(t0_ns)) return z.real, z.imag
[docs] def fit_offset_surface( t0_hat: ArrayLike, accepted: ArrayLike, weights: ArrayLike | None = None, order: int = 0, ) -> tuple[np.ndarray, np.ndarray]: """ Spatial model ``t0(r)`` from accepted pixels of a 2-D ``t0_hat`` map: the median for ``order=0``, otherwise a weighted polynomial ``sum_{i+j<=order} theta_ij x^i y^j`` on pixel coordinates scaled to ``[-1, 1]``. Returns ------- tuple[np.ndarray, np.ndarray] ``(t0_map, theta)``; ``theta`` is ``(median,)`` for ``order=0``. """ t0_hat = np.asarray(t0_hat, dtype=float) use = np.asarray(accepted, dtype=bool) & np.isfinite(t0_hat) if weights is not None: use &= np.isfinite(weights) & (np.asarray(weights) > 0) if not use.any(): raise ValueError("no accepted pixels with a finite offset") if order == 0: med = np.median(t0_hat[use]) return np.full(t0_hat.shape, med), np.array([med]) H, W = t0_hat.shape yy, xx = np.meshgrid(np.linspace(-1, 1, H), np.linspace(-1, 1, W), indexing="ij") basis = np.stack( [xx**i * yy**j for i in range(order + 1) for j in range(order + 1 - i)], -1 ) sw = np.ones(use.sum()) if weights is None else np.sqrt(np.asarray(weights)[use]) theta, *_ = np.linalg.lstsq(basis[use] * sw[:, None], t0_hat[use] * sw, rcond=None) return basis @ theta, theta
[docs] def bracket_violations( t0_map: ArrayLike, lower: ArrayLike, upper: ArrayLike, tol_ns: ArrayLike = 0.0 ) -> np.ndarray: """Pixels whose modelled ``t0`` lies outside ``[lower - tol, upper + tol]``.""" t0_map = np.asarray(t0_map) return (t0_map < np.asarray(lower) - tol_ns) | (t0_map > np.asarray(upper) + tol_ns)
[docs] class HarmonicOffset: """ Pixelwise ``t0`` estimation and correction on top of a :class:`PhasorAnalyzer` (``n_harmonics >= 2``; its time axis must be :func:`gate_starts` of the period ``1 / frequency`` over which the phasors are computed). """ def __init__(self, analyzer: PhasorAnalyzer) -> None: if analyzer.n_harmonics < 2: raise ValueError("HarmonicOffset needs an analyzer with n_harmonics >= 2") t = np.asarray(analyzer.time_axis_ns, dtype=float) expected = t[0] + gate_starts(1e9 / analyzer.frequency, t.size) if not np.allclose(t, expected, rtol=0.0, atol=1e-6 * (expected[1] - t[0])): raise ValueError( "analyzer.time_axis_ns must be the gate starts of one period 1/frequency " "(gate_starts(period, n), i.e. linspace(0, period, n, endpoint=False)); " f"got spacing {t[1] - t[0]} ns for period/n = {expected[1] - t[0]} ns" ) self.analyzer = analyzer self.frequency = analyzer.frequency self.n_harmonics = analyzer.n_harmonics
[docs] def estimate( self, decay: ArrayLike, irf: ArrayLike, alpha: float = 0.05, order: int = 0, excess_noise: float = 1.0, full_covariance: bool = True, include_lifetime: bool = False, t0_guess_ns: ArrayLike = 0.0, v_shift: ArrayLike | None = None, irf_v_shift: ArrayLike = 0.0, model: str = "mono-exponential", n_jobs: int = -1, ) -> dict[str, Any]: """ Run the full pipeline on a decay cube ``(H, W, T)`` and a 1-D or per-pixel IRF. `include_lifetime` tests ``(t0_k, tau_k)`` jointly (``dof = 2K - 2``) instead of ``t0_k`` alone (``dof = K - 1``; see :func:`combine_offsets`). A known per-gate background `v_shift` (scalar or ``(H, W)``, e.g. the solver's ``v_shift_map``) and `irf_v_shift` give ``c`` (:func:`modulation_factor`), which is divided out of the calibrated phasors and their noise. ``model="bi-exponential"`` (``n_harmonics >= 3``) estimates each pixel's offset under the bi-exponential model (:func:`bi_exponential_offset`), so bi-exponential samples need no mono-exponential pixels; the chi-square test then has ``dof = 2K - 4``. Returns ------- dict[str, Any] ``z`` (calibrated phasors ``(K, H, W)``), ``t0_k``, ``tau_k``, ``lower``, ``upper``, ``cov``, ``c``, the :func:`combine_offsets` keys with ``t0`` as ``t0_hat`` (and ``tau`` as ``tau_hat``), ``accepted``, ``t0_map``, ``h_shift_map`` (solver convention, :func:`h_shift_from_t0`), ``theta`` and ``violations`` (rejected pixels whose bracket excludes ``t0_map``). For the bi-exponential model, the :func:`bi_exponential_offset` keys with ``t0`` as ``t0_hat`` and ``tau1``, ``tau2``, ``alpha1`` as ``tau1_hat``, ``tau2_hat``, ``alpha1_hat``, and ``cov`` = ``None``. """ if model not in ("mono-exponential", "bi-exponential"): raise ValueError( f"model must be 'mono-exponential' or 'bi-exponential', got {model!r}" ) K = self.n_harmonics decay = np.asarray(decay, dtype=float) z_raw = harmonic_phasors(self.analyzer, decay, 2 * K) z_irf = harmonic_phasors(self.analyzer, irf, 2 * K) c = np.ones(()) if v_shift is not None: irf_arr = np.asarray(irf, dtype=float) c = modulation_factor( decay.sum(-1), v_shift, decay.shape[-1], irf_arr.sum(-1), irf_v_shift ) if z_irf.ndim == 1: z_irf = z_irf.reshape((-1,) + (1,) * c.ndim) z_irf = z_irf * c z = calibrate_phasors(z_raw[:K], z_irf) t0_k, tau_k = mono_offset(z, self.frequency, t0_guess_ns) lower, upper = offset_bracket(z, self.frequency, t0_guess_ns) noise = phasor_noise(z_raw, z_irf, decay.sum(-1), K, excess_noise) if model == "bi-exponential": cov = None test = bi_exponential_offset( z, noise, self.frequency, t0_guess_ns, n_jobs=n_jobs ) test = { f"{key}_hat" if key in ("tau1", "tau2", "alpha1") else key: value for key, value in test.items() } test["tau"] = None else: cov = offset_covariance(noise, self.frequency, include_lifetime) test = combine_offsets( t0_k, cov, full_covariance, tau_k if include_lifetime else None ) accepted = select_mono(test["chi2"], test["dof"], alpha) t0_map, theta = fit_offset_surface( test["t0"], accepted, test["t0_se"] ** -2.0, order ) return { "z": z, "t0_k": t0_k, "tau_k": tau_k, "lower": lower, "upper": upper, "cov": cov, "c": c, "t0_hat": test.pop("t0"), "tau_hat": test.pop("tau"), **test, "accepted": accepted, "t0_map": t0_map, "h_shift_map": h_shift_from_t0(t0_map, self.analyzer.time_axis_ns), "theta": theta, "violations": ~accepted & bracket_violations(t0_map, lower, upper), }
[docs] def correct( self, G: ArrayLike, S: ArrayLike, t0_ns: ArrayLike ) -> tuple[np.ndarray, np.ndarray]: """Rotate calibrated phasor stacks by the offset (:func:`correct_phasors`).""" return correct_phasors(G, S, t0_ns, self.frequency)