flimkit 0.12.0__py3-none-any.whl

flimkit/UI/expert_settings.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk, messagebox
+
+from flimkit.UI.utils import _C
+from flimkit.UI.fit_help import help_button
+from typing import Optional
+
+_EXPERT_DEFAULTS = {
+    'binning_factor': 1,
+    'optimizer': 'de',
+    'lm_restarts': 8,
+    'de_population': 30,
+    'de_maxiter': 5000,
+    'n_workers': -1,
+    'cost_function': 'poisson',
+    'channels': '',
+    'min_photons': 10,
+    'irf_fwhm': None,
+    'irf_align': 'steepest_rise',
+    'irf_shift_bins': 2,
+    'free_tau_perpixel': False,
+    'align_irf': False,
+    'fit_start_ns': None,
+    'fit_end_ns': None,
+    'exclude_ns': '',
+    'fit_t0': False,
+}
+
+
+class ExpertSettingsDialog(tk.Toplevel):
+
+    def __init__(self, parent, current: dict):
+        super().__init__(parent)
+        self.title('Expert Fit Settings')
+        self.resizable(False, False)
+        self.transient(parent)
+        self.grab_set()
+
+        self.result: Optional[dict] = None
+        cfg = _C()
+
+        vals = dict(_EXPERT_DEFAULTS)
+        vals.update({
+            'binning_factor': cfg['binning_factor'],
+            'optimizer': cfg['Optimizer'],
+            'lm_restarts': cfg['lm_restarts'],
+            'de_population': cfg['de_population'],
+            'de_maxiter': cfg['de_maxiter'],
+            'n_workers': cfg['n_workers'],
+            'min_photons': cfg['MIN_PHOTONS_PERPIX'],
+        })
+        vals.update(current)
+
+        PAD = {'padx': 4, 'pady': 3}
+        row = 0
+        f = ttk.Frame(self, padding=12)
+        f.pack(fill='both', expand=True)
+
+        opt_label = ttk.Frame(f)
+        opt_label.grid(row=row, column=0, sticky='w', **PAD)
+        ttk.Label(opt_label, text='Optimizer:').pack(side='left')
+        help_button(opt_label, 'optimizer').pack(side='left', padx=(4, 0))
+        self._sv_optimizer = tk.StringVar(value=vals['optimizer'])
+        opt_frame = ttk.Frame(f)
+        opt_frame.grid(row=row, column=1, columnspan=3, sticky='w', **PAD)
+        ttk.Radiobutton(opt_frame, text='Differential Evolution (DE)',
+                        variable=self._sv_optimizer, value='de').pack(side='left', padx=(0, 8))
+        ttk.Radiobutton(opt_frame, text='Levenberg-Marquardt (LM)',
+                        variable=self._sv_optimizer, value='lm_multistart').pack(side='left')
+
+        row += 1
+        ttk.Label(f, text='DE population:').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_de_pop = tk.StringVar(value=str(vals['de_population']))
+        ttk.Entry(f, textvariable=self._sv_de_pop, width=8).grid(row=row, column=1, sticky='w', **PAD)
+        ttk.Label(f, text='DE max iterations:').grid(row=row, column=2, sticky='w', **PAD)
+        self._sv_de_maxiter = tk.StringVar(value=str(vals['de_maxiter']))
+        ttk.Entry(f, textvariable=self._sv_de_maxiter, width=8).grid(row=row, column=3, sticky='w', **PAD)
+
+        row += 1
+        ttk.Label(f, text='LM random restarts:').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_lm_restarts = tk.StringVar(value=str(vals['lm_restarts']))
+        ttk.Entry(f, textvariable=self._sv_lm_restarts, width=8).grid(row=row, column=1, sticky='w', **PAD)
+
+        row += 1
+        ttk.Label(f, text='Spatial binning (NxN):').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_binning = tk.StringVar(value=str(vals['binning_factor']))
+        ttk.Entry(f, textvariable=self._sv_binning, width=8).grid(row=row, column=1, sticky='w', **PAD)
+        ttk.Label(f, text='(1 = no binning)', foreground='grey').grid(row=row, column=2, columnspan=2, sticky='w', **PAD)
+
+        row += 1
+        ttk.Label(f, text='CPU workers:').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_workers = tk.StringVar(value=str(vals['n_workers']))
+        ttk.Entry(f, textvariable=self._sv_workers, width=8).grid(row=row, column=1, sticky='w', **PAD)
+        ttk.Label(f, text='(-1 = all cores)', foreground='grey').grid(row=row, column=2, columnspan=2, sticky='w', **PAD)
+
+        row += 1
+        ttk.Label(f, text='Min photons/pixel:').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_min_ph = tk.StringVar(value=str(vals['min_photons']))
+        ttk.Entry(f, textvariable=self._sv_min_ph, width=8).grid(row=row, column=1, sticky='w', **PAD)
+
+        row += 1
+        ttk.Label(f, text='Cost function:').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_cost = tk.StringVar(value=vals['cost_function'])
+        cf_frame = ttk.Frame(f)
+        cf_frame.grid(row=row, column=1, columnspan=3, sticky='w', **PAD)
+        ttk.Radiobutton(cf_frame, text='Poisson deviance',
+                        variable=self._sv_cost, value='poisson').pack(side='left', padx=(0, 8))
+        ttk.Radiobutton(cf_frame, text='Chi² (legacy)',
+                        variable=self._sv_cost, value='chi2').pack(side='left')
+
+        row += 1
+        ttk.Label(f, text='Channel filter:').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_channels = tk.StringVar(value=str(vals.get('channels', '') or ''))
+        ttk.Entry(f, textvariable=self._sv_channels, width=12).grid(row=row, column=1, sticky='w', **PAD)
+        ttk.Label(f, text='(blank = all channels)', foreground='grey').grid(row=row, column=2, columnspan=2, sticky='w', **PAD)
+
+        row += 1
+        ttk.Label(f, text='IRF FWHM (ns):').grid(row=row, column=0, sticky='w', **PAD)
+        _irf_fwhm_val = vals.get('irf_fwhm')
+        self._sv_irf_fwhm = tk.StringVar(value='' if _irf_fwhm_val is None else str(_irf_fwhm_val))
+        ttk.Entry(f, textvariable=self._sv_irf_fwhm, width=12).grid(row=row, column=1, sticky='w', **PAD)
+        ttk.Label(f, text='(blank = 1 bin auto, e.g. 0.097)', foreground='grey').grid(row=row, column=2, columnspan=2, sticky='w', **PAD)
+
+        row += 1
+        ttk.Label(f, text='IRF alignment:').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_irf_align = tk.StringVar(value=vals.get('irf_align', 'steepest_rise'))
+        align_frame = ttk.Frame(f)
+        align_frame.grid(row=row, column=1, columnspan=3, sticky='w', **PAD)
+        ttk.Radiobutton(align_frame, text='Steepest rise (recommended)',
+                        variable=self._sv_irf_align, value='steepest_rise').pack(side='left', padx=(0, 8))
+        ttk.Radiobutton(align_frame, text='Decay peak (legacy)',
+                        variable=self._sv_irf_align, value='decay_peak').pack(side='left')
+
+        row += 1
+        ttk.Label(f, text='IRF shift bound (±bins):').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_irf_shift = tk.StringVar(value=str(vals.get('irf_shift_bins', 2)))
+        ttk.Entry(f, textvariable=self._sv_irf_shift, width=8).grid(row=row, column=1, sticky='w', **PAD)
+        ttk.Label(f, text='(2 = recommended; 5 = legacy)', foreground='grey').grid(row=row, column=2, columnspan=2, sticky='w', **PAD)
+
+        row += 1
+        self._bv_align_irf = tk.BooleanVar(value=bool(vals.get('align_irf', False)))
+        ttk.Checkbutton(f, text='Align measured IRF peak to the decay rising edge  '
+                                '(for a scatter PTU or .pck from a separate acquisition)',
+                        variable=self._bv_align_irf).grid(
+            row=row, column=0, columnspan=4, sticky='w', **PAD)
+
+        row += 1
+        _start_val = vals.get('fit_start_ns')
+        _end_val = vals.get('fit_end_ns')
+        ttk.Label(f, text='Fit window start (ns):').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_fit_start = tk.StringVar(value='' if _start_val is None else str(_start_val))
+        ttk.Entry(f, textvariable=self._sv_fit_start, width=8).grid(row=row, column=1, sticky='w', **PAD)
+        ttk.Label(f, text='Fit window end (ns):').grid(row=row, column=2, sticky='w', **PAD)
+        self._sv_fit_end = tk.StringVar(value='' if _end_val is None else str(_end_val))
+        ttk.Entry(f, textvariable=self._sv_fit_end, width=8).grid(row=row, column=3, sticky='w', **PAD)
+
+        row += 1
+        ttk.Label(f, text='Exclude bands (ns):').grid(row=row, column=0, sticky='w', **PAD)
+        self._sv_exclude = tk.StringVar(value=str(vals.get('exclude_ns', '') or ''))
+        ttk.Entry(f, textvariable=self._sv_exclude, width=20).grid(row=row, column=1, sticky='w', **PAD)
+        ttk.Label(f, text='(blank = none, e.g. 7.2-8.8 or 7.2-8.8,11.0-11.5)',
+                  foreground='grey').grid(row=row, column=2, columnspan=2, sticky='w', **PAD)
+
+        row += 1
+        self._bv_free_tau = tk.BooleanVar(value=bool(vals.get('free_tau_perpixel', False)))
+        ttk.Checkbutton(f, text='Free τ per pixel  (slower - reveals τ spatial variation for n_exp > 1)',
+                        variable=self._bv_free_tau).grid(
+            row=row, column=0, columnspan=4, sticky='w', **PAD)
+
+        row += 1
+        self._bv_fit_t0 = tk.BooleanVar(value=bool(vals.get('fit_t0', False)))
+        ttk.Checkbutton(f, text='Free t0  (tail fit only - correlated with the amplitudes, leave off unless they matter)',
+                        variable=self._bv_fit_t0).grid(
+            row=row, column=0, columnspan=4, sticky='w', **PAD)
+
+        row += 1
+        btn_frame = ttk.Frame(f)
+        btn_frame.grid(row=row, column=0, columnspan=4, pady=(12, 0))
+        ttk.Button(btn_frame, text='Confirm', command=self._confirm).pack(side='left', padx=4)
+        ttk.Button(btn_frame, text='Reset Defaults', command=self._reset).pack(side='left', padx=4)
+        ttk.Button(btn_frame, text='Cancel', command=self.destroy).pack(side='left', padx=4)
+
+        self.protocol('WM_DELETE_WINDOW', self.destroy)
+        self.update_idletasks()
+        pw, ph = parent.winfo_width(), parent.winfo_height()
+        px, py = parent.winfo_rootx(), parent.winfo_rooty()
+        w, h = self.winfo_width(), self.winfo_height()
+        self.geometry(f"+{px + (pw - w) // 2}+{py + (ph - h) // 2}")
+
+    def _collect(self) -> dict:
+        from flimkit.interactive import parse_exclude_ns
+        ch = self._sv_channels.get().strip()
+        _fwhm_s = self._sv_irf_fwhm.get().strip()
+        _start_s = self._sv_fit_start.get().strip()
+        _end_s = self._sv_fit_end.get().strip()
+        _excl_s = self._sv_exclude.get().strip()
+        parse_exclude_ns(_excl_s or None)
+        return {
+            'optimizer': self._sv_optimizer.get(),
+            'de_population': int(self._sv_de_pop.get() or 30),
+            'de_maxiter': int(self._sv_de_maxiter.get() or 5000),
+            'lm_restarts': int(self._sv_lm_restarts.get() or 8),
+            'binning_factor': int(self._sv_binning.get() or 1),
+            'n_workers': int(self._sv_workers.get() or -1),
+            'min_photons': int(self._sv_min_ph.get() or 10),
+            'cost_function': self._sv_cost.get(),
+            'channels': int(ch) if ch.isdigit() else (None if ch == '' else ch),
+            'irf_fwhm': float(_fwhm_s) if _fwhm_s else None,
+            'irf_align': self._sv_irf_align.get(),
+            'irf_shift_bins': int(self._sv_irf_shift.get() or 2),
+            'align_irf': self._bv_align_irf.get(),
+            'free_tau_perpixel': self._bv_free_tau.get(),
+            'fit_t0': self._bv_fit_t0.get(),
+            'fit_start_ns': float(_start_s) if _start_s else None,
+            'fit_end_ns': float(_end_s) if _end_s else None,
+            'exclude_ns': _excl_s,
+        }
+
+    def _confirm(self):
+        try:
+            self.result = self._collect()
+        except ValueError as e:
+            messagebox.showerror('Invalid value', str(e), parent=self)
+            return
+        self.destroy()
+
+    def _reset(self):
+        d = _EXPERT_DEFAULTS
+        self._sv_optimizer.set(d['optimizer'])
+        self._sv_de_pop.set(str(d['de_population']))
+        self._sv_de_maxiter.set(str(d['de_maxiter']))
+        self._sv_lm_restarts.set(str(d['lm_restarts']))
+        self._sv_binning.set(str(d['binning_factor']))
+        self._sv_workers.set(str(d['n_workers']))
+        self._sv_min_ph.set(str(d['min_photons']))
+        self._sv_cost.set(d['cost_function'])
+        self._sv_channels.set('')
+        self._sv_irf_fwhm.set('')
+        self._sv_irf_align.set('steepest_rise')
+        self._sv_irf_shift.set('2')
+        self._bv_align_irf.set(False)
+        self._bv_free_tau.set(False)
+        self._bv_fit_t0.set(False)
+        self._sv_fit_start.set('')
+        self._sv_fit_end.set('')
+        self._sv_exclude.set('')

flimkit/UI/fit_help.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk
+from tkinter import font as tkfont
+
+TOPIC_ORDER = ('fit_model', 'components', 'fitting_mode', 'optimizer',
+               'irf', 'masking')
+
+FIT_HELP = {
+    'fit_model': ('Fit model', [
+        ('n-exp',
+         'A sum of N discrete exponentials, convolved with the IRF before it is '
+         'compared to the data. This is the default and the right choice for most '
+         'samples. It assumes every molecule in a pixel sits in one of N '
+         'well-defined states, each with a single lifetime.'),
+        ('Gaussian dist.',
+         'One continuous distribution of lifetimes instead of a discrete set. The '
+         'fit returns a centre and a width rather than a list of taus. Use it when '
+         'the fluorophore sits in a heterogeneous environment and a discrete fit '
+         'needs an implausible number of components to converge.'),
+        ('Lorentzian dist.',
+         'The same idea with a Lorentzian shape, which has heavier tails than a '
+         'Gaussian. It tolerates a small sub-population well away from the centre '
+         'without dragging the centre towards it.'),
+        ('n-exp tail',
+         'Fits discrete exponentials past the peak of the decay and uses no IRF at '
+         'all. Fast, and it removes the IRF as a source of error, but it cannot '
+         'recover components shorter than roughly the IRF width, so short taus come '
+         'out biased. The IRF panel disappears when this is selected.'),
+    ], 'Distribution fits are slower than discrete ones: each evaluation integrates '
+       'over a 200-point lifetime grid.'),
+
+    'components': ('Components', [
+        ('n-exp models (1, 2, 3)',
+         'How many discrete exponentials to fit. Start at 1 and add a component '
+         'only if the residuals show structure. Each extra component adds two free '
+         'parameters, and three components need a lot of photons before the taus '
+         'are separable.'),
+        ('Distribution models (unimodal, bimodal)',
+         'How many distributions to sum. Unimodal is one centre and one width. '
+         'Bimodal fits two, for a sample with two distinct populations that are '
+         'each internally heterogeneous.'),
+    ], 'A lower chi-squared alone does not justify an extra component. More '
+       'parameters will always fit better. Check whether the recovered taus are '
+       'physically distinct and whether the residuals actually improved.'),
+
+    'fitting_mode': ('Fitting mode', [
+        ('Full',
+         'Fits the summed decay for the whole field of view and then fits every '
+         'pixel individually. This is what produces the FLIM image and the lifetime '
+         'maps.'),
+        ('Fast',
+         'Fits the summed decay only. No per-pixel fitting, so no FLIM image and no '
+         'lifetime maps, but it finishes in seconds rather than minutes. Use it to '
+         'check that the IRF, the model and the component count are sensible before '
+         'committing to a full run.'),
+    ], 'Per-pixel fitting is the expensive step. Binning and the minimum '
+       'photons-per-pixel threshold both live in Expert Fit Settings.'),
+
+    'optimizer': ('Optimizer', [
+        ('Differential Evolution (DE)',
+         'A global search over the whole bounded parameter space, so it does not '
+         'depend on a starting guess and will not settle into a local minimum near '
+         'one. Slower than LM. Lifetimes are searched in log space, the population '
+         'is Sobol-initialised, and a Levenberg-Marquardt polish is run at the end '
+         'to sharpen the result.'),
+        ('Levenberg-Marquardt (LM)',
+         'A local gradient-based fit, run from several starting points and the best '
+         'result kept. The first start is log-spaced across the lifetime bounds and '
+         'the rest are random. Much faster than DE, but with few restarts it can '
+         'still miss the global minimum on a multi-exponential decay.'),
+    ], 'Both are seeded, so repeating a fit on the same data gives the same answer. '
+       'DE population, DE iterations and LM restart count are all set in Expert Fit '
+       'Settings.'),
+
+    'irf': ('Instrument Response Function (IRF)', [
+        ('Analytical model (LAS X export)',
+         'Builds the IRF from the LAS X export named in Input Files. This is the '
+         'default for Leica FALCON data, where the microscope has already '
+         'characterised its own response.'),
+        ('Machine IRF (.npy pre-built)',
+         'A prompt measured once for the instrument and saved to disk, reused for '
+         'every dataset from that microscope. Build one with the IRF tab. Use this '
+         'when the optical path has not changed since it was measured.'),
+        ('Machine IRF + full sigma broadening',
+         'The same stored prompt, but the fit is allowed to broaden it with a '
+         'Gaussian of up to 3.0 bins. Use it when the stored IRF is narrower than '
+         'the real response, for example after a change of objective or pinhole.'),
+        ('Machine IRF + half sigma broadening',
+         'Broadening capped at 0.5 bins. A tighter leash for when the stored IRF is '
+         'close to right and a free sigma would start absorbing the decay itself.'),
+        ('Measured IRF file (scatter PTU or .pck)',
+         'A prompt measured alongside this dataset, usually a scattering solution '
+         'or a reflecting surface. The most defensible option when you have one: it '
+         'carries the same optical path, detector and timing as the sample.'),
+        ('Estimate from decay - raw',
+         'Takes 21 bins centred on the peak of the decay itself and uses them as '
+         'the prompt, after subtracting a background estimated from the pre-peak '
+         'bins. A last resort. It cannot separate the instrument response from the '
+         'fastest part of the decay, so short lifetimes come out too long.'),
+        ('Estimate from decay - parametric',
+         'Fits an analytical pulse shape, amplitude times t/t0 times exp(-t/t0), to '
+         'a 1.5 ns window around the peak. Smoother and less noisy than raw '
+         'extraction, but it inherits the same problem and falls back to raw '
+         'extraction if the fit fails.'),
+        ('Gaussian (fallback)',
+         'A plain Gaussian prompt of the configured width. For when nothing better '
+         'is available and you need a number rather than an answer.'),
+    ], 'The IRF is the largest single source of systematic error in a reconvolution '
+       'fit, and it matters most for the shortest component. If tau_1 comes out '
+       'near the IRF width, treat it as unresolved rather than measured. Picking '
+       'the n-exp tail model removes the IRF from the fit entirely.'),
+
+    'masking': ('Masking & Thresholding', [
+        ('Apply cell mask (Cellpose-SAM)',
+         'Segments cells in the intensity image and fits only inside them. Removes '
+         'background pixels that would otherwise contribute noise-dominated '
+         'lifetimes to the summary statistics.'),
+        ('Intensity threshold (min photons/px)',
+         'Skips any pixel with fewer than this many photons. A per-pixel fit on a '
+         'few dozen photons is dominated by shot noise, so the resulting lifetime '
+         'is close to meaningless and will smear the histogram. Leave blank for no '
+         'threshold.'),
+        ('Coates pile-up correction',
+         'At high count rates the detector preferentially records early photons, '
+         'which biases lifetimes short. The Coates correction inverts that '
+         'distortion on the measured decay. The count rate and photons-per-pulse '
+         'are printed at the start of every fit, and the checkbox is worth ticking '
+         'above about 5 percent.'),
+        ('Time-varying background PTU',
+         'A separately measured background acquisition. Its decay shape is fitted '
+         'as an extra component with a free scale, so a background that is itself '
+         'time-varying, such as detector afterpulsing or room light, is subtracted '
+         'in shape rather than as a flat offset.'),
+    ], 'The Coates correction rescales the counts, so the corrected decay is no '
+       'longer Poisson-distributed while the default cost function still assumes it '
+       'is. The reported chi-squared is unreliable when the correction is on, even '
+       'though the recovered lifetimes are not.'),
+}
+
+
+class FitHelpWindow(tk.Toplevel):
+
+    def __init__(self, parent, topic=None):
+        super().__init__(parent)
+        self.title('Choosing your fit settings')
+        self.transient(parent)
+        self.geometry('620x520')
+        self.minsize(420, 300)
+        frame = ttk.Frame(self, padding=(12, 10))
+        frame.pack(fill='both', expand=True)
+        self._text = tk.Text(frame, wrap='word', relief='flat', padx=8, pady=6,
+                             borderwidth=0, highlightthickness=0)
+        bar = ttk.Scrollbar(frame, orient='vertical', command=self._text.yview)
+        self._text.configure(yscrollcommand=bar.set)
+        self._text.pack(side='left', fill='both', expand=True)
+        bar.pack(side='right', fill='y')
+        self._configure_tags()
+        self._marks = {}
+        self._fill()
+        self._text.configure(state='disabled')
+        ttk.Button(self, text='Close', command=self.destroy).pack(pady=(0, 10))
+        self.bind('<Escape>', lambda _e: self.destroy())
+        if topic in self._marks:
+            self.after(50, lambda: self._text.see(self._marks[topic]))
+
+    def _configure_tags(self):
+        base = tkfont.nametofont('TkDefaultFont')
+        size = base.cget('size')
+        family = base.cget('family')
+        self._text.tag_configure('h1', font=(family, abs(size) + 3, 'bold'),
+                                 spacing1=14, spacing3=6)
+        self._text.tag_configure('h2', font=(family, abs(size), 'bold'),
+                                 spacing1=8, spacing3=2, lmargin1=8, lmargin2=8)
+        self._text.tag_configure('body', spacing3=4, lmargin1=8, lmargin2=8)
+        self._text.tag_configure('note', foreground='#777', spacing1=6, spacing3=8,
+                                 lmargin1=8, lmargin2=8)
+
+    def _fill(self):
+        for key in TOPIC_ORDER:
+            title, entries, note = FIT_HELP[key]
+            self._marks[key] = f'mark_{key}'
+            self._text.mark_set(self._marks[key], 'end-1c')
+            self._text.mark_gravity(self._marks[key], 'left')
+            self._text.insert('end', title + '\n', 'h1')
+            for name, body in entries:
+                self._text.insert('end', name + '\n', 'h2')
+                self._text.insert('end', body + '\n', 'body')
+            self._text.insert('end', note + '\n', 'note')
+
+
+def show_fit_help(parent, topic=None):
+    win = FitHelpWindow(parent, topic=topic)
+    win.focus_set()
+    return win
+
+
+def help_button(parent, topic):
+    btn = ttk.Label(parent, text='ⓘ', foreground='#4a7ebb', cursor='hand2',
+                    takefocus=True)
+    def _open(_evt=None):
+        show_fit_help(parent.winfo_toplevel(), topic)
+    for seq in ('<Button-1>', '<Return>', '<space>'):
+        btn.bind(seq, _open)
+    return btn