pyfli.phasor.harmonic_offset#
Fit-free pixelwise IRF-decay timing offset t0 from multi-harmonic phasors: mono
estimate, bracket for any completely monotone decay, chi-square selection and correction.
Functions
|
|
|
|
|
|
|
Per-pixel offset of a bi-exponential decay from |
|
Pixels whose modelled |
|
Calibrated phasors |
|
Generalised least-squares mono-exponential test across harmonics (paper eq. |
|
Remove the offset from calibrated phasor stacks |
|
Spatial model |
|
Solver/simulator |
|
Raw complex phasors |
|
Closed-form |
|
Modulation imbalance |
|
Per-harmonic mono-exponential offset and lifetime (paper eq. |
|
Two-sided bracket |
|
Delta-method covariance of the per-harmonic offsets |
|
Shot-noise covariance of the calibrated phasors in each phasor's own rotated frame |
|
Pixels consistent with the offset model: |
|
Inverse of |
|
Phases |
Classes
|
Pixelwise |
- harmonic_phasors(analyzer, decay, n_harmonics=None)[source]#
Raw complex phasors
G + iSof decay at harmonics1..n_harmonics, fromPhasorAnalyzer.create_phasor_cpu().- Returns:
(n_harmonics,) + decay.shape[:-1]; n_harmonics defaults to the analyzer’s.- Return type:
np.ndarray- Parameters:
analyzer (PhasorAnalyzer)
decay (ArrayLike)
n_harmonics (int | None)
- calibrate_phasors(z_raw, z_irf)[source]#
Calibrated phasors
z_k = z~_k / z~^I_k(asPhasorAnalyzer.calibrate()) for the harmonics of z_raw(K, ...); z_irf is(>= K,)or(>= K, ...).- Parameters:
z_raw (ArrayLike)
z_irf (ArrayLike)
- Return type:
- unwrap_phases(z, frequency_hz, t0_guess_ns=0.0)[source]#
Phases
phi_kof calibrated phasorsz(K, ...), unwrapped beyond the principal value. Sincephi_klies in[k omega t0, k omega t0 + pi/2), each harmonic is taken withinpiofk omega (L + U) / 2 + pi/4, the centre of the bracket[L, U]of eq. 7 built from the lower harmonics; this is unique whilek omega (U - L) < 3 pi / 2. Unwrapping againstk phi_1(paper section 9) instead fails for long lifetimes atk >= 4. Harmonic 1 is centred on t0_guess_ns and needs|t0 - t0_guess| < 3T/8.
- mono_offset(z, frequency_hz, t0_guess_ns=0.0)[source]#
Per-harmonic mono-exponential offset and lifetime (paper eq. 6),
t0_k = (phi_k - arccos m_k) / (k omega)andtau_k = sqrt(m_k^-2 - 1) / (k omega).- Returns:
(t0_k, tau_k)in ns, each(K, ...). Moduli above 1 are clipped to 1.- Return type:
tuple[np.ndarray,np.ndarray]- Parameters:
z (ArrayLike)
frequency_hz (float)
t0_guess_ns (ArrayLike)
- offset_bracket(z, frequency_hz, t0_guess_ns=0.0)[source]#
Two-sided bracket
max_k t0_k <= t0 <= min_k phi_k / (k omega)(paper eq. 7), valid for every completely monotone decay whenc = 1. The upper bound holds for anyc > 0.
- phasor_noise(z_raw, z_irf, n_photons, n_harmonics, excess_noise=1.0)[source]#
Shot-noise covariance of the calibrated phasors in each phasor’s own rotated frame
X + iY = e^{-i phi_k} z_k(paper eq. 8), including the cross-harmonic terms that involvez_{k+l}andz_{k-l}.- Parameters:
z_raw (
array_like) – Raw (uncalibrated) sample phasors(>= 2K, ...).z_irf (
array_like) – Raw IRF phasors(>= K,)or(>= K, ...).n_photons (
array_like) – Detected counts per pixel (background included), shape(...).n_harmonics (
int) –K.excess_noise (
float) – Variance multiplier: ICCD excess-noise factor times counts per photon.
- Returns:
"XX","YY","XY"(Cov(X_k, Y_l)),"YX", each(..., K, K), and"m", the calibrated moduli(..., K).- Return type:
dict[str,np.ndarray]
- offset_covariance(noise, frequency_hz, include_lifetime=False)[source]#
Delta-method covariance of the per-harmonic offsets
t0_k(paper eq. 9, with the fullK x Kcross-harmonic form), fromphasor_noise(). With include_lifetime, the joint covariance of(t0_1..t0_K, tau_1..tau_K), usingd tau_k = -dX_k / (k omega m_k^2 sqrt(1 - m_k^2)).
- combine_offsets(t0_k, cov, full_covariance=True, tau_k=None)[source]#
Generalised least-squares mono-exponential test across harmonics (paper eq. 10). With t0_k only, one parameter
t0onKobservations (dof = K - 1); with tau_k and a joint cov fromoffset_covariance(..., include_lifetime=True), two parameters(t0, tau)on2Kobservations (dof = 2K - 2), which also tests that the modulation lifetimes agree.full_covariance=Falsedrops the cross terms.- Returns:
"t0","t0_se","tau"and"tau_se"(Nonewithout tau_k),"chi2","reduced_chi2"(chi2 / dof),"dof"and"n_params". Pixels with non-finite inputs areNaN.- Return type:
dict[str,Any]- Parameters:
t0_k (ArrayLike)
cov (ArrayLike)
full_covariance (bool)
tau_k (ArrayLike | None)
- select_mono(chi2, dof, alpha=0.05)[source]#
Pixels consistent with the offset model:
chi2 < chi2_{dof, 1-alpha}(doffromcombine_offsets()orbi_exponential_offset()).
- bi_exponential_offset(z, noise, frequency_hz, t0_guess_ns=0.0, margin_ns=0.1, n_jobs=-1)[source]#
Per-pixel offset of a bi-exponential decay from
K >= 3harmonics. Theorem 1 makest0unidentifiable for an arbitrary completely monotone decay, but under the bi-exponential modelz_k = e^{i k omega t0} (A / (1 - i k omega tau1) + (1 - A) / (1 - i k omega tau2))the2Kreal data determine the four unknowns(t0, tau1, tau2, A). Each pixel is fitted by weighted least squares, whitened by the shot-noise covariance ofphasor_noise(), witht0inside its bracket (offset_bracket()) widened by margin_ns.A = 1is the mono estimate.- Returns:
"t0","t0_se","tau1","tau2","alpha1"(photon fraction oftau1),"chi2"and"reduced_chi2", each(...)(NaNwhere the noise is undefined),"dof"=2K - 4and"n_params"= 4.- Return type:
dict[str,Any]- Parameters:
- imbalance_offset(z, frequency_hz, noise=None, t0_guess_ns=0.0)[source]#
Closed-form
c,tauandt0under modulation imbalancec != 1(paper eq. 12): weighted least squares of1 / m_k^2 = P + Q k^2.- Parameters:
z (
array_like) – Calibrated phasors(K >= 2, ...).frequency_hz (
float) – Laser repetition frequency in hertz.noise (
dict | None) –phasor_noise()output; gives inverse-variance weights and makeschi2(K - 2degrees of freedom) a test of constantc. Unweighted ifNone.t0_guess_ns (
array_like) – Seeunwrap_phases().
- Returns:
"c","tau"(ns),"t0"(ns, weighted mean of"t0_k"),"t0_k"(K, ...),"chi2","reduced_chi2"(NaNforK = 2),"dof"and"n_params"(P,Q).- Return type:
dict[str,np.ndarray]
- modulation_factor(n_counts, v_shift, n_gates, irf_counts=None, irf_v_shift=0.0)[source]#
Modulation imbalance
c = (1 - beta) / (1 - beta_I)of paper eq. 3 from the constant per-gate backgrounds (the solver’sv_shift):beta = n_gates v_shift / n_countsfor the sample andbeta_I = n_gates irf_v_shift / irf_countsfor the IRF trace. Dividing calibrated phasors bycrestoresc = 1exactly.
- h_shift_from_t0(t0_ns, time_axis_ns)[source]#
Solver/simulator
h_shiftfor a harmonic offsett0:t0 + dt/2. The forward model (pyfli.cm_funcs.forward_model.model_numpy(),pyfli.reconstruction.ParamToDecay) and the simulators excite at the start of each IRF gate and integrate the decay over gates[t, t + dt), so the calibrated phasor phase isk omega (h_shift - dt/2).- Parameters:
t0_ns (ArrayLike)
time_axis_ns (ArrayLike)
- Return type:
- t0_from_h_shift(h_shift_ns, time_axis_ns)[source]#
Inverse of
h_shift_from_t0().- Parameters:
h_shift_ns (ArrayLike)
time_axis_ns (ArrayLike)
- Return type:
- correct_phasors(G, S, t0_ns, frequency_hz)[source]#
Remove the offset from calibrated phasor stacks
(K, ...):z_k <- e^{-i k omega t0} z_k(paper eq. 13), exact for every decay.
- fit_offset_surface(t0_hat, accepted, weights=None, order=0)[source]#
Spatial model
t0(r)from accepted pixels of a 2-Dt0_hatmap: the median fororder=0, otherwise a weighted polynomialsum_{i+j<=order} theta_ij x^i y^jon pixel coordinates scaled to[-1, 1].- Returns:
(t0_map, theta);thetais(median,)fororder=0.- Return type:
tuple[np.ndarray,np.ndarray]- Parameters:
t0_hat (ArrayLike)
accepted (ArrayLike)
weights (ArrayLike | None)
order (int)
- bracket_violations(t0_map, lower, upper, tol_ns=0.0)[source]#
Pixels whose modelled
t0lies outside[lower - tol, upper + tol].- Parameters:
t0_map (ArrayLike)
lower (ArrayLike)
upper (ArrayLike)
tol_ns (ArrayLike)
- Return type:
- class HarmonicOffset(analyzer)[source]#
Bases:
objectPixelwise
t0estimation and correction on top of aPhasorAnalyzer(n_harmonics >= 2; its time axis must begate_starts()of the period1 / frequencyover which the phasors are computed).- Parameters:
analyzer (PhasorAnalyzer)
- estimate(decay, irf, alpha=0.05, order=0, excess_noise=1.0, full_covariance=True, include_lifetime=False, t0_guess_ns=0.0, v_shift=None, irf_v_shift=0.0, model='mono-exponential', n_jobs=-1)[source]#
Run the full pipeline on a decay cube
(H, W, T)and a 1-D or per-pixel IRF. include_lifetime tests(t0_k, tau_k)jointly (dof = 2K - 2) instead oft0_kalone (dof = K - 1; seecombine_offsets()). A known per-gate background v_shift (scalar or(H, W), e.g. the solver’sv_shift_map) and irf_v_shift givec(modulation_factor()), which is divided out of the calibrated phasors and their noise.model="bi-exponential"(n_harmonics >= 3) estimates each pixel’s offset under the bi-exponential model (bi_exponential_offset()), so bi-exponential samples need no mono-exponential pixels; the chi-square test then hasdof = 2K - 4.- Returns:
z(calibrated phasors(K, H, W)),t0_k,tau_k,lower,upper,cov,c, thecombine_offsets()keys witht0ast0_hat(andtauastau_hat),accepted,t0_map,h_shift_map(solver convention,h_shift_from_t0()),thetaandviolations(rejected pixels whose bracket excludest0_map). For the bi-exponential model, thebi_exponential_offset()keys witht0ast0_hatandtau1,tau2,alpha1astau1_hat,tau2_hat,alpha1_hat, andcov=None.- Return type:
dict[str,Any]- Parameters: