Source code for pyfli.analysis.phasor_analysis

"""Compute phasor coordinates from binned decay data and save phasor lifetime maps."""

import os
from typing import Any

import numpy as np

from pyfli import logging

from ..analyticalWorkflow import AnalyticalHelpers, PhasorAnalyzer
from ..data_vnp import ColorProcessor


[docs] def compute_freq_axis( binned_irf: np.ndarray, laser_period_ns: float = 12.5 ) -> tuple[Any, ...]: """Derive frequency and time axis from IRF array shape. Parameters ---------- binned_irf : np.ndarray (H, W, T) laser_period_ns : float default 12.5 ns → 80 MHz Returns ------- freq : tuple from AnalyticalHelpers.freq_computation() freq_hz : float time_axis_ns : np.ndarray length T, gate start times ``k * T / num_gates`` covering exactly one laser period (endpoint excluded), so the phasor sums are the discrete Fourier transform at the laser frequency """ num_gates = binned_irf.shape[2] gate_delay = laser_period_ns / num_gates freq = AnalyticalHelpers( laser_period=laser_period_ns, gate_delay=gate_delay, num_gate=num_gates ).freq_computation() freq_hz = freq[1] * 1e6 time_axis_ns = np.arange(num_gates) * gate_delay return freq, freq_hz, time_axis_ns
[docs] def compute_phasor( binned_decay: np.ndarray, binned_irf: np.ndarray, freq_hz: np.ndarray, time_axis_ns: np.ndarray, n_harmonics: int = 3, ) -> tuple[Any, ...]: """Compute and calibrate phasor coordinates. Parameters ---------- binned_decay : np.ndarray (H, W, T) binned_irf : np.ndarray (H, W, T) freq_hz : float time_axis_ns : np.ndarray n_harmonics : int Returns ------- phasor_obj : PhasorAnalyzer reuse this instance for all plotting calls Gc, Sc : np.ndarray (n_harmonics, H, W) calibrated phasor coordinates tau_map_ns : np.ndarray (H, W) apparent lifetime from 1st harmonic """ phasor_obj = PhasorAnalyzer( frequency_hz=freq_hz, time_axis_ns=time_axis_ns, n_harmonics=n_harmonics ) G, S = phasor_obj.create_phasor_gpu(binned_decay) Gc, Sc = phasor_obj.calibrate_pixelwise(G, S, binned_irf) tau_map_ns = phasor_obj.compute_lifetime(Gc[0], Sc[0]) return phasor_obj, Gc, Sc, tau_map_ns
[docs] def plot_phasor_figures( phasor_obj: np.ndarray, Gc: Any, Sc: Any, binned_decay: np.ndarray, mask: np.ndarray, colorset: str = "jet", saver: Any | None = None, ) -> np.ndarray: """Generate all standard phasor figures. Produces: phasor diagram, overlay subplots, harmonics plot (if ≥ 3 harmonics), pure phasor map, and traceable analysis. Parameters ---------- phasor_obj : PhasorAnalyzer returned by compute_phasor() Gc, Sc : np.ndarray (n_harmonics, H, W) binned_decay: np.ndarray (H, W, T) mask : np.ndarray (H, W) bool colorset : str colormap name for hexbin density plots saver : DataSaver or None Returns ------- figs : dict[str, Figure] keyed by figure name """ plasma_m = ColorProcessor().lowest_zero("plasma") viridis_m = ColorProcessor().lowest_zero("viridis") figs = {} figs["phasor_diagram"] = phasor_obj.plot_phasor_diagram( Gc[0], Sc[0], mask=mask, colors=None, hexbin_color=colorset, ax=None, figsize=(8, 3), half_circle=True, 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, ) if saver: saver.save_plot("Phasor_Plot", fig=figs["phasor_diagram"], close=False) figs["phasor_subplots"] = phasor_obj.plot_overlay_subplots( binned_decay, Gc[0], Sc[0], mask=mask, colormaps=[plasma_m, viridis_m], hexbin_color="jet", noise_removed=True, figsize=(10, 8), ) if saver: saver.save_plot("Phasor_subplots", fig=figs["phasor_subplots"], close=False) n_harmonics = Gc.shape[0] if n_harmonics >= 2: figs["phasor_harmonics"] = phasor_obj.plot_phasor_harmonics( Gc, Sc, harmonics=tuple(range(1, n_harmonics + 1)), mask=mask, hexbin_color=colorset, figsize=(14, 4), ) if saver: saver.save_plot( "phasor_harmonics_Plot", fig=figs["phasor_harmonics"], close=False ) figs["phasor_pure_map"] = phasor_obj.plot_pure_phasor_map( Gc[0], Sc[0], binned_decay, noise_removed=True, colormap="viridis" ) figs["phasor_traceable"] = phasor_obj.plot_traceable_analysis( Gc[0], Sc[0], binned_decay, mask=mask, colormap="viridis" ) return figs
[docs] def save_phasor_result( save_dir: str, tau_map_ns: np.ndarray, saver: Any | None = None ) -> np.ndarray: """ Save phasor result. Parameters ---------- save_dir : str Directory where outputs are saved. tau_map_ns : np.ndarray Lifetime map in nanoseconds. saver : Any | None Optional saver used to persist messages or figures. Returns ------- np.ndarray Saved phasor result arrays or metadata. """ result = { "results": { "maps": { "tau_map": tau_map_ns, "mean_lifetime": tau_map_ns, }, "TR_maps": {}, } } path = os.path.join(save_dir, "phasor_tau_map.npy") np.save(path, result) if saver: saver.log("Phasor tau map saved as phasor_tau_map.npy") logging.info(f"Phasor result saved → {path}") return path