pyfli.phasor.phasorS.phasor_simple#
Compact phasor analyzer for CPU and optional GPU workflows.
Classes
|
Compute, calibrate, and interpret FLI phasors from decay data. |
- class PhasorAnalyzer(frequency_hz, time_axis_ns, n_harmonics=1, device=None)[source]#
Bases:
PhasorPlotsMixinCompute, 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 ofngates tiling one period1 / 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, matchingcalibrate().
- 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).
- calibrate_reference_pixelwise(G, S, ref_data, ref_lifetime_ns=None)[source]#
Correctly spelled name of
calibratre_reference_pixelwise()(same arguments and result).
- 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, matchingcalibrate_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, withomegathe laser (first harmonic) angular frequency: pass first-harmonic phasors, or divide bykfor harmonick. 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) / omegain ns,M^2 = G^2 + S^2, withomegathe laser (first harmonic) angular frequency: pass first-harmonic phasors, or divide bykfor harmonick.- 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, fromcompute_lifetime(),compute_modulation_lifetime()andcompute_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:
tau_ns (
Any) – Lifetime(s) in nanoseconds (any shapeS).model (
str) –"continuous": excitation photons arrive anywhere inside their bin, as in a real instrument (the forward model’sexcitation="uniform",gate_integrated_kernel(); equal toperiodic_instrument_exponential())."bin_start": every excitation at a bin start, as in pyfli’s simulators (excitation="bin_start"; equal toperiodic_bin_exponential()).
- 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 pointlifetime_to_phasor(), exactly.model="bin_start"(data simulated by pyfli’sPhotonCountSimulator/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"(seecomponent_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 (seecomponent_phasor()):"continuous"(default, the universal semicircle – real instruments) or"bin_start"(pyfli’sPhotonCountSimulator/ContinuousSimulatordata).
- 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;Noneis 0.v_shift (
float | np.ndarray | None) – Constant added to every gate, scalar or(H, W);Noneis 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 toA1 + 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: