pyfli.phasor.phasorS.phasor_simple#

Compact phasor analyzer for CPU and optional GPU workflows.

Classes

PhasorAnalyzer(frequency_hz, time_axis_ns[, ...])

Compute, calibrate, and interpret FLI phasors from decay data.

class PhasorAnalyzer(frequency_hz, time_axis_ns, n_harmonics=1, device=None)[source]#

Bases: 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 (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.

create_phasor_cpu(decay)[source]#

Create phasor cpu.

Parameters:

decay (np.ndarray) – Time-resolved decay signal or decay cube.

Returns:

Object produced by create phasor CPU.

Return type:

Any

create_phasor_gpu(decay)[source]#

Create phasor gpu.

Parameters:

decay (np.ndarray) – Time-resolved decay signal or decay cube.

Returns:

Tuple containing GPU-computed phasor coordinates and intensity values.

Return type:

tuple[Any, ]

calibrate(G, S, irf)[source]#

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 containing calibrated phasor coordinates and calibration factors.

Return type:

tuple[Any, ]

calibrate_pixelwise(G, S, irf)[source]#

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 containing per-pixel calibrated phasor coordinates and factors.

Return type:

tuple[Any, ]

calibratre_reference(G, S, ref_data, ref_lifetime_ns=None)[source]#

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 calibrate().

Returns:

Tuple containing calibrated phasor coordinates and calibration factors.

Return type:

tuple[Any, ]

calibrate_reference(G, S, ref_data, ref_lifetime_ns=None)[source]#

Correctly spelled name of calibratre_reference() (same arguments and result).

Parameters:
Return type:

tuple[Any, …]

calibrate_reference_pixelwise(G, S, ref_data, ref_lifetime_ns=None)[source]#

Correctly spelled name of calibratre_reference_pixelwise() (same arguments and result).

Parameters:
Return type:

tuple[Any, …]

calibratre_reference_pixelwise(G, S, ref_data, ref_lifetime_ns=None)[source]#

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 calibrate_pixelwise().

Returns:

Tuple containing per-pixel calibrated phasor coordinates and factors.

Return type:

tuple[Any, ]

lifetime_to_phasor(tau_ns, frequency_hz)[source]#

Run the lifetime to phasor routine.

Parameters:
  • tau_ns (np.ndarray) – Lifetime value in nanoseconds.

  • frequency_hz (float) – Excitation frequency in hertz.

Returns:

Tuple containing phasor coordinates for the supplied lifetime values.

Return type:

tuple[Any, ]

compute_lifetime(G, S)[source]#

Compute lifetime.

Parameters:
  • G (np.ndarray) – Phasor real coordinate.

  • S (np.ndarray) – Phasor imaginary coordinate or shift amount.

Returns:

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); discrete_phasor_lifetime() inverts the binned locus exactly.

Return type:

np.ndarray

compute_modulation_lifetime(G, S)[source]#

Compute modulation lifetime.

Parameters:
  • G (np.ndarray) – Phasor real coordinate.

  • S (np.ndarray) – Phasor imaginary coordinate or shift amount.

Returns:

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.

Return type:

Any

compute_normal_lifetime(G, S)[source]#

Compute the normal lifetime tau_N: the lifetime of the universal-semicircle point nearest to each phasor (normal_lifetime()).

Parameters:
  • G (np.ndarray) – Phasor real coordinate (IRF-calibrated, first harmonic).

  • S (np.ndarray) – Phasor imaginary coordinate.

Returns:

Normal lifetime map in nanoseconds.

Return type:

np.ndarray

compute_apparent_lifetimes(G, S)[source]#

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:

{"tau_phi", "tau_m", "tau_n"} maps in nanoseconds, from compute_lifetime(), compute_modulation_lifetime() and compute_normal_lifetime().

Return type:

dict[str, np.ndarray]

component_kernel(tau_ns, model='continuous')[source]#

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:
Returns:

S + (T,), summing to 1 along the last axis.

Return type:

np.ndarray

component_phasor(tau_ns, harmonic=1, model='continuous')[source]#

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 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 component_kernel()).

Returns:

(g, s) with the shape of tau_ns.

Return type:

tuple[Any, ]

compute_fractions(G, S, tau1_ns, tau2_ns, mask=None, hexbin_color=None, plot_graph=True, ax=None, half_circle=False, component_model='continuous')[source]#

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 component_phasor()): "continuous" (default, the universal semicircle – real instruments) or "bin_start" (pyfli’s PhotonCountSimulator / ContinuousSimulator data).

Returns:

(A1, A2): intensity (photon) fractions of the two components, from the projection of each phasor onto the line between the component phasors.

Return type:

tuple[Any, ]

analyze_biexponential_and_reconstruct(G, S, irf, tau1_ns=None, tau2_ns=None, plot=True, axes=None, component_model='continuous', h_shift=None, v_shift=None)[source]#

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. 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:

Reconstructed decays (H, W, T): the solver’s forward model (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).

Return type:

Any

generate_intensity_image(decay)[source]#

Generate intensity image.

Parameters:

decay (np.ndarray) – Time-resolved decay signal or decay cube.

Returns:

Intensity image obtained by integrating the decay along the time axis.

Return type:

np.ndarray

save_phasors_hdf5(Gc, Sc, tau_phasor, save_file)[source]#

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:

No object is returned; the function save phasors hdf5.

Return type:

None