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

_bi_pixel(zk, rot, whiten, w, lo, up, margin)

_clipped_modulation(z)

_harmonic_axis(z)

bi_exponential_offset(z, noise, frequency_hz)

Per-pixel offset of a bi-exponential decay from K >= 3 harmonics.

bracket_violations(t0_map, lower, upper[, ...])

Pixels whose modelled t0 lies outside [lower - tol, upper + tol].

calibrate_phasors(z_raw, z_irf)

Calibrated phasors z_k = z~_k / z~^I_k (as PhasorAnalyzer.calibrate()) for the harmonics of z_raw (K, ...); z_irf is (>= K,) or (>= K, ...).

combine_offsets(t0_k, cov[, ...])

Generalised least-squares mono-exponential test across harmonics (paper eq.

correct_phasors(G, S, t0_ns, frequency_hz)

Remove the offset from calibrated phasor stacks (K, ...): z_k <- e^{-i k omega t0} z_k (paper eq.

fit_offset_surface(t0_hat, accepted[, ...])

Spatial model t0(r) from accepted pixels of a 2-D t0_hat map: the median for order=0, otherwise a weighted polynomial sum_{i+j<=order} theta_ij x^i y^j on pixel coordinates scaled to [-1, 1].

h_shift_from_t0(t0_ns, time_axis_ns)

Solver/simulator h_shift for a harmonic offset t0: t0 + dt/2.

harmonic_phasors(analyzer, decay[, n_harmonics])

Raw complex phasors G + iS of decay at harmonics 1..n_harmonics, from PhasorAnalyzer.create_phasor_cpu().

imbalance_offset(z, frequency_hz[, noise, ...])

Closed-form c, tau and t0 under modulation imbalance c != 1 (paper eq.

modulation_factor(n_counts, v_shift, n_gates)

Modulation imbalance c = (1 - beta) / (1 - beta_I) of paper eq.

mono_offset(z, frequency_hz[, t0_guess_ns])

Per-harmonic mono-exponential offset and lifetime (paper eq.

offset_bracket(z, frequency_hz[, t0_guess_ns])

Two-sided bracket max_k t0_k <= t0 <= min_k phi_k / (k omega) (paper eq.

offset_covariance(noise, frequency_hz[, ...])

Delta-method covariance of the per-harmonic offsets t0_k (paper eq.

phasor_noise(z_raw, z_irf, n_photons, ...[, ...])

Shot-noise covariance of the calibrated phasors in each phasor's own rotated frame X + iY = e^{-i phi_k} z_k (paper eq.

select_mono(chi2, dof[, alpha])

Pixels consistent with the offset model: chi2 < chi2_{dof, 1-alpha} (dof from combine_offsets() or bi_exponential_offset()).

t0_from_h_shift(h_shift_ns, time_axis_ns)

Inverse of h_shift_from_t0().

unwrap_phases(z, frequency_hz[, t0_guess_ns])

Phases phi_k of calibrated phasors z (K, ...), unwrapped beyond the principal value.

Classes

HarmonicOffset(analyzer)

Pixelwise t0 estimation and correction on top of a PhasorAnalyzer (n_harmonics >= 2; its time axis must be gate_starts() of the period 1 / frequency over which the phasors are computed).

harmonic_phasors(analyzer, decay, n_harmonics=None)[source]#

Raw complex phasors G + iS of decay at harmonics 1..n_harmonics, from PhasorAnalyzer.create_phasor_cpu().

Returns:

(n_harmonics,) + decay.shape[:-1]; n_harmonics defaults to the analyzer’s.

Return type:

np.ndarray

Parameters:
calibrate_phasors(z_raw, z_irf)[source]#

Calibrated phasors z_k = z~_k / z~^I_k (as PhasorAnalyzer.calibrate()) for the harmonics of z_raw (K, ...); z_irf is (>= K,) or (>= K, ...).

Parameters:
  • z_raw (ArrayLike)

  • z_irf (ArrayLike)

Return type:

ndarray

unwrap_phases(z, frequency_hz, t0_guess_ns=0.0)[source]#

Phases phi_k of calibrated phasors z (K, ...), unwrapped beyond the principal value. Since phi_k lies in [k omega t0, k omega t0 + pi/2), each harmonic is taken within pi of k omega (L + U) / 2 + pi/4, the centre of the bracket [L, U] of eq. 7 built from the lower harmonics; this is unique while k omega (U - L) < 3 pi / 2. Unwrapping against k phi_1 (paper section 9) instead fails for long lifetimes at k >= 4. Harmonic 1 is centred on t0_guess_ns and needs |t0 - t0_guess| < 3T/8.

Parameters:
  • z (ArrayLike)

  • frequency_hz (float)

  • t0_guess_ns (ArrayLike)

Return type:

ndarray

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) and tau_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 when c = 1. The upper bound holds for any c > 0.

Parameters:
  • z (ArrayLike)

  • frequency_hz (float)

  • t0_guess_ns (ArrayLike)

Return type:

tuple[ndarray, ndarray]

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 involve z_{k+l} and z_{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 full K x K cross-harmonic form), from phasor_noise(). With include_lifetime, the joint covariance of (t0_1..t0_K, tau_1..tau_K), using d tau_k = -dX_k / (k omega m_k^2 sqrt(1 - m_k^2)).

Returns:

(..., K, K), or (..., 2K, 2K) with include_lifetime, in ns^2.

Return type:

np.ndarray

Parameters:
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 t0 on K observations (dof = K - 1); with tau_k and a joint cov from offset_covariance(..., include_lifetime=True), two parameters (t0, tau) on 2K observations (dof = 2K - 2), which also tests that the modulation lifetimes agree. full_covariance=False drops the cross terms.

Returns:

"t0", "t0_se", "tau" and "tau_se" (None without tau_k), "chi2", "reduced_chi2" (chi2 / dof), "dof" and "n_params". Pixels with non-finite inputs are NaN.

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} (dof from combine_offsets() or bi_exponential_offset()).

Parameters:
  • chi2 (ArrayLike)

  • dof (int)

  • alpha (float)

Return type:

ndarray

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 >= 3 harmonics. Theorem 1 makes t0 unidentifiable for an arbitrary completely monotone decay, but under the bi-exponential model z_k = e^{i k omega t0} (A / (1 - i k omega tau1) + (1 - A) / (1 - i k omega tau2)) the 2K real data determine the four unknowns (t0, tau1, tau2, A). Each pixel is fitted by weighted least squares, whitened by the shot-noise covariance of phasor_noise(), with t0 inside its bracket (offset_bracket()) widened by margin_ns. A = 1 is the mono estimate.

Returns:

"t0", "t0_se", "tau1", "tau2", "alpha1" (photon fraction of tau1), "chi2" and "reduced_chi2", each (...) (NaN where the noise is undefined), "dof" = 2K - 4 and "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, tau and t0 under modulation imbalance c != 1 (paper eq. 12): weighted least squares of 1 / 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 makes chi2 (K - 2 degrees of freedom) a test of constant c. Unweighted if None.

  • t0_guess_ns (array_like) – See unwrap_phases().

Returns:

"c", "tau" (ns), "t0" (ns, weighted mean of "t0_k"), "t0_k" (K, ...), "chi2", "reduced_chi2" (NaN for K = 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’s v_shift): beta = n_gates v_shift / n_counts for the sample and beta_I = n_gates irf_v_shift / irf_counts for the IRF trace. Dividing calibrated phasors by c restores c = 1 exactly.

Parameters:
  • n_counts (ArrayLike)

  • v_shift (ArrayLike)

  • n_gates (int)

  • irf_counts (ArrayLike | None)

  • irf_v_shift (ArrayLike)

Return type:

ndarray

h_shift_from_t0(t0_ns, time_axis_ns)[source]#

Solver/simulator h_shift for a harmonic offset t0: 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 is k omega (h_shift - dt/2).

Parameters:
  • t0_ns (ArrayLike)

  • time_axis_ns (ArrayLike)

Return type:

ndarray

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:

ndarray

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.

Parameters:
  • G (ArrayLike)

  • S (ArrayLike)

  • t0_ns (ArrayLike)

  • frequency_hz (float)

Return type:

tuple[ndarray, ndarray]

fit_offset_surface(t0_hat, accepted, weights=None, order=0)[source]#

Spatial model t0(r) from accepted pixels of a 2-D t0_hat map: the median for order=0, otherwise a weighted polynomial sum_{i+j<=order} theta_ij x^i y^j on pixel coordinates scaled to [-1, 1].

Returns:

(t0_map, theta); theta is (median,) for order=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 t0 lies outside [lower - tol, upper + tol].

Parameters:
  • t0_map (ArrayLike)

  • lower (ArrayLike)

  • upper (ArrayLike)

  • tol_ns (ArrayLike)

Return type:

ndarray

class HarmonicOffset(analyzer)[source]#

Bases: object

Pixelwise t0 estimation and correction on top of a PhasorAnalyzer (n_harmonics >= 2; its time axis must be gate_starts() of the period 1 / frequency over 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 of t0_k alone (dof = K - 1; see combine_offsets()). A known per-gate background v_shift (scalar or (H, W), e.g. the solver’s v_shift_map) and irf_v_shift give c (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 has dof = 2K - 4.

Returns:

z (calibrated phasors (K, H, W)), t0_k, tau_k, lower, upper, cov, c, the combine_offsets() keys with t0 as t0_hat (and tau as tau_hat), accepted, t0_map, h_shift_map (solver convention, h_shift_from_t0()), theta and violations (rejected pixels whose bracket excludes t0_map). For the bi-exponential model, the bi_exponential_offset() keys with t0 as t0_hat and tau1, tau2, alpha1 as tau1_hat, tau2_hat, alpha1_hat, and cov = None.

Return type:

dict[str, Any]

Parameters:
  • decay (ArrayLike)

  • irf (ArrayLike)

  • alpha (float)

  • order (int)

  • excess_noise (float)

  • full_covariance (bool)

  • include_lifetime (bool)

  • t0_guess_ns (ArrayLike)

  • v_shift (ArrayLike | None)

  • irf_v_shift (ArrayLike)

  • model (str)

  • n_jobs (int)

correct(G, S, t0_ns)[source]#

Rotate calibrated phasor stacks by the offset (correct_phasors()).

Parameters:
  • G (ArrayLike)

  • S (ArrayLike)

  • t0_ns (ArrayLike)

Return type:

tuple[ndarray, ndarray]