2. Fitting Example (NLSF & MLE) in CPU - Bi-exponential FLI data processing#

A simulated, full 3-D fluorescence lifetime image dataset of a two-well plate is generated (refer to the “Whole Image Simulation” example). Each well is assigned a different set of lifetime / FRET parameters. The data is then processed with fitted pixel by pixel with two estimators and the phasor method:

  • Non-linear least squares (NLSF): minimizes the sum of squared residuals between the IRF-convolved model and the decay.

  • Maximum likelihood estimation (MLE): maximizes the Poisson log-likelihood of the photon counts. It models the counting statistics directly, so it remains accurate at low photon counts, where least squares becomes biased.

This example walks through:

  • Simulating the two-well FLI data and inspecting the ground-truth parameters

  • Comparing NLSF and MLE on a single pixel

  • Fitting the whole image with NLSF and with MLE

  • Comparing the fitted maps and their distributions with the ground truth

  • Inspecting the fit and residuals at individual pixels

  • The phasor computation, with pixel-wise IRF calibration to benchmark the results.

  • Phasor plot and pixel-wise phasor color overlays

Author - Vikas

## importing the modules required for this work
import sys

import numpy as np

sys.path.insert(0, "ex_helper")  # local helper for synthetic image generation

from sim_general_image import ROIMaskGenerator

from pyfli.analysis.utils import random_true_pixel
from pyfli.analyticalWorkflow import AnalyticalHelpers
from pyfli.data_cc import Normalization
from pyfli.data_text import MessageDisplay
from pyfli.data_vnp import ColorProcessor, DataViewer
from pyfli.io import DataOperations
from pyfli.phasor.phasorS import PhasorAnalyzer
from pyfli.simulator import FLIModelImageGenerator

2.1. Loading the IRF#

# Path to the local IRF file
IRF_PATH = "<select file/folder path>"
loader = DataOperations(irf_path=IRF_PATH)
irf_data = loader.load_irf()

gate_delay = 12.5 / irf_data.shape[2]
num_gates = irf_data.shape[2]
freq = AnalyticalHelpers(
    laser_period=12.5, gate_delay=gate_delay, num_gate=num_gates
).freq_computation()
INFO:pyfli:Initiating IRF load from: <select file/folder path>

2.2. Simulation configuration#

MODEL_TYPE selects the decay model for both the simulation and the fits. get_config builds a per-well configuration by overriding BASE_CONFIG.

SEED = 0
# select the type of decay model to simulate
MODEL_TYPE = "bi-exponential"
if MODEL_TYPE == "bi-exponential":
    mono_fraction = 0.0
elif MODEL_TYPE == "mono-exponential":
    mono_fraction = 1.0
else:
    mono_fraction = 0.4  # fraction of mono-exponential model in sampled data

# Your constant, default configuration
BASE_CONFIG = {
    # Modular Noise
    "jitter": False,  # offset artifact (due to jitter)
    "dcr_on": True,  # Dark Count Rate (thermal background)
    "poisson": False,  # Shot noise — Large detector only
    "qe_on": True,  # Quantum efficiency scaling
    "read_noise_on": False,  # Gaussian read noise — Large detector only
    # Sensor
    "sensor_type": "discrete",  # "continuous" | "discrete"
    "bit": 12,
    "dcr": 0.08,  # Mean dark counts per bin
    "laser_feq": freq[1],  # Laser repetition rate (MHz) → period = 12.5 ns
    "round_on": True,  # Round photon counts to integers — Macro_sim only
    "clip_on": True,  # Clip at bit-depth ceiling — Macro_sim: max_adc_val; TCSPC: max_bin_count
    # Fluorescence Physics (FLI / FRET)
    "tau2": (1, 1),  # τ₂ ~ TruncNormal(mu=1 ns, sigma=0.5 ns)
    "tau2_dist": "beta",  # if dist "beta" or "normal" (default)
    "tau2_beta_range": (2.5, 0.1),
    "efficiency": (1, 1),  # FRET efficiency E ~ Beta(2, 5)  → [0.1, 1.0]
    "A1_fraction": (1, 1),  # Amplitude fraction A₁ ~ Beta(2, 5) → [0.05, 0.95]
    "photo_count": (2, 5),  # Peak intensity ~ Beta(2, 5) × max_adc - large detectors
    "mono_fraction": mono_fraction,  # Fraction of pixels forced mono-exponential (0.0 = all bi-exp)
    "n_cycles": (1_500_000, 2_000_000),  # Accumulation cycles — for photon counter
}
def get_config(**kwargs):
    """Create a config by overriding defaults with specific test parameters."""
    config = BASE_CONFIG.copy()
    config.update(kwargs)
    return config
# Shared plotting / phasor configuration used by the two-well example below
colorset = "rainbow"
freq_hz = freq[1] * 1e6
jet_m_well = ColorProcessor().lowest_zero("jet")
bg_color = "black"  # either "black" or "white"
ph_cols_ = "viridis_r"

2.3. Two wells example#

A two-well plate is simulated, with each well assigned a different set of ground-truth lifetime / FRET parameters.

from sim_general_image import WellPlateShape

h_well, w_well = 128, 256
generator_well = ROIMaskGenerator((h_well, w_well), top=10, bottom=10, left=10, right=10)
TwoWells = WellPlateShape(rows=1, cols=2, gap=0.15)

custom_intensities_well = [ 0.6, 1.0]
_ = generator_well.plot_preview(
    TwoWells,
    bit_depth=10,
    intensities=custom_intensities_well,
    show=True,
)
../_images/68e513c73d05e0b29964a578c427233d5cac99f087932e56eba86899ad7e6ef6.png
ROI0_well = {}
ROI1_well = get_config(
    tau2_beta_range=(0.1, 1.8),
    efficiency = (5, 2),  
    A1_fraction = (7, 13),
)
ROI2_well = get_config(
    tau2_beta_range=(0.2, 0.8),
    efficiency = (10, 10),  
    A1_fraction = (15, 10),
)
img_intensity_well = generator_well.generate_intensity_image(
    TwoWells, intensities=custom_intensities_well
)
img_cluster_well = generator_well.generate_cluster_mask(TwoWells)
b_bool_mask_well = generator_well.generate_binary_mask(TwoWells)

np.random.seed(SEED)
simulated_img_well = FLIModelImageGenerator(
    irf_data=irf_data[120, 40, :],
    intensity_image=img_intensity_well,
    roi_mask=img_cluster_well,
    roi_params=[dict(cfg, seed=SEED + k) for k, cfg in enumerate([ROI0_well, ROI1_well, ROI2_well])],
    method="PHOTON_COUNTER",
    verbose=True,
    bool_mask=b_bool_mask_well,
)

gt_data_well = simulated_img_well.generate_image()
INFO:pyfli:Generating PHOTON_COUNTER FLI Image [128x256x256]...
Simulating Pixels:   0%|          | 0/32768 [00:00<?, ?px/s]
                                                                          

Check the decay, IRF, and fit at a randomly selected pixel.

_decay_well = gt_data_well["raw_data"]["decay"]
_irf_well = gt_data_well["raw_data"]["irf"]
x_well, y_well = random_true_pixel(b_bool_mask_well)
TRs_well = gt_data_well["results"]["TR_maps"]
maps_well = gt_data_well["results"]["maps"]
print(f"the non-zero pixel selected for probing is ({x_well}, {y_well})")
irf_norm_well = Normalization(_irf_well).norm_scale(_decay_well)
DataViewer().plot_fli_px(
    data_list=[_decay_well, irf_norm_well, TRs_well["fit_map"], TRs_well["residual_map"]],
    pixel=(x_well, y_well),
    mode=[0, 1, 2],
    mode2=[1],
    names=["decay", "irf", "fit"],
    cmap=jet_m_well,
)
_ = MessageDisplay().get_pixel_summary(data_maps=maps_well, px=(x_well, y_well))
the non-zero pixel selected for probing is (37, 39)
../_images/4329337ec5673a768dae2ac7940ab18857c01fb31a7fbc45a5f6c457f3f6bbc1.png
INFO:pyfli:
  Pixel (37, 39)
  ─────────────────────
  A         12648.1992
  α         0.5470
  τ₁        0.1596
  τ₂        1.8703
  R²        —
  Red.χ²    —
  Raw.χ²    —
  Pearson   —
  v-shift   0.0800
  h-shift   0.0000
  ─────────────────────

Distribution of the simulated ground-truth parameters across the image, before computing phasors.

import matplotlib.pyplot as plt
import seaborn as sns

res_well = gt_data_well["results"]["maps"]

b_bool_mask_well_bool = b_bool_mask_well.astype(bool)
valid_px_well = np.argwhere(b_bool_mask_well)
rng_well = np.random.default_rng(0)
sample_idx_well = rng_well.choice(len(valid_px_well), size=min(300, len(valid_px_well)), replace=False)
sample_px_well = valid_px_well[sample_idx_well]
decay_sample_well = _decay_well[sample_px_well[:, 0], sample_px_well[:, 1], :]
irf_sample_well = _irf_well[sample_px_well[:, 0], sample_px_well[:, 1], :]
photon_count_sample_well = res_well["photon_count_map"][sample_px_well[:, 0], sample_px_well[:, 1]]

tau1_valid_well = res_well["tau1_map"][b_bool_mask_well_bool]
tau2_valid_well = res_well["tau2_map"][b_bool_mask_well_bool]
alpha1_valid_well = res_well["alpha1_map"][b_bool_mask_well_bool]
tau_mean_valid_well = res_well["tau_mean_map"][b_bool_mask_well_bool]
efficiency_valid_well = res_well["fret_efficiency_map"][b_bool_mask_well_bool]
photon_count_valid_well = res_well["photon_count_map"][b_bool_mask_well_bool]
tau_dif_well = tau2_valid_well - tau1_valid_well

fig, axes = plt.subplots(2, 5, figsize=(15, 8))

axes[0, 0].plot(decay_sample_well.T)
axes[0, 0].set_title("decay")
axes[0, 0].set_xlabel("bins")
axes[0, 0].set_ylabel("Photon Counts")

axes[0, 1].plot((irf_sample_well * photon_count_sample_well[:, None]).T)
axes[0, 1].set_title("irf * photon_count")
axes[0, 1].set_xlabel("bins")
axes[0, 1].set_ylabel("Photon Counts")

sns.histplot(data=tau_mean_valid_well, ax=axes[0, 2], kde=True, stat="density", color="tab:orange", alpha=0.4)
axes[0, 2].set_title("mean tau")
axes[0, 2].set_xlabel("Lifetime (ns)")

sns.histplot(data=tau_dif_well, ax=axes[0, 3], kde=True, stat="density", color="tab:orange", alpha=0.4)
axes[0, 3].set_title("Δ tau")
axes[0, 3].set_xlabel("Lifetime (ns)")

sns.histplot(data=efficiency_valid_well, ax=axes[0, 4], kde=True, stat="density", color="tab:green", alpha=0.4)
axes[0, 4].set_title("FRET Efficiency")
axes[0, 4].set_xlabel("Efficiency")

sns.histplot(data=tau1_valid_well, ax=axes[1, 0], kde=True, stat="density", color="tab:green", alpha=0.4)
axes[1, 0].set_title("tau1")
axes[1, 0].set_xlabel("Lifetime (ns)")

sns.histplot(data=tau2_valid_well, ax=axes[1, 1], kde=True, stat="density", color="tab:red", alpha=0.4)
axes[1, 1].set_title("tau2")
axes[1, 1].set_xlabel("Lifetime (ns)")

sns.histplot(data=alpha1_valid_well, ax=axes[1, 2], kde=True, stat="density", color="tab:purple", alpha=0.4)
axes[1, 2].set_title("alpha1")
axes[1, 2].set_xlabel("Amplitude Fraction")
axes[1, 2].set_xlim(0.0, 1.0)

axes[1, 3].scatter(tau_dif_well, alpha1_valid_well, s=8, alpha=0.3)
axes[1, 3].set_xlabel("Δ tau")
axes[1, 3].set_ylabel("fraction")

sns.histplot(data=photon_count_valid_well, ax=axes[1, 4], kde=True, stat="density", color="tab:purple", alpha=0.4)
axes[1, 4].set_title("photon_count")
axes[1, 4].set_xlabel("photons")

plt.tight_layout()
plt.show()
../_images/6311bf5e900d5785aff11db3a7c4d8b5debe703074594d1e2b434db5089a6b20.png

2.4. Lifetime fitting: NLSF and MLE#

For a bi-exponential model the fitted parameters are [S, alpha1, tau1, tau2, v_shift, h_shift]. Separating alpha1, tau1 and tau2 is harder than fitting a single lifetime, so the amplitude-weighted mean lifetime tau_mean is also compared below as the most robust summary of each pixel.

from pyfli.analysis.utils import plot_pixel_diagnostic
from pyfli.data_vnp import Plotter
from pyfli.solver import (
    BaseFLIFitter,
    BinnedFLIFitter,
    FittingComparator,
    FLICPUProcessor,
    MLEFLIFitter,
)

2.4.1. Single-pixel fit: NLSF vs MLE#

Before fitting the whole image, FittingComparator fits one randomly selected pixel with both estimators and plots the fits side by side:

  • "least_squares" uses BaseFLIFitter (NLSF)

  • "poisson" uses MLEFLIFitter (Poisson MLE)

p0 (initial guess) and bounds are left as None, so the fitter derives its own initial guess from the data. Both can be passed in the parameter order given above.

SHIFT_METHOD = "circular"
p0 = None
bounds = None

xd_well, yd_well = random_true_pixel(b_bool_mask_well)
pixel_decay_well = _decay_well[xd_well, yd_well, :]
pixel_irf_well = _irf_well[xd_well, yd_well, :]

comparator = FittingComparator(freq, BaseFLIFitter, MLEFLIFitter)
comp_results_table, comp_fig = comparator.compare_selected(
    ["least_squares", "poisson"],
    y_data=pixel_decay_well,
    irf_data=pixel_irf_well,
    model_type=MODEL_TYPE,
    shift_method=SHIFT_METHOD,
    p0=p0,
    bounds=bounds,
    yscale="linear",
    plot=True,
)
┌──────────────────────────────────────────────────────────────┐
│  FLI Fitting Results  |  BI-EXPONENTIAL                      │
│  2 methods queued                                            │
└──────────────────────────────────────────────────────────────┘


┌────────────────┬──────┬─────────┬─────────┬──────────┬──────────┬─────────┬──────────┬──────────┬─────────┬──────────┐
│ Method         │ Type │       A │       α │       τ₁ │       τ₂ │      R² │   Red.χ² │   Raw.χ² │ v-shift │  h-shift │
├────────────────┼──────┼─────────┼─────────┼──────────┼──────────┼─────────┼──────────┼──────────┼─────────┼──────────┤
│ LEAST_SQUARES  │ NLSF │ 12827.94 │  0.9703 │    0.657 │    1.567 │  0.9967 │   1.1191 │   274.41 │    0.05 │    0.005 │
│ POISSON        │ MLE  │ 12826.21 │  0.9382 │    0.649 │    1.183 │  0.9967 │   1.1240 │   274.15 │    0.05 │    0.004 │
└────────────────┴──────┴─────────┴─────────┴──────────┴──────────┴─────────┴──────────┴──────────┴─────────┴──────────┘
../_images/5378a7fd40902898d7d7b865acad26549c9e10f6f108a3745a011de222b9a808.png

2.4.2. Whole-image fitting#

Each pixel is fitted independently and in parallel on the CPU:

  • FLICPUProcessor(freq, fitter_class) spreads the per-pixel fits over n_jobs worker processes. The fitter class sets the estimator family.

  • BinnedFLIFitter(..., bin_radius=0) is the image-level entry point. A bin_radius of 0 fits every pixel as-is, and a larger radius sums each pixel with its neighbours first to raise the photon count.

  • max_iter caps the optimizer’s function evaluations per pixel.

On a machine with a CUDA GPU, FLIGPUProcessor can be used in place of FLICPUProcessor to fit all pixels as one batch.

2.4.2.1. NLSF#

MAX_ITER = 2000
N_JOBS = 7

nlsf_fitter = BinnedFLIFitter(FLICPUProcessor(freq, BaseFLIFitter), bin_radius=0)
results_nlsf = nlsf_fitter.fit(
    b_img=_decay_well,
    b_irf=_irf_well,
    estimator="least_squares",
    model_type=MODEL_TYPE,
    shift_method=SHIFT_METHOD,
    n_jobs=N_JOBS,
    data_name="simulated_wells_nlsf",
    max_iter=MAX_ITER,
)
INFO:pyfli:Engine: CPU Parallel Processor (via FLICPUProcessor)
Fitting Pixels (least_squares): 100%|██████████| 13226/13226 [03:09<00:00, 69.66px/s]

2.4.2.2. MLE#

The same pipeline is run with MLEFLIFitter and the "poisson" estimator. MLE takes longer per pixel than NLSF.

MAX_ITER = 1500
mle_fitter = BinnedFLIFitter(FLICPUProcessor(freq, MLEFLIFitter), bin_radius=0)
results_mle = mle_fitter.fit(
    b_img=_decay_well,
    b_irf=_irf_well,
    estimator="poisson",
    model_type=MODEL_TYPE,
    shift_method=SHIFT_METHOD,
    n_jobs=N_JOBS,
    data_name="simulated_wells_mle",
    max_iter=MAX_ITER,
)
INFO:pyfli:Engine: CPU Parallel Processor (via FLICPUProcessor)
Fitting Pixels (poisson): 100%|██████████| 13226/13226 [08:04<00:00, 27.28px/s]
import pandas as pd

import matplotlib.pyplot as plt

from pyfli.solver import BaseFLIFitter, FLICPUProcessor, GlobalFLIFitter, MLEFLIFitter

check_px = np.argwhere(b_bool_mask_well)
check_px = check_px[np.random.default_rng(SEED).choice(len(check_px), size=min(300, len(check_px)), replace=False)]
check_decay = _decay_well[check_px[:, 0], check_px[:, 1]][:, None, :]
check_irf = _irf_well[check_px[:, 0], check_px[:, 1]][:, None, :]
check_keys = (
    ["tau1_map", "tau2_map", "alpha1_map", "tau_mean_map"] if MODEL_TYPE == "bi-exponential" else ["tau_map"]
)
rows = []
for method in ["zero_pad", "circular"]:
    fitted = FLICPUProcessor(freq, MLEFLIFitter).process_image(
        check_decay,
        check_irf,
        mask=np.ones(check_decay.shape[:2], dtype=bool),
        model_type=MODEL_TYPE,
        estimator="poisson",
        n_jobs=7,
        shift_method=method,
    )["results"]["maps"]
    row = {"shift_method": method}
    for key in check_keys:
        rel = fitted[key][:, 0] / res_well[key][check_px[:, 0], check_px[:, 1]] - 1.0
        name = key.replace("_map", "")
        row[f"{name} bias (%)"] = 100 * np.median(rel)
        row[f"{name} spread (%)"] = 100 * (np.percentile(rel, 75) - np.percentile(rel, 25))
    rows.append(row)
fit_mask = np.zeros(b_bool_mask_well.shape, dtype=bool)
fit_mask[check_px[:, 0], check_px[:, 1]] = True
capped_fitter = GlobalFLIFitter(freq, BaseFLIFitter, MLEFLIFitter, processor_instance=FLICPUProcessor(freq, MLEFLIFitter))
capped_fitter.make_clusters(_decay_well, _irf_well, np.where(b_bool_mask_well, img_cluster_well, 0).astype(int))
capped_results, _, _ = capped_fitter.process_clusters(
    _decay_well,
    _irf_well,
    mask=fit_mask,
    model_type=MODEL_TYPE,
    estimator="poisson",
    global_inference=False,
    gi_tol={"tau2": 1.0},
    n_jobs=7,
    shift_method="circular",
)
plt.close("all")
capped = capped_fitter.stitch_results(capped_results, *_decay_well.shape, model_type=MODEL_TYPE)["results"]["maps"]
row = {"shift_method": "circular + tau2 cap (GlobalFLIFitter)"}
for key in check_keys:
    rel = capped[key][check_px[:, 0], check_px[:, 1]] / res_well[key][check_px[:, 0], check_px[:, 1]] - 1.0
    name = key.replace("_map", "")
    row[f"{name} bias (%)"] = 100 * np.median(rel)
    row[f"{name} spread (%)"] = 100 * (np.percentile(rel, 75) - np.percentile(rel, 25))
rows.append(row)
pd.DataFrame(rows).set_index("shift_method").round(2)
Fitting Pixels (poisson): 100%|██████████| 300/300 [00:07<00:00, 37.69px/s]
Fitting Pixels (poisson): 100%|██████████| 300/300 [00:09<00:00, 30.56px/s]
INFO:pyfli:
--- Fitting Super-Pixels (Strategy: snr_weighted) ---
Super-Pixel Progress:   0%|          | 0/2 [00:00<?, ?it/s]
┌──────────────────────────────────────────────────────────────┐
│  FLI Fitting Results  |  BI-EXPONENTIAL                      │
│  1 method queued                                             │
└──────────────────────────────────────────────────────────────┘


┌────────────────┬──────┬─────────┬─────────┬──────────┬──────────┬─────────┬──────────┬──────────┬─────────┬──────────┐
│ Method         │ Type │       A │       α │       τ₁ │       τ₂ │      R² │   Red.χ² │   Raw.χ² │ v-shift │  h-shift │
├────────────────┼──────┼─────────┼─────────┼──────────┼──────────┼─────────┼──────────┼──────────┼─────────┼──────────┤
│ POISSON        │ MLE  │ 13189.24 │  0.2425 │    0.307 │    1.708 │  0.9995 │   0.0206 │     5.43 │    0.27 │   -0.001 │
└────────────────┴──────┴─────────┴─────────┴──────────┴──────────┴─────────┴──────────┴──────────┴─────────┴──────────┘
../_images/13bb5bf7e26f5918d7ba8ceae352fadc05748bce9d3e40a98cb343a504dbd15e.png
Super-Pixel Progress:  50%|█████     | 1/2 [00:00<00:00,  1.30it/s]
┌──────────────────────────────────────────────────────────────┐
│  FLI Fitting Results  |  BI-EXPONENTIAL                      │
│  1 method queued                                             │
└──────────────────────────────────────────────────────────────┘


┌────────────────┬──────┬─────────┬─────────┬──────────┬──────────┬─────────┬──────────┬──────────┬─────────┬──────────┐
│ Method         │ Type │       A │       α │       τ₁ │       τ₂ │      R² │   Red.χ² │   Raw.χ² │ v-shift │  h-shift │
├────────────────┼──────┼─────────┼─────────┼──────────┼──────────┼─────────┼──────────┼──────────┼─────────┼──────────┤
│ POISSON        │ MLE  │ 13226.52 │  0.4804 │    0.388 │    0.852 │  1.0000 │   0.0006 │     0.14 │    0.09 │   -0.000 │
└────────────────┴──────┴─────────┴─────────┴──────────┴──────────┴─────────┴──────────┴──────────┴─────────┴──────────┘
../_images/ff1906044a73bcbb4865f6fbadc328f44694e0a76862d80053e8efd31faa63f8.png
Super-Pixel Progress: 100%|██████████| 2/2 [00:01<00:00,  1.03it/s]
INFO:pyfli:
═════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
CONSOLIDATED CLUSTER BENCHMARK
═════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
INFO:pyfli:╒═══════════╤══════════╤════════╤════════╤═══════════╤════════╤════════╤═════════════╤════════════════════════════════════════════╕
│  Cluster  │  Method  │  Type  │  Conv  │   Time    │   R2   │  Chi2  │  Red. Chi2  │                 Parameters                 │
╞═══════════╪══════════╪════════╪════════╪═══════════╪════════╪════════╪═════════════╪════════════════════════════════════════════╡
│ cluster_1 │ POISSON  │  MLE   │  YES   │ 187.81 ms │ 0.9995 │  5.43  │   0.0206    │ A:13189.2, α:0.24, τ1:0.31, τ2:1.71, B:0.3 │
├───────────┼──────────┼────────┼────────┼───────────┼────────┼────────┼─────────────┼────────────────────────────────────────────┤
│ cluster_2 │ POISSON  │  MLE   │  YES   │ 191.49 ms │   1    │  0.14  │   0.0006    │ A:13226.5, α:0.48, τ1:0.39, τ2:0.85, B:0.1 │
╘═══════════╧══════════╧════════╧════════╧═══════════╧════════╧════════╧═════════════╧════════════════════════════════════════════╛
Fitting Pixels (poisson): 100%|██████████| 164/164 [00:04<00:00, 38.30px/s]
Fitting Pixels (poisson): 100%|██████████| 136/136 [00:04<00:00, 31.59px/s]
tau1 bias (%) tau1 spread (%) tau2 bias (%) tau2 spread (%) alpha1 bias (%) alpha1 spread (%) tau_mean bias (%) tau_mean spread (%)
shift_method
zero_pad -6.98 16.049999 -5.49 8.55 -7.99 31.98 -1.94 2.73
circular -2.60 15.010000 -0.98 8.29 -1.79 21.32 -0.26 2.00
circular + tau2 cap (GlobalFLIFitter) -3.09 16.209999 -1.30 9.13 -2.98 24.48 -0.36 2.08

2.5. Comparing the results#

Every fit result has the same layout: results["results"]["maps"] holds the parameter maps (alpha1_map, tau1_map, tau2_map, tau_mean_map, R2_map, reduced_chi2_map, …), and results["results"]["TR_maps"] holds the per-pixel fitted curves (fit_map) and residuals (residual_map).

2.5.1. Parameter maps#

Rows: ground truth, NLSF, MLE. The lifetime color range is shared across rows and set from the ground truth.

experiments = {"NLSF": results_nlsf, "MLE": results_mle}
all_datasets = [res["results"]["maps"] for res in experiments.values()]
all_fitset = [res["results"]["TR_maps"] for res in experiments.values()]

keys_to_plot = ["tau1_map", "tau2_map", "tau_mean_map", "alpha1_map",]
sources = {"ground_truth": res_well, **dict(zip(experiments, all_datasets))}
tau_max = float(max(res_well["tau1_map"].max(), res_well["tau2_map"].max()))

_ = DataViewer().display_data(
    [maps[key] for maps in sources.values() for key in keys_to_plot],
    structure=(len(sources), len(keys_to_plot)),
    coord=None,
    data_names=[f"{key}_{name}" for name in sources for key in keys_to_plot],
    cmaps=[jet_m_well] * len(sources) * len(keys_to_plot),
    v_ranges=[(0, 1), (0, 2), (0, 2), (0, 1)] * len(sources),
    figsize=(20, 9),
    normalize=False,
    yscale="linear",
)
../_images/ac392796d3b4e4838b262c8d6c2f48c4edfa99015cf90980f4f0fbea9a78d00b.png

2.5.2. Parameter distributions#

Plotter compares the parameter values of the well pixels across the sources. The operations dict is applied to every source: it keeps only pixels inside the mask, drops failed fits (NaN or zero) and discards values outside the threshold range. A list of dicts, one per source, can be passed instead to filter each source differently.

names = ["Ground truth"] + list(experiments)
plotter_ops = {
    "mask": b_bool_mask_well.ravel(),
    "remove_nan": True,
    "remove_zero": True,
    "threshold": (0, 7),
}

painter = Plotter(
    res_well,
    *all_datasets,
    values=keys_to_plot,
    style_config=["#AAB7B8", "#5DADE2", "#EC7063"],
    source_names=names,
    operations=plotter_ops,
)

fig = painter.make_plot(
    title="Bi-exponential parameters: ground truth vs NLSF vs MLE",
    graph_type="violin",
    point_type="strip",
    show_mean=True,
    show_median=True,
    show_significance=True,
    test_type="none",
    correction=False,
)
../_images/00ecf95718164c8e772fb9e85588fb9aabaa050b28db84b85381e4e89f447f3e.png

graph_type can also be "box", "swarm", "overlay", "raincloud" or "kde". Setting test_type to "paired" or "welch" adds significance tests between the sources.

2.5.3. Fits at a single pixel#

plot_pixel_diagnostic overlays the NLSF and MLE fitted curves on the measured decay at one pixel, with the residuals below.

x_well, y_well = random_true_pixel(b_bool_mask_well)
_ = plot_pixel_diagnostic(
    _decay_well,
    all_fitset,
    list(experiments),
    mask=b_bool_mask_well,
    pixel=(x_well, y_well),
    t=None,
    yscale="log",
    raw_style="line",
    model_type=MODEL_TYPE,
)
../_images/d5f7920195c3d51a20813a3a6c3c07e2bb501273b80df17fbc55b66602378320.png

The same pixel is shown for each estimator, along with the fitted parameters and goodness-of-fit metrics (R², reduced χ²). The ground-truth values at this pixel are printed first for reference.

print(f"the non-zero pixel selected for probing is ({x_well}, {y_well})")
print("--- Ground truth ---")
_ = MessageDisplay().get_pixel_summary(data_maps=res_well, px=(x_well, y_well))
for name, maps, TRs in zip(experiments, all_datasets, all_fitset):
    print(f"--- {name} ---")
    DataViewer().plot_fli_px(
        data_list=[_decay_well, irf_norm_well, TRs["fit_map"], TRs["residual_map"]],
        pixel=(x_well, y_well),
        mode=[0, 1, 2],
        mode2=[0],
        names=["decay", "irf", "fit"],
    )
    _ = MessageDisplay().get_pixel_summary(data_maps=maps, px=(x_well, y_well))
INFO:pyfli:
  Pixel (53, 52)
  ─────────────────────
  A         13945.9824
  α         0.3646
  τ₁        0.7216
  τ₂        1.8709
  R²        —
  Red.χ²    —
  Raw.χ²    —
  Pearson   —
  v-shift   0.0800
  h-shift   0.0000
  ─────────────────────
the non-zero pixel selected for probing is (53, 52)
--- Ground truth ---
--- NLSF ---
../_images/78b185d5cddffb124e41b9f29affea7567199421e46131556a4c87a507dc51da.png
INFO:pyfli:
  Pixel (53, 52)
  ─────────────────────
  A         13919.8662
  α         0.4668
  τ₁        0.8037
  τ₂        1.9857
  R²        0.9946
  Red.χ²    0.9045
  Raw.χ²    237.4342
  Pearson   0.8931
  v-shift   0.2500
  h-shift   0.0043
  ─────────────────────
--- MLE ---
../_images/d84103b352c7f1858509f1649bac77ca3573335086534910fd971a330ba5e7d5.png
INFO:pyfli:
  Pixel (53, 52)
  ─────────────────────
  A         13917.8037
  α         0.4653
  τ₁        0.8025
  τ₂        1.9820
  R²        0.9946
  Red.χ²    0.9045
  Raw.χ²    237.4333
  Pearson   0.8927
  v-shift   0.2586
  h-shift   0.0044
  ─────────────────────

2.6. Phasor computation and visualization#

time_axis_ns_well = np.linspace(0, gate_delay * num_gates, _irf_well.shape[2], endpoint=False)
phasor_well = PhasorAnalyzer(
    frequency_hz=freq_hz, time_axis_ns=time_axis_ns_well, n_harmonics=3
)
G_well, S_well = phasor_well.create_phasor_gpu(_decay_well)
Gc_well, Sc_well = phasor_well.calibrate_pixelwise(G_well, S_well, _irf_well)
tau_map_ns_well = phasor_well.compute_lifetime(Gc_well[0], Sc_well[0])
im2_well = phasor_well.plot_overlay_subplots(
    _decay_well,
    Gc_well[0],
    Sc_well[0],
    mask=b_bool_mask_well,
    colormaps=["plasma", "jet", "turbo_r", ph_cols_],
    figsize=(13, 7),
    xlim=(0, 1.1),
    bg_color=bg_color,
    transpose=False,
    kdeplot=False,
)
../_images/8ebb82ce7835642cc8f8b96f12b7c280f5c77472cb5b8cbaadd22e82bcc7c851.png