pyfli.phasor.phasorSEPL.phasors#
phasors.py#
Analytical and semi-analytical phasor coordinate calculators for each acquisition mode described in Michalet 2021 (DOI: 10.1063/5.0027834).
Every public function has signature:
phasor_*(tau, cfg) -> tuple[float | np.ndarray, float | np.ndarray]
returning (g, s) coordinates in the phasor plane.
Convention#
g = Re[ z(τ) ] (cosine / real component) s = Im[ z(τ) ] (sine / imaginary component)
z(τ) is the normalised first-harmonic Fourier coefficient of the luminescence decay I(t).
References
Michalet X., AIP Advances 11, 035331 (2021), Sec. III–V. ISS Technical Note: “FLIM Analysis using the Phasor Plots”.
Functions
|
Phasor coordinates for a periodic single-exponential decay (PSED) in the continuous / ideal TCSPC limit (Dirac IRF, full-period recording). |
|
Phasor coordinates for a PSED sampled into N equal bins over one period T. |
|
Dispatch to the correct phasor function based on cfg.mode. |
|
Phasor of a PSED measured with N equidistant square gates of width W. |
|
Phasor coordinates for a PSED measured through a single square gate of width W starting at t = 0, with Dirac IRF. |
|
Phasor when the excitation pulse (or IRF peak) is offset by t₀ within the recording window. |
|
Phasor when only the first T_rec < T nanoseconds of the decay are recorded. |
- phasor_continuous(tau, cfg)[source]#
Phasor coordinates for a periodic single-exponential decay (PSED) in the continuous / ideal TCSPC limit (Dirac IRF, full-period recording).
This is the canonical formula whose locus is the universal semicircle of radius ½ centred at (½, 0).
Equations (Michalet 2021, Eq. 15 / ISS technical note Eq. 10):
g(τ) = 1 / (1 + ω²τ²) s(τ) = ωτ / (1 + ω²τ²)
where ω = 2π·n/T.
- Parameters:
tau (
array_like) – Fluorescence lifetime(s) in nanoseconds.cfg (
AcquisitionConfig) – Must supply: omega (derived from T_ns and harmonic).
- Returns:
g, s – Real and imaginary phasor coordinates (shape matches tau).
- Return type:
np.ndarray
- phasor_discrete(tau, cfg)[source]#
Phasor coordinates for a PSED sampled into N equal bins over one period T.
The locus is an arc of a circle (not the universal semicircle). Its centre and radius depend on N and the harmonic n; it converges to the universal semicircle as N → ∞.
Algorithm: direct discrete Fourier coefficient (Michalet 2021, Sec. III C):
I_k = ∫_{k·Δt}^{(k+1)·Δt} e^{-t/τ} dt = e^{-k·Δt/τ} · (1 − e^{-Δt/τ}) z̃ = Σ_k I_k · e^{i 2π n k / N} / Σ_k I_k
- Parameters:
tau (
array_like) – Lifetime(s) in ns.cfg (
AcquisitionConfig) – Requires: T_ns, N_bins, harmonic.
- Returns:
g, s
- Return type:
np.ndarray
- phasor_gated_single(tau, cfg)[source]#
Phasor coordinates for a PSED measured through a single square gate of width W starting at t = 0, with Dirac IRF.
From Michalet 2021, Sec. III B (Eq. for gated PSED phasor):
The gate selects the interval [0, W]. The T-periodic normalisation factor is α(τ,W,T) = (1 − e^{-W/τ}) / (1 − e^{-T/τ}).
- g_gate(τ) = α · 1/(1+ω²τ²) · [1 − e^{-W/τ}(cos(ωW) + ωτ·sin(ωW))]
/ (1 − e^{-W/τ})
- s_gate(τ) = α · 1/(1+ω²τ²) · [ωτ − e^{-W/τ}(ωτ·cos(ωW) − sin(ωW))]
/ (1 − e^{-W/τ})
Simplification gives the scaled form used here.
- Parameters:
tau (
array_like) – Lifetime(s) in ns.cfg (
AcquisitionConfig) – Requires: T_ns, gate_width_frac, harmonic.
- Returns:
g, s
- Return type:
np.ndarray
- phasor_gated_N(tau, cfg)[source]#
Phasor of a PSED measured with N equidistant square gates of width W.
Gate k starts at t_k = k · θ where θ = T / N_gates.
The (discrete) phasor is (Michalet 2021, Sec. III C 3):
I_k = e^{-t_k/τ} − e^{-(t_k+W)/τ} z̃ = Σ_k I_k · e^{i 2π n k / N_gates} / Σ_k I_k
- Parameters:
tau (
array_like) – Lifetime(s) in ns.cfg (
AcquisitionConfig) – Requires: T_ns, N_gates, gate_width_frac, harmonic.
- Returns:
g, s
- Return type:
np.ndarray
- phasor_truncated(tau, cfg)[source]#
Phasor when only the first T_rec < T nanoseconds of the decay are recorded.
This is a common experimental artefact with high-repetition-rate lasers. The SEPL deforms and phasors can fall outside the universal semicircle, leading to erroneous multi-exponential interpretations if uncorrected.
Analytical form (Michalet 2021, Sec. V):
Using partial integration of e^{-t/τ} · e^{iωt} over [0, T_rec]:
- ∫₀^{T_rec} e^{-t/τ} e^{iωt} dt = τ · [1 − e^{-(1/τ−iω)T_rec}]
/ (1 − iωτ)
Normalised by ∫₀^{T_rec} e^{-t/τ} dt = τ(1 − e^{-T_rec/τ})
- Parameters:
tau (
array_like) – Lifetime(s) in ns.cfg (
AcquisitionConfig) – Requires: T_ns, T_rec_frac, harmonic.
- Returns:
g, s
- Return type:
np.ndarray
- phasor_offset(tau, cfg)[source]#
Phasor when the excitation pulse (or IRF peak) is offset by t₀ within the recording window.
An offset of t₀ introduces a pure rotation in the phasor plane (Michalet 2021, Sec. IV):
z_offset(τ) = z_continuous(τ) · e^{−iωt₀}
which gives:
g_off = g·cos(ωt₀) + s·sin(ωt₀) s_off = s·cos(ωt₀) − g·sin(ωt₀)
- Parameters:
tau (
array_like) – Lifetime(s) in ns.cfg (
AcquisitionConfig) – Requires: T_ns, t0_frac, harmonic.
- Returns:
g, s
- Return type:
np.ndarray