"""Compact phasor analyzer for CPU and optional GPU workflows."""
from typing import Any
import h5py
import matplotlib.pyplot as plt
import numpy as np
import torch
from pyfli import logging
from pyfli.cm_funcs.forward_model import gate_integrated_kernel
from pyfli.reconstruction.common_reconstruct import circular_convolve_torch, gate_starts
from pyfli.reconstruction.decay_reconstruction import ParamToDecay
from .phasor_lifetime import normal_lifetime
from .phasor_simple_plots import PhasorPlotsMixin
[docs]
class PhasorAnalyzer(PhasorPlotsMixin):
"""
Compute, calibrate, and interpret FLI phasors from decay data. The analyzer
supports NumPy and optional Torch execution, multi-harmonic phasors, IRF
calibration, lifetime conversion, fractional component estimates, and plotting
through the phasor mixin.
Parameters
----------
frequency_hz : float
Excitation frequency in hertz.
time_axis_ns : np.ndarray
Time axis for decay samples in nanoseconds: the starts of ``n`` gates tiling
one period ``1 / frequency_hz``
(:func:`~pyfli.reconstruction.common_reconstruct.gate_starts`); a warning is
logged otherwise.
n_harmonics : int
Number of phasor harmonics to compute.
device : Any | None
Execution device, such as a Torch device or device string.
"""
def __init__(
self,
frequency_hz: float,
time_axis_ns: np.ndarray,
n_harmonics: int = 1,
device: Any | None = None,
) -> None:
self.frequency = float(frequency_hz)
self.time_axis_ns = np.asarray(time_axis_ns)
self.n_harmonics = int(n_harmonics)
t = self.time_axis_ns
if t.size > 1 and not np.isclose(
(t[1] - t[0]) * t.size, 1e9 / self.frequency, rtol=1e-6
):
logging.warning(
f"time_axis_ns spans {(t[1] - t[0]) * t.size:.6g} ns, not one period "
f"{1e9 / self.frequency:.6g} ns; use "
"pyfli.reconstruction.common_reconstruct.gate_starts(period, n) "
"(linspace(0, period, n, endpoint=False))"
)
self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
self.omega = 2 * np.pi * self.frequency
self.t_s_np = self.time_axis_ns * 1e-9
self.t_s_torch = torch.tensor(
self.t_s_np, dtype=torch.float32, device=self.device
)
self.eps = 1e-12
# ── phasor computation ────────────────────────────────────────────────────
def _phasor_numpy(self, decay: np.ndarray) -> tuple[Any, ...]:
"""
Run the phasor numpy routine.
Parameters
----------
decay : np.ndarray
Time-resolved decay signal or decay cube.
Returns
-------
tuple[Any, ...]
Tuple containing NumPy-computed phasor coordinates and intensity values.
"""
decay = np.asarray(decay, dtype=np.float64)
*spatial, T = decay.shape
decay_flat = decay.reshape(-1, T)
I_sum = np.clip(np.sum(decay_flat, axis=1), self.eps, None)
G_all, S_all = [], []
for k in range(1, self.n_harmonics + 1):
omega_k = k * self.omega
cos_k = np.cos(omega_k * self.t_s_np)
sin_k = np.sin(omega_k * self.t_s_np)
G_all.append((np.sum(decay_flat * cos_k, axis=1) / I_sum).reshape(spatial))
S_all.append((np.sum(decay_flat * sin_k, axis=1) / I_sum).reshape(spatial))
return np.stack(G_all), np.stack(S_all)
def _phasor_torch(self, decay: np.ndarray) -> tuple[Any, ...]:
"""
Run the phasor torch routine.
Parameters
----------
decay : np.ndarray
Time-resolved decay signal or decay cube.
Returns
-------
tuple[Any, ...]
Tuple containing Torch-computed phasor coordinates and intensity values.
"""
decay_t = torch.tensor(
np.asarray(decay), dtype=torch.float32, device=self.device
)
*spatial, T = decay_t.shape
decay_flat = decay_t.reshape(-1, T)
I_sum = torch.clamp(torch.sum(decay_flat, dim=1), min=self.eps)
G_all, S_all = [], []
for k in range(1, self.n_harmonics + 1):
omega_k = k * self.omega
cos_k = torch.cos(omega_k * self.t_s_torch)
sin_k = torch.sin(omega_k * self.t_s_torch)
G_all.append(
(torch.sum(decay_flat * cos_k, dim=1) / I_sum).reshape(spatial)
)
S_all.append(
(torch.sum(decay_flat * sin_k, dim=1) / I_sum).reshape(spatial)
)
return torch.stack(G_all), torch.stack(S_all)
[docs]
def create_phasor_cpu(self, decay: np.ndarray) -> Any:
"""
Create phasor cpu.
Parameters
----------
decay : np.ndarray
Time-resolved decay signal or decay cube.
Returns
-------
Any
Object produced by create phasor CPU.
"""
return self._phasor_numpy(decay)
[docs]
def create_phasor_gpu(self, decay: np.ndarray) -> tuple[Any, ...]:
"""
Create phasor gpu.
Parameters
----------
decay : np.ndarray
Time-resolved decay signal or decay cube.
Returns
-------
tuple[Any, ...]
Tuple containing GPU-computed phasor coordinates and intensity values.
"""
G, S = self._phasor_torch(decay)
return G.cpu().numpy(), S.cpu().numpy()
# ── calibration ───────────────────────────────────────────────────────────
[docs]
def calibrate(
self, G: np.ndarray, S: np.ndarray, irf: np.ndarray
) -> tuple[Any, ...]:
"""
Run the calibrate routine.
Parameters
----------
G : np.ndarray
Phasor real coordinate.
S : np.ndarray
Phasor imaginary coordinate or shift amount.
irf : np.ndarray
Instrument response function aligned with the decay signal.
Returns
-------
tuple[Any, ...]
Tuple containing calibrated phasor coordinates and calibration factors.
"""
G = np.asarray(G)
S = np.asarray(S)
irf = np.asarray(irf)
if irf.ndim == 3:
irf = irf.mean(axis=(0, 1))
denom = np.clip(np.sum(irf), self.eps, None)
G_irf, S_irf = [], []
for k in range(1, self.n_harmonics + 1):
omega_k = k * self.omega
G_irf.append(np.sum(irf * np.cos(omega_k * self.t_s_np)) / denom)
S_irf.append(np.sum(irf * np.sin(omega_k * self.t_s_np)) / denom)
G_irf = np.array(G_irf)
S_irf = np.array(S_irf)
P = G + 1j * S
P_irf = G_irf[:, None, None] + 1j * S_irf[:, None, None]
P_irf_abs_sq = np.clip(
G_irf[:, None, None] ** 2 + S_irf[:, None, None] ** 2, self.eps, None
)
P_true = P * np.conj(P_irf) / P_irf_abs_sq
return np.real(P_true), np.imag(P_true)
[docs]
def calibrate_pixelwise(
self, G: np.ndarray, S: np.ndarray, irf: np.ndarray
) -> tuple[Any, ...]:
"""
Run the calibrate pixelwise routine.
Parameters
----------
G : np.ndarray
Phasor real coordinate.
S : np.ndarray
Phasor imaginary coordinate or shift amount.
irf : np.ndarray
Instrument response function aligned with the decay signal.
Returns
-------
tuple[Any, ...]
Tuple containing per-pixel calibrated phasor coordinates and factors.
"""
G = np.asarray(G, dtype=np.float32)
S = np.asarray(S, dtype=np.float32)
irf = np.asarray(irf, dtype=np.float32)
H, W, T = irf.shape
K = self.n_harmonics
irf_flat = torch.tensor(irf.reshape(-1, T), device=self.device)
I_sum = irf_flat.sum(dim=1, keepdim=True).clamp(min=self.eps)
irf_norm = irf_flat / I_sum
t_s = self.t_s_torch
Gc_list, Sc_list = [], []
for k in range(1, K + 1):
omega_k = k * self.omega
cos_k = torch.cos(
torch.tensor(omega_k, dtype=torch.float32, device=self.device) * t_s
)
sin_k = torch.sin(
torch.tensor(omega_k, dtype=torch.float32, device=self.device) * t_s
)
G_irf_flat = (irf_norm * cos_k).sum(dim=1)
S_irf_flat = (irf_norm * sin_k).sum(dim=1)
G_irf = G_irf_flat.reshape(H, W)
S_irf = S_irf_flat.reshape(H, W)
G_meas = torch.tensor(G[k - 1], device=self.device)
S_meas = torch.tensor(S[k - 1], device=self.device)
denom = (G_irf**2 + S_irf**2).clamp(min=self.eps)
Gc_k = (G_meas * G_irf + S_meas * S_irf) / denom
Sc_k = (S_meas * G_irf - G_meas * S_irf) / denom
Gc_list.append(Gc_k.cpu().numpy())
Sc_list.append(Sc_k.cpu().numpy())
return np.stack(Gc_list), np.stack(Sc_list)
[docs]
def calibratre_reference(
self,
G: np.ndarray,
S: np.ndarray,
ref_data: np.ndarray,
ref_lifetime_ns: float | None = None,
) -> tuple[Any, ...]:
"""
Run the calibratre reference routine.
Parameters
----------
G : np.ndarray
Phasor real coordinate.
S : np.ndarray
Phasor imaginary coordinate or shift amount.
ref_data : np.ndarray
Decay trace of a reference sample used for calibration.
ref_lifetime_ns : float | None
Known lifetime of the reference sample in nanoseconds. When None, the
reference is treated as a zero-lifetime instrument response, matching
:meth:`calibrate`.
Returns
-------
tuple[Any, ...]
Tuple containing calibrated phasor coordinates and calibration factors.
"""
G = np.asarray(G)
S = np.asarray(S)
ref_data = np.asarray(ref_data)
if ref_data.ndim == 3:
ref_data = ref_data.mean(axis=(0, 1))
denom = np.clip(np.sum(ref_data), self.eps, None)
G_ref, S_ref = [], []
for k in range(1, self.n_harmonics + 1):
omega_k = k * self.omega
G_ref.append(np.sum(ref_data * np.cos(omega_k * self.t_s_np)) / denom)
S_ref.append(np.sum(ref_data * np.sin(omega_k * self.t_s_np)) / denom)
G_ref = np.array(G_ref)
S_ref = np.array(S_ref)
if ref_lifetime_ns is not None:
harmonic_freqs = self.frequency * np.arange(1, self.n_harmonics + 1)
G_theory, S_theory = self.lifetime_to_phasor(
ref_lifetime_ns, harmonic_freqs
)
else:
G_theory = np.ones(self.n_harmonics)
S_theory = np.zeros(self.n_harmonics)
P = G + 1j * S
P_ref = G_ref[:, None, None] + 1j * S_ref[:, None, None]
P_theory = G_theory[:, None, None] + 1j * S_theory[:, None, None]
P_ref_abs_sq = np.clip(
G_ref[:, None, None] ** 2 + S_ref[:, None, None] ** 2, self.eps, None
)
P_true = P * np.conj(P_ref) * P_theory / P_ref_abs_sq
return np.real(P_true), np.imag(P_true)
[docs]
def calibrate_reference(
self,
G: np.ndarray,
S: np.ndarray,
ref_data: np.ndarray,
ref_lifetime_ns: float | None = None,
) -> tuple[Any, ...]:
"""Correctly spelled name of :meth:`calibratre_reference` (same arguments and result)."""
return self.calibratre_reference(G, S, ref_data, ref_lifetime_ns)
[docs]
def calibrate_reference_pixelwise(
self,
G: np.ndarray,
S: np.ndarray,
ref_data: np.ndarray,
ref_lifetime_ns: float | None = None,
) -> tuple[Any, ...]:
"""Correctly spelled name of :meth:`calibratre_reference_pixelwise` (same arguments and result)."""
return self.calibratre_reference_pixelwise(G, S, ref_data, ref_lifetime_ns)
[docs]
def calibratre_reference_pixelwise(
self,
G: np.ndarray,
S: np.ndarray,
ref_data: np.ndarray,
ref_lifetime_ns: float | None = None,
) -> tuple[Any, ...]:
"""
Run the calibratre reference pixelwise routine.
Parameters
----------
G : np.ndarray
Phasor real coordinate.
S : np.ndarray
Phasor imaginary coordinate or shift amount.
ref_data : np.ndarray
Per-pixel decay cube of a reference sample used for calibration.
ref_lifetime_ns : float | None
Known lifetime of the reference sample in nanoseconds. When None, the
reference is treated as a zero-lifetime instrument response, matching
:meth:`calibrate_pixelwise`.
Returns
-------
tuple[Any, ...]
Tuple containing per-pixel calibrated phasor coordinates and factors.
"""
G = np.asarray(G, dtype=np.float32)
S = np.asarray(S, dtype=np.float32)
ref_data = np.asarray(ref_data, dtype=np.float32)
H, W, T = ref_data.shape
K = self.n_harmonics
ref_flat = torch.tensor(ref_data.reshape(-1, T), device=self.device)
I_sum = ref_flat.sum(dim=1, keepdim=True).clamp(min=self.eps)
ref_norm = ref_flat / I_sum
t_s = self.t_s_torch
Gc_list, Sc_list = [], []
for k in range(1, K + 1):
omega_k = k * self.omega
cos_k = torch.cos(
torch.tensor(omega_k, dtype=torch.float32, device=self.device) * t_s
)
sin_k = torch.sin(
torch.tensor(omega_k, dtype=torch.float32, device=self.device) * t_s
)
G_ref_flat = (ref_norm * cos_k).sum(dim=1)
S_ref_flat = (ref_norm * sin_k).sum(dim=1)
G_ref = G_ref_flat.reshape(H, W)
S_ref = S_ref_flat.reshape(H, W)
G_meas = torch.tensor(G[k - 1], device=self.device)
S_meas = torch.tensor(S[k - 1], device=self.device)
denom = (G_ref**2 + S_ref**2).clamp(min=self.eps)
Gc_k = (G_meas * G_ref + S_meas * S_ref) / denom
Sc_k = (S_meas * G_ref - G_meas * S_ref) / denom
if ref_lifetime_ns is not None:
G_theory, S_theory = self.lifetime_to_phasor(
ref_lifetime_ns, k * self.frequency
)
G_theory = float(G_theory)
S_theory = float(S_theory)
Gc_k, Sc_k = (
Gc_k * G_theory - Sc_k * S_theory,
Gc_k * S_theory + Sc_k * G_theory,
)
Gc_list.append(Gc_k.cpu().numpy())
Sc_list.append(Sc_k.cpu().numpy())
return np.stack(Gc_list), np.stack(Sc_list)
# ── lifetime conversion ───────────────────────────────────────────────────
[docs]
def lifetime_to_phasor(
self, tau_ns: np.ndarray, frequency_hz: float
) -> tuple[Any, ...]:
"""
Run the lifetime to phasor routine.
Parameters
----------
tau_ns : np.ndarray
Lifetime value in nanoseconds.
frequency_hz : float
Excitation frequency in hertz.
Returns
-------
tuple[Any, ...]
Tuple containing phasor coordinates for the supplied lifetime values.
"""
tau_s = np.asarray(tau_ns) * 1e-9
omega = 2 * np.pi * frequency_hz
denom = 1 + (omega * tau_s) ** 2
return 1 / denom, (omega * tau_s) / denom
[docs]
def compute_lifetime(self, G: np.ndarray, S: np.ndarray) -> np.ndarray:
"""
Compute lifetime.
Parameters
----------
G : np.ndarray
Phasor real coordinate.
S : np.ndarray
Phasor imaginary coordinate or shift amount.
Returns
-------
np.ndarray
Phase lifetime ``S / (omega G)`` in ns, with ``omega`` the laser (first
harmonic) angular frequency: pass first-harmonic phasors, or divide by
``k`` for harmonic ``k``. For binned data this standard phase lifetime
carries the gate-width bias of the binned locus (a few % at 256 bins);
:func:`~pyfli.phasor.phasorS.discrete_phasor_lifetime` inverts the binned
locus exactly.
"""
G = np.asarray(G, dtype=np.float64)
S = np.asarray(S, dtype=np.float64)
safe_denom = np.where(np.abs(G) > 1e-4, G * self.omega, np.inf)
return np.where(np.abs(G) > 1e-4, S / safe_denom * 1e9, np.nan)
[docs]
def compute_modulation_lifetime(self, G: np.ndarray, S: np.ndarray) -> Any:
"""
Compute modulation lifetime.
Parameters
----------
G : np.ndarray
Phasor real coordinate.
S : np.ndarray
Phasor imaginary coordinate or shift amount.
Returns
-------
Any
Modulation lifetime ``sqrt(1 / M^2 - 1) / omega`` in ns, ``M^2 = G^2 + S^2``,
with ``omega`` the laser (first harmonic) angular frequency: pass
first-harmonic phasors, or divide by ``k`` for harmonic ``k``.
"""
G = np.asarray(G, dtype=np.float64)
S = np.asarray(S, dtype=np.float64)
M_sq = np.clip(G**2 + S**2, self.eps, 1.0 - self.eps)
return np.sqrt(1.0 / M_sq - 1.0) / self.omega * 1e9
[docs]
def compute_normal_lifetime(self, G: np.ndarray, S: np.ndarray) -> np.ndarray:
"""
Compute the normal lifetime ``tau_N``: the lifetime of the universal-semicircle
point nearest to each phasor
(:func:`~pyfli.phasor.phasorS.phasor_lifetime.normal_lifetime`).
Parameters
----------
G : np.ndarray
Phasor real coordinate (IRF-calibrated, first harmonic).
S : np.ndarray
Phasor imaginary coordinate.
Returns
-------
np.ndarray
Normal lifetime map in nanoseconds.
"""
return normal_lifetime(G, S, self.frequency)
[docs]
def compute_apparent_lifetimes(
self, G: np.ndarray, S: np.ndarray
) -> dict[str, np.ndarray]:
"""
Compute the phase, modulation and normal lifetimes of each phasor.
Parameters
----------
G : np.ndarray
Phasor real coordinate (IRF-calibrated, first harmonic).
S : np.ndarray
Phasor imaginary coordinate.
Returns
-------
dict[str, np.ndarray]
``{"tau_phi", "tau_m", "tau_n"}`` maps in nanoseconds, from
:meth:`compute_lifetime`, :meth:`compute_modulation_lifetime` and
:meth:`compute_normal_lifetime`.
"""
return {
"tau_phi": self.compute_lifetime(G, S),
"tau_m": self.compute_modulation_lifetime(G, S),
"tau_n": self.compute_normal_lifetime(G, S),
}
# ── two-component analysis ────────────────────────────────────────────────
[docs]
def component_kernel(self, tau_ns: Any, model: str = "continuous") -> np.ndarray:
"""
Per-bin photon distribution of a pure periodically excited mono-exponential
component over this analyzer's time axis (one laser period), before IRF
convolution.
Parameters
----------
tau_ns : Any
Lifetime(s) in nanoseconds (any shape ``S``).
model : str
``"continuous"``: excitation photons arrive anywhere inside their bin, as in
a real instrument (the forward model's ``excitation="uniform"``,
:func:`~pyfli.cm_funcs.forward_model.gate_integrated_kernel`; equal to
:func:`~pyfli.reconstruction.common_reconstruct.periodic_instrument_exponential`).
``"bin_start"``: every excitation at a bin start, as in pyfli's simulators
(``excitation="bin_start"``; equal to
:func:`~pyfli.reconstruction.common_reconstruct.periodic_bin_exponential`).
Returns
-------
np.ndarray
``S + (T,)``, summing to 1 along the last axis.
"""
n_bins, period_ns = len(self.t_s_np), 1e9 / self.frequency
kernel, _ = gate_integrated_kernel(
gate_starts(period_ns, n_bins),
period_ns / n_bins,
(1.0, np.asarray(tau_ns, dtype=float)[..., None], 0.0),
"mono-exponential",
0.0,
period_ns,
excitation=self._excitation(model),
)
return kernel
@staticmethod
def _excitation(model: str) -> str:
"""Forward-model ``excitation`` of a phasor component model."""
if model == "continuous":
return "uniform"
if model == "bin_start":
return "bin_start"
raise ValueError(f"model must be 'continuous' or 'bin_start', got {model!r}")
[docs]
def component_phasor(
self, tau_ns: Any, harmonic: int = 1, model: str = "continuous"
) -> tuple[Any, ...]:
"""
Phasor of a pure mono-exponential component as it appears in IRF-calibrated
binned data on this analyzer's time axis.
``model="continuous"`` (real instruments) gives the universal-semicircle point
:meth:`lifetime_to_phasor`, exactly. ``model="bin_start"`` (data simulated by
pyfli's ``PhotonCountSimulator`` / ``ContinuousSimulator``, whose excitations
sit at bin starts) gives the binned locus, which is rotated by about half a bin
(phase lifetime a few % lower at 256 bins).
Parameters
----------
tau_ns : Any
Lifetime(s) in nanoseconds.
harmonic : int
Harmonic (1 = laser frequency).
model : str
``"continuous"`` or ``"bin_start"`` (see :meth:`component_kernel`).
Returns
-------
tuple[Any, ...]
``(g, s)`` with the shape of `tau_ns`.
"""
if model == "continuous":
return self.lifetime_to_phasor(tau_ns, harmonic * self.frequency)
p = self.component_kernel(tau_ns, model)
w = harmonic * self.omega * self.t_s_np
return p @ np.cos(w), p @ np.sin(w)
[docs]
def compute_fractions(
self,
G: np.ndarray,
S: np.ndarray,
tau1_ns: np.ndarray,
tau2_ns: np.ndarray,
mask: np.ndarray | None = None,
hexbin_color: np.ndarray | None = None,
plot_graph: bool = True,
ax: Any | None = None,
half_circle: bool = False,
component_model: str = "continuous",
) -> tuple[Any, ...]:
"""
Compute fractions.
Parameters
----------
G : np.ndarray
Phasor real coordinate.
S : np.ndarray
Phasor imaginary coordinate or shift amount.
tau1_ns : np.ndarray
Short lifetime component in nanoseconds.
tau2_ns : np.ndarray
Long lifetime component in nanoseconds.
mask : np.ndarray | None
Boolean or labeled mask selecting pixels for the operation.
hexbin_color : np.ndarray | None
Optional values used to color phasor hexbin density.
plot_graph : bool
Whether the phasor graph should be drawn.
ax : Any | None
Matplotlib axes object on which the plot is drawn.
half_circle : bool
Whether to draw only the upper half of the universal phasor circle.
component_model : str
Where a pure component's calibrated phasor lies (see
:meth:`component_phasor`): ``"continuous"`` (default, the universal
semicircle -- real instruments) or ``"bin_start"`` (pyfli's
``PhotonCountSimulator`` / ``ContinuousSimulator`` data).
Returns
-------
tuple[Any, ...]
``(A1, A2)``: intensity (photon) fractions of the two components, from the
projection of each phasor onto the line between the component phasors.
"""
g1, s1 = self.component_phasor(tau1_ns, model=component_model)
g2, s2 = self.component_phasor(tau2_ns, model=component_model)
if plot_graph:
created_fig = ax is None
if created_fig:
fig, ax = plt.subplots(figsize=(8, 6))
self.plot_phasor_diagram(
G,
S,
mask=mask,
colors=None,
hexbin_color="jet_r",
ax=ax,
figsize=(8, 3),
half_circle=half_circle,
title="Phasor Diagram",
xlim=(-0.1, 1.1),
ylim=(0.0, 0.6),
kdeplot=False,
kde_color="white",
kde_levels=5,
kde_linewidths=1,
kde_alpha=0.5,
)
ax.plot(
[g1, g2], [s1, s2], color="#2C0F02", linestyle="--", lw=2, zorder=10
)
ax.plot(g1, s1, "o", color="#E5D16E", markersize=8, label="...", zorder=11)
ax.plot(g2, s2, "o", color="#363D45", markersize=8, label="...", zorder=11)
ax.legend(loc="upper right")
if created_fig:
plt.tight_layout()
line_vec_g = g1 - g2
line_vec_s = s1 - s2
line_mag_sq = line_vec_g**2 + line_vec_s**2 + self.eps
A1 = np.clip(
((G - g2) * line_vec_g + (S - s2) * line_vec_s) / line_mag_sq, 0, 1
)
return A1, 1 - A1
# ── biexponential reconstruction ──────────────────────────────────────────
def _convolve_batch(self, signal: np.ndarray, kernel: np.ndarray) -> Any:
"""
Circular (periodic) convolution of a batch of decays with IRFs.
The time axis spans one laser period and the excitation repeats, so the IRF
spread of photons near the end of the period wraps to its start, as in the
measured decays (and in the phasor model, which assumes periodic excitation).
Parameters
----------
signal : np.ndarray
Signal batch convolved with the supplied kernel, ``(N, T)``.
kernel : np.ndarray
Convolution kernel applied to the signal batch, ``(N, T)`` or ``(1, T)``.
Returns
-------
Any
Convolved batch, ``(N, T)``.
"""
return circular_convolve_torch(signal, kernel, dim=1)
[docs]
def analyze_biexponential_and_reconstruct(
self,
G: np.ndarray,
S: np.ndarray,
irf: np.ndarray,
tau1_ns: np.ndarray | None = None,
tau2_ns: np.ndarray | None = None,
plot: bool = True,
axes: Any | None = None,
component_model: str = "continuous",
h_shift: Any = None,
v_shift: Any = None,
) -> Any:
"""
Run the analyze biexponential and reconstruct routine.
Parameters
----------
G : np.ndarray
Phasor real coordinate.
S : np.ndarray
Phasor imaginary coordinate or shift amount.
irf : np.ndarray
Instrument response function aligned with the decay signal.
tau1_ns : np.ndarray | None
Short lifetime component in nanoseconds.
tau2_ns : np.ndarray | None
Long lifetime component in nanoseconds.
plot : bool
Whether diagnostic plots should be generated.
axes : Any | None
Matplotlib axes collection used for drawing subplots.
component_model : str
``"continuous"`` (default, real instruments) or ``"bin_start"`` (pyfli
simulated data); used for both the fractions and the reconstruction.
h_shift : float | np.ndarray | None
Decay onset in ns, scalar or ``(H, W)``, e.g.
:func:`pyfli.phasor.harmonic_offset.h_shift_from_t0` of a harmonic offset;
``None`` is 0.
v_shift : float | np.ndarray | None
Constant added to every gate, scalar or ``(H, W)``; ``None`` is 0.
Returns
-------
Any
Reconstructed decays ``(H, W, T)``: the solver's forward model
(:class:`pyfli.reconstruction.ParamToDecay`, ``shift_method="circular"``,
the excitation of `component_model`) with the phasor fractions, convolved
with each pixel's IRF; without `v_shift` every pixel sums to ``A1 + A2``
(1 for fractions summing to 1; multiply by the photon count to compare
with the data).
"""
if tau1_ns is None or tau2_ns is None:
return None
A1, A2 = self.compute_fractions(
G, S, tau1_ns, tau2_ns, plot_graph=False, component_model=component_model
)
tau_map_ns = self.compute_lifetime(G, S)
if plot:
created_fig = axes is None
if created_fig:
fig, axes = plt.subplots(1, 3, figsize=(18, 5))
else:
fig = axes[0].get_figure()
im1 = axes[0].imshow(A1, origin="upper", cmap="viridis")
axes[0].set_title(f"A1 Map (Fraction of {tau1_ns} ns)")
fig.colorbar(im1, ax=axes[0])
im2 = axes[1].imshow(A2, origin="upper", cmap="plasma")
axes[1].set_title(f"A2 Map (Fraction of {tau2_ns} ns)")
fig.colorbar(im2, ax=axes[1])
im3 = axes[2].imshow(
np.clip(tau_map_ns, 0, 5), origin="upper", cmap="magma"
)
axes[2].set_title("Phase Lifetime Map (ns)")
fig.colorbar(im3, ax=axes[2])
for ax in axes:
ax.axis("off")
if created_fig:
plt.tight_layout()
A1 = np.asarray(A1, dtype=float)
A2 = np.asarray(A2, dtype=float)
shape = A1.shape
total = A1 + A2
alpha1 = np.divide(A1, total, out=np.full(shape, 0.5), where=total != 0)
def as_map(value: Any) -> np.ndarray:
value = 0.0 if value is None else value
return np.broadcast_to(np.asarray(value, dtype=float), shape)
recon = ParamToDecay(
"bi-exponential",
self.frequency / 1e6,
irf=np.asarray(irf, dtype=float),
shift_method="circular",
excitation=self._excitation(component_model),
)
convolved = recon.reconstruct_unit_amplitude(
{
"photon_count_map": total,
"alpha1_map": alpha1,
"tau1_map": as_map(tau1_ns),
"tau2_map": as_map(tau2_ns),
"h_shift_map": as_map(h_shift),
}
)["convolved_map"]
return (convolved + as_map(v_shift)[..., None]).astype(np.float32)
# ── utilities ─────────────────────────────────────────────────────────────
[docs]
def generate_intensity_image(self, decay: np.ndarray) -> np.ndarray:
"""
Generate intensity image.
Parameters
----------
decay : np.ndarray
Time-resolved decay signal or decay cube.
Returns
-------
np.ndarray
Intensity image obtained by integrating the decay along the time axis.
"""
return np.sum(decay, axis=2)
[docs]
def save_phasors_hdf5(
self, Gc: Any, Sc: Any, tau_phasor: np.ndarray, save_file: np.ndarray
) -> None:
"""
Save phasors hdf5.
Parameters
----------
Gc : Any
Calibrated phasor real coordinate map.
Sc : Any
Calibrated phasor imaginary coordinate map.
tau_phasor : np.ndarray
Lifetime map estimated from phasor coordinates.
save_file : np.ndarray
HDF5 path where phasor results are saved.
Returns
-------
None
No object is returned; the function save phasors hdf5.
"""
try:
with h5py.File(save_file, "w") as hf:
hf.create_dataset("Gc", data=Gc, compression="gzip", chunks=True)
hf.create_dataset("Sc", data=Sc, compression="gzip", chunks=True)
hf.create_dataset(
"tau_phasor", data=tau_phasor, compression="gzip", chunks=True
)
hf.attrs["n_harmonics"] = Gc.shape[0]
hf.attrs["resolution"] = f"{Gc.shape[1]}x{Gc.shape[2]}"
logging.info(f"Successfully saved data to {save_file}")
except Exception as e:
logging.error(f"An error occurred while saving: {e}")