flimkit 0.12.0__py3-none-any.whl

flimkit/phasor/peaks.py

@@ -0,0 +1,186 @@
+import numpy as np
+import matplotlib.pyplot as plt
+from scipy.ndimage import gaussian_filter, label, maximum_filter, center_of_mass
+
+from phasorpy.phasor import phasor_to_polar
+from phasorpy.lifetime import phasor_to_apparent_lifetime
+from phasorpy.plot import PhasorPlot
+
+
+def find_phasor_peaks(
+    real_cal,
+    imag_cal,
+    mean,
+    frequency,
+    *,
+    min_photons=0.01,
+    n_bins=256,
+    sigma=3.0,
+    neighbourhood=15,
+    threshold_frac=0.10,
+):
+    rc = np.asarray(real_cal).squeeze().astype(float)
+    ic = np.asarray(imag_cal).squeeze().astype(float)
+    mn = np.asarray(mean).squeeze().astype(float)
+    valid = (mn >= min_photons) & ~np.isnan(rc)
+
+    g_vals = rc[valid]
+    s_vals = ic[valid]
+
+    # 2-D histogram
+    hist, g_edges, s_edges = np.histogram2d(
+        g_vals, s_vals, bins=n_bins,
+        range=[[0, 1], [0, 0.55]])
+    g_centers = 0.5 * (g_edges[:-1] + g_edges[1:])
+    s_centers = 0.5 * (s_edges[:-1] + s_edges[1:])
+
+    # Smooth + local-maximum detection
+    hist_smooth = gaussian_filter(hist, sigma=sigma)
+    local_max = maximum_filter(hist_smooth, size=neighbourhood)
+    threshold = threshold_frac * hist_smooth.max()
+    peak_mask = (hist_smooth == local_max) & (hist_smooth > threshold)
+
+    labelled, n_peaks = label(peak_mask)
+
+    # Weighted centroids → phasor coordinates
+    peak_coords = center_of_mass(hist_smooth, labelled,
+                                 range(1, n_peaks + 1))
+    peak_g = np.empty(n_peaks)
+    peak_s = np.empty(n_peaks)
+    for i, (ig, is_) in enumerate(peak_coords):
+        peak_g[i] = np.interp(ig, np.arange(n_bins), g_centers)
+        peak_s[i] = np.interp(is_, np.arange(n_bins), s_centers)
+
+    # Lifetimes & polar coordinates
+    tau_phase, tau_mod = phasor_to_apparent_lifetime(
+        peak_g, peak_s, frequency)
+    phase_vals, mod_vals = phasor_to_polar(peak_g, peak_s)
+
+    # On-semicircle test (distance from centre (0.5, 0) with r = 0.5)
+    r = np.sqrt((peak_g - 0.5) ** 2 + peak_s ** 2)
+    on_semicircle = np.abs(r - 0.5) < 0.02
+
+    return dict(
+        n_peaks=n_peaks,
+        peak_g=peak_g,
+        peak_s=peak_s,
+        tau_phase=tau_phase,
+        tau_mod=tau_mod,
+        phase=phase_vals,
+        modulation=mod_vals,
+        on_semicircle=on_semicircle,
+        hist=hist,
+        hist_smooth=hist_smooth,
+        g_centers=g_centers,
+        s_centers=s_centers,
+    )
+
+
+def print_peaks(peaks: dict) -> None:
+    n = peaks['n_peaks']
+    print(f"Found {n} peak(s) in the phasor histogram\n")
+    print(f"{'Peak':>4}  {'G':>7}  {'S':>7}  {'τ_φ (ns)':>9}  "
+          f"{'τ_m (ns)':>9}  {'phase(°)':>9}  {'mod':>6}")
+    print('-' * 68)
+    for i in range(n):
+        print(f"{i+1:4d}  {peaks['peak_g'][i]:7.4f}  "
+              f"{peaks['peak_s'][i]:7.4f}  "
+              f"{peaks['tau_phase'][i]:9.3f}  "
+              f"{peaks['tau_mod'][i]:9.3f}  "
+              f"{np.degrees(peaks['phase'][i]):9.2f}  "
+              f"{peaks['modulation'][i]:6.4f}")
+    print()
+    for i in range(n):
+        if peaks['on_semicircle'][i]:
+            print(f"Peak {i+1}: ON semicircle → single-exponential, "
+                  f"τ ≈ {peaks['tau_phase'][i]:.2f} ns")
+        else:
+            r = abs(np.sqrt((peaks['peak_g'][i] - 0.5)**2 +
+                            peaks['peak_s'][i]**2) - 0.5)
+            print(f"Peak {i+1}: INSIDE semicircle (dist={r:.3f}) → "
+                  f"multi-exponential mixture")
+            print(f"          τ_φ = {peaks['tau_phase'][i]:.2f} ns,  "
+                  f"τ_m = {peaks['tau_mod'][i]:.2f} ns")
+
+
+def plot_phasor_peaks(
+    peaks: dict,
+    real_cal: np.ndarray,
+    imag_cal: np.ndarray,
+    mean: np.ndarray,
+    frequency: float,
+    *,
+    min_photons: float = 0.01,
+    figsize: tuple[float, float] = (13, 5.5),
+    ax_phasor=None,
+) -> plt.Figure | None:
+    n = peaks['n_peaks']
+    pg, ps = peaks['peak_g'], peaks['peak_s']
+    tp = peaks['tau_phase']
+
+    # Annotate an existing axes (e.g. the interactive phasor)
+    if ax_phasor is not None:
+        _annotate_peaks(ax_phasor, n, pg, ps, tp)
+        ax_phasor.figure.canvas.draw_idle()
+        return None
+ 
+    # Full standalone figure
+    rc = np.asarray(real_cal).squeeze().astype(float)
+    ic = np.asarray(imag_cal).squeeze().astype(float)
+    mn = np.asarray(mean).squeeze().astype(float)
+    valid = (mn >= min_photons) & ~np.isnan(rc)
+    g_vals, s_vals = rc[valid], ic[valid]
+
+    fig, axes = plt.subplots(1, 2, figsize=figsize)
+
+    # Left - PhasorPlot hist2d with markers
+    ax = axes[0]
+    pp = PhasorPlot(frequency=frequency, ax=ax,
+                    title='Phasor histogram - peak detection')
+    pp.hist2d(g_vals, s_vals)
+    _annotate_peaks(ax, n, pg, ps, tp)
+
+    # Right - smoothed contour + peaks
+    ax2 = axes[1]
+    GG, SS = np.meshgrid(peaks['g_centers'], peaks['s_centers'])
+    ax2.contourf(GG, SS, peaks['hist_smooth'].T, levels=30, cmap='Blues')
+    ax2.contour(GG, SS, peaks['hist_smooth'].T, levels=10,
+                colors='grey', linewidths=0.5)
+    for i in range(n):
+        ax2.plot(pg[i], ps[i], 'r*', ms=18,
+                 markeredgecolor='k', markeredgewidth=0.8, zorder=20)
+        ax2.annotate(
+            f'Peak {i+1}\nτ_φ={tp[i]:.2f} ns\nτ_m={peaks['tau_mod'][i]:.2f} ns',
+            xy=(pg[i], ps[i]), xytext=(12, 12),
+            textcoords='offset points', fontsize=8, color='red',
+            fontweight='bold',
+            bbox=dict(boxstyle='round,pad=0.3', fc='white', alpha=0.8),
+            arrowprops=dict(arrowstyle='->', color='red', lw=1.2))
+    theta = np.linspace(0, np.pi, 200)
+    ax2.plot(0.5 + 0.5 * np.cos(theta), 0.5 * np.sin(theta),
+             'k-', lw=1, alpha=0.5)
+    ax2.set_xlabel('G (real)')
+    ax2.set_ylabel('S (imag)')
+    ax2.set_title('Smoothed contour + peaks')
+    ax2.set_xlim(0, 1.05)
+    ax2.set_ylim(-0.02, 0.55)
+    ax2.set_aspect('equal')
+
+    fig.tight_layout()
+    return fig
+
+
+def _annotate_peaks(ax, n, pg, ps, tp):
+    artists = []
+    for i in range(n):
+        (star,) = ax.plot(pg[i], ps[i], 'r*', ms=18,
+                          markeredgecolor='k', markeredgewidth=0.8,
+                          zorder=20)
+        ann = ax.annotate(
+            f'τ_φ={tp[i]:.2f} ns',
+            xy=(pg[i], ps[i]), xytext=(10, 10),
+            textcoords='offset points', fontsize=9, color='red',
+            fontweight='bold',
+            arrowprops=dict(arrowstyle='->', color='red', lw=1.2))
+        artists.extend([star, ann])
+    return artists

flimkit/phasor/signal.py

@@ -0,0 +1,90 @@
+import numpy as np
+import pandas as pd
+from phasorpy.plot import plot_phasor
+from ..formats.PTU.tools import signal_from_PTUFile
+from phasorpy.phasor import phasor_from_signal
+from phasorpy.phasor import phasor_to_polar, phasor_transform
+
+def return_phasor_from_PTUFile(ptu_file):
+    signal = signal_from_PTUFile(ptu_file, dtype=np.uint32, binning=4)
+    mean, real, imag = phasor_from_signal(signal, axis='H')
+    return mean, real, imag
+
+def process_ifli(ifli_path, phasor_filter=None, filter_kwargs=None, channel=None):
+    from ..formats import FLIMFile
+    print(f"Loading frequency-domain file: {ifli_path}")
+    iss = FLIMFile(str(ifli_path), verbose=True, channel=channel)
+    mean, real, imag, frequency = iss.phasor(channel=channel)
+    print(f"  FD-FLIM phasor coordinates (frequency = {frequency:.2f} MHz)")
+    real_cal, imag_cal = real, imag
+    if phasor_filter:
+        from .filters import phasor_filter as _filter_fn
+        real_cal, imag_cal = _filter_fn(
+            np.asarray(real_cal, dtype=float),
+            np.asarray(imag_cal, dtype=float),
+            phasor_filter,
+            mean=np.asarray(mean, dtype=float),
+            **(filter_kwargs or {}),
+        )
+    return dict(
+        real_cal=np.asarray(real_cal),
+        imag_cal=np.asarray(imag_cal),
+        mean=np.asarray(mean),
+        frequency=float(frequency),
+        channel=channel,
+        display_image=np.asarray(mean, dtype=float),
+    )
+
+def get_phasor_irf(irf_xlsx):
+    df = pd.read_excel(irf_xlsx, sheet_name='Fit', header=None)
+    irf_time_ns = pd.to_numeric(df.iloc[2:, 2], errors='coerce').dropna().values
+    irf_counts = pd.to_numeric(df.iloc[2:, 3], errors='coerce').dropna().values
+    return irf_time_ns, irf_counts
+
+def calibrate_signal_with_irf(signal, real, imag, irf_time_ns, irf_counts, frequency):
+    signal_time_ns = signal.coords['H'].values
+    irf_on_signal = np.interp(signal_time_ns, irf_time_ns, irf_counts, left=0, right=0)
+
+    mean_irf, real_irf, imag_irf = phasor_from_signal(
+        irf_on_signal[np.newaxis, :], axis=-1
+    )
+    phase_irf, mod_irf = phasor_to_polar(real_irf.ravel(), imag_irf.ravel())
+    real_cal, imag_cal = phasor_transform(real, imag, -phase_irf[0], 1.0 / mod_irf[0],)
+    return real_cal, imag_cal
+
+def plot_calibrated_phasor(real, imag, signal):
+    frequency = signal.attrs['frequency']
+    plot_phasor(
+        real,
+        imag,
+        frequency=frequency,
+        title='Calibrated, filtered phasor coordinates',
+    )
+
+def calibrate_signal_with_machine_irf(signal, real, imag, machine_irf_npy: str,
+                                       frequency: float):
+    import json
+    from pathlib import Path
+
+    npy_path = Path(machine_irf_npy)
+    meta_path = npy_path.with_name(npy_path.stem + '_meta.json')
+
+    irf_arr = np.load(str(npy_path))
+
+    if meta_path.exists():
+        with open(meta_path) as f:
+            meta = json.load(f)
+        tcspc_res_ns = meta.get('tcspc_res_ns', None)
+    else:
+        tcspc_res_ns = None
+
+    signal_time_ns = signal.coords['H'].values
+    n_irf = len(irf_arr)
+
+    if tcspc_res_ns is not None:
+        irf_time_ns = np.arange(n_irf) * tcspc_res_ns
+    else:
+        irf_time_ns = np.linspace(signal_time_ns[0], signal_time_ns[-1], n_irf)
+
+    return calibrate_signal_with_irf(signal, real, imag,
+                                     irf_time_ns, irf_arr, frequency)

flimkit/phasor_launcher.py

@@ -0,0 +1,314 @@
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+
+def _yes_no(question):
+    import inquirer
+    ans = inquirer.prompt([inquirer.List(
+        'yesno', message=question, choices=['Yes', 'No'])])
+    return ans['yesno'] == 'Yes'
+
+def _ask_path(message, *, optional=False):
+    import inquirer
+    hint = ' (leave blank to skip)' if optional else ''
+    ans = inquirer.prompt([
+        inquirer.Path('path',
+                      message=f'{message}{hint}',
+                      path_type=inquirer.Path.FILE,
+                      exists=not optional)])
+    val = (ans or {}).get('path', '').strip()
+    if not val:
+        return None
+    return val
+
+def _pick_save_file(title: str, default_name: str) -> str | None:
+    from .dialogs import ask_save_path
+    return ask_save_path(title, default_name, defaultextension='.npz',
+                         filetypes=[('NumPy archive', '*.npz'), ('All files', '*')])
+
+def save_session(path, *,
+                 real_cal,
+                 imag_cal,
+                 mean,
+                 frequency,
+                 cursors,
+                 params,
+                 ptu_file=None,
+                 irf_file=None,
+                 display_image=None):
+    n = len(cursors)
+    cursor_g = np.array([c['center_g'] for c in cursors], dtype=float) if n else np.array([], dtype=float)
+    cursor_s = np.array([c['center_s'] for c in cursors], dtype=float) if n else np.array([], dtype=float)
+    cursor_colors = np.array([c['color'] for c in cursors], dtype='U10') if n else np.array([], dtype='U10')
+    save_kw = dict(
+        real_cal=real_cal,
+        imag_cal=imag_cal,
+        mean=mean,
+        frequency=np.float64(frequency),
+        cursor_g=cursor_g,
+        cursor_s=cursor_s,
+        cursor_colors=cursor_colors,
+        param_radius=np.float64(params.get('radius', 0.05)),
+        param_radius_minor=np.float64(params.get('radius_minor', 0.03)),
+        param_angle_mode=np.array(params.get('angle_mode', 'semicircle')),
+        ptu_file=np.array(ptu_file or ''),
+        irf_file=np.array(irf_file or ''),
+    )
+    if display_image is not None:
+        save_kw['display_image'] = np.asarray(display_image)
+    np.savez_compressed(path, **save_kw)
+    print(f'Session saved → {path}  ({n} cursor(s))')
+
+def load_session(path):
+    d = np.load(path, allow_pickle=False)
+    cursors = []
+    g = d['cursor_g']
+    s = d['cursor_s']
+    colors = d['cursor_colors']
+    for i in range(len(g)):
+        cursors.append(dict(
+            center_g=float(g[i]),
+            center_s=float(s[i]),
+            color=str(colors[i]),
+        ))
+    params = dict(
+        radius=float(d['param_radius']),
+        radius_minor=float(d['param_radius_minor']),
+        angle_mode=str(d['param_angle_mode']),
+    )
+    return dict(
+        real_cal=d['real_cal'],
+        imag_cal=d['imag_cal'],
+        mean=d['mean'],
+        frequency=float(d['frequency']),
+        cursors=cursors,
+        params=params,
+        ptu_file=str(d['ptu_file']) or None,
+        irf_file=str(d['irf_file']) or None,
+        display_image=d['display_image'] if 'display_image' in d else None,
+    )
+
+def get_ptu_active_channels(ptu_path):
+    from flimkit.formats import FLIMFile
+    ptu = FLIMFile(str(ptu_path), verbose=False)
+    active = getattr(ptu, '_active', None)
+    if not active:
+        active = list(range(getattr(ptu, 'n_channels', 0) or 0))
+    return sorted(int(channel) for channel in active)
+
+def _prompt_ptu_channel(active_channels):
+    import inquirer
+    answer = inquirer.prompt([inquirer.List(
+        'channel',
+        message=(
+            f'Multiple channels detected: {active_channels}. '
+            'Which one should be used for phasor analysis?'
+        ),
+        choices=[f'Channel {channel}' for channel in active_channels],
+    )])
+    if not answer or 'channel' not in answer:
+        raise ValueError('No channel selected for phasor analysis')
+    return int(str(answer['channel']).split()[-1])
+
+def resolve_ptu_channel(
+    ptu_path,
+    channel=None,
+    *,
+    prompt_fn=None,
+):
+    active_channels = get_ptu_active_channels(ptu_path)
+    if not active_channels:
+        raise ValueError('No photon channels found in PTU file')
+    if channel is not None:
+        selected_channel = int(channel)
+        if selected_channel not in active_channels:
+            raise ValueError(
+                f'Channel {selected_channel} is not present in PTU file. '
+                f'Available channels: {active_channels}'
+            )
+        return selected_channel
+    if len(active_channels) == 1:
+        selected_channel = active_channels[0]
+        print(f'Auto-selected channel {selected_channel} (only channel available)')
+        return selected_channel
+    if prompt_fn is None:
+        prompt_fn = _prompt_ptu_channel
+    selected_channel = int(prompt_fn(active_channels))
+    if selected_channel not in active_channels:
+        raise ValueError(
+            f'Channel {selected_channel} is not present in PTU file. '
+            f'Available channels: {active_channels}'
+        )
+    return selected_channel
+
+def _process_ptu(ptu_path, irf_path=None, channel=None, phasor_filter=None,
+                 filter_kwargs=None):
+    from phasorpy.phasor import phasor_from_signal
+    from .formats.PTU.tools import signal_from_PTUFile
+    from flimkit.formats import FLIMFile
+    from .phasor.signal import get_phasor_irf, calibrate_signal_with_irf
+    print(f'Loading PTU file: {ptu_path}')
+    channel = resolve_ptu_channel(ptu_path, channel=channel)
+    print(f'Using channel: {channel}')
+    signal = signal_from_PTUFile(ptu_path, dtype=np.uint32, binning=4, channel=channel)
+    frequency = float(signal.attrs['frequency'])
+    print(f'Computing phasors (frequency = {frequency:.2f} MHz) ...')
+    mean, real, imag = phasor_from_signal(signal, axis='H')
+    ptu = FLIMFile(str(ptu_path), verbose=False)
+    if getattr(ptu, 'is_image', True):
+        display_image = ptu.raw_pixel_stack(channel=channel, binning=4).sum(axis=-1)
+    else:
+        print(' Point measurement: no image to reconstruct.')
+        display_image = None
+    if irf_path:
+        from .phasor.signal import calibrate_signal_with_machine_irf
+        irf_path_p = Path(irf_path)
+        if irf_path_p.suffix.lower() == '.npy':
+            print(f'Calibrating with machine IRF (.npy): {irf_path}')
+            real_cal, imag_cal = calibrate_signal_with_machine_irf(
+                signal, real, imag, irf_path, frequency)
+        else:
+            print(f'Calibrating with IRF (.xlsx): {irf_path}')
+            irf_time_ns, irf_counts = get_phasor_irf(irf_path)
+            real_cal, imag_cal = calibrate_signal_with_irf(
+                signal, real, imag, irf_time_ns, irf_counts, frequency)
+    else:
+        print(' No IRF - using uncalibrated phasor coordinates.')
+        real_cal, imag_cal = real, imag
+    if phasor_filter:
+        from .phasor.filters import phasor_filter as _filter_fn
+        print(f'Applying phasor filter: {phasor_filter} ...')
+        real_cal, imag_cal = _filter_fn(
+            np.asarray(real_cal, dtype=float),
+            np.asarray(imag_cal, dtype=float),
+            phasor_filter,
+            mean=np.asarray(mean, dtype=float),
+            **(filter_kwargs or {}),
+        )
+    return dict(
+        real_cal=np.asarray(real_cal),
+        imag_cal=np.asarray(imag_cal),
+        mean=np.asarray(mean),
+        frequency=frequency,
+        channel=channel,
+        display_image=(np.asarray(display_image, dtype=float)
+                       if display_image is not None else None),
+    )
+
+def launch_phasor(ptu_path=None,
+                  irf_path=None,
+                  machine_irf_path=None,
+                  session_path=None,
+                  *,
+                  channel=None,
+                  phasor_filter=None,
+                  filter_kwargs=None,
+                  min_photons=0.01,
+                  max_cursors=6,
+                  figsize=(8, 5)):
+    from .phasor.interactive import phasor_cursor_tool
+    from flimkit.formats import file_modality
+    initial_cursors = None
+    initial_params = None
+    src_ptu = ptu_path
+    src_irf = irf_path
+    if session_path is None and ptu_path is None:
+        import inquirer
+        mode = inquirer.prompt([inquirer.List(
+            'mode',
+            message='What would you like to do?',
+            choices=[
+                'Analyse a new PTU file',
+                'Resume a saved session (.npz)',
+            ],
+        )])['mode']
+        if mode.startswith('Resume'):
+            session_path = _ask_path('Path to saved .npz session')
+            if session_path is None:
+                print('No file specified - aborting.')
+                return {}
+        else:
+            ptu_path = _ask_path('Path to PTU file')
+            if ptu_path is None:
+                print('No file specified - aborting.')
+                return {}
+    if session_path:
+        print(f'Loading session: {session_path}')
+        sess = load_session(session_path)
+        data = dict(
+            real_cal=sess['real_cal'],
+            imag_cal=sess['imag_cal'],
+            mean=sess['mean'],
+            frequency=sess['frequency'],
+            display_image=sess.get('display_image'),
+        )
+        initial_cursors = sess['cursors'] or None
+        initial_params = sess['params']
+        src_ptu = sess.get('ptu_file')
+        src_irf = sess.get('irf_file')
+        print(f'  frequency = {data['frequency']:.2f} MHz, '
+              f'{len(sess['cursors'])} cursor(s) restored')
+    elif ptu_path and file_modality(ptu_path) == 'frequency':
+        from .phasor.signal import process_ifli
+        data = process_ifli(ptu_path, phasor_filter=phasor_filter,
+                            filter_kwargs=filter_kwargs, channel=channel)
+    else:
+        if irf_path is None and machine_irf_path is None:
+            choices = [
+                'XLSX IRF (analytical model)',
+                'Machine IRF (.npy pre-built)',
+                'No IRF (uncalibrated)',
+            ]
+            irf_choice = inquirer.prompt([inquirer.List(
+                'irf', message='IRF calibration source?', choices=choices
+            )])['irf']
+            if irf_choice.startswith('XLSX'):
+                irf_path = _ask_path('Path to IRF Excel file (.xlsx)')
+            elif irf_choice.startswith('Machine'):
+                machine_irf_path = _ask_path('Path to machine IRF (.npy)')
+        effective_irf = irf_path or machine_irf_path
+        src_irf = effective_irf
+        effective_irf = irf_path or machine_irf_path
+        data = _process_ptu(ptu_path, effective_irf, channel=channel,
+                            phasor_filter=phasor_filter,
+                            filter_kwargs=filter_kwargs)
+    _data = data
+
+    def _save_callback(state, params):
+        stem = Path(src_ptu).stem if src_ptu else 'phasor_session'
+        default_name = f'{stem}_session.npz'
+        out = _pick_save_file('Save phasor session', default_name)
+        if out:
+            save_session(
+                out,
+                real_cal=_data['real_cal'],
+                imag_cal=_data['imag_cal'],
+                mean=_data['mean'],
+                frequency=_data['frequency'],
+                cursors=state['cursors'],
+                params=params,
+                ptu_file=src_ptu,
+                irf_file=src_irf,
+                display_image=_data.get('display_image'),
+            )
+    state = phasor_cursor_tool(
+        data['real_cal'],
+        data['imag_cal'],
+        data['mean'],
+        data['frequency'],        display_image=data.get('display_image'),        min_photons=min_photons,
+        max_cursors=max_cursors,
+        figsize=figsize,
+        initial_cursors=initial_cursors,
+        initial_params=initial_params,
+        on_save=_save_callback,
+    )
+    return state
+
+def phasor_inquire():
+    print('\n Interactive Phasor Analysis')
+    return launch_phasor()
+
+if __name__ == '__main__':
+    phasor_inquire()