driftlessflip 0.15.0__py3-none-any.whl

driftlessflip/__init__.py

@@ -0,0 +1,5 @@
+"""DriftlessFLIP acquisition and analysis software."""
+
+__version__ = "0.15.0"
+
+__all__ = ["__version__"]

driftlessflip/__main__.py

@@ -0,0 +1,3 @@
+from driftlessflip.cli import main
+
+raise SystemExit(main())

driftlessflip/acquisition/__init__.py

@@ -0,0 +1 @@
+"""Recording orchestration and state management."""

driftlessflip/acquisition/looping.py

@@ -0,0 +1,162 @@
+"""Repeated acquisitions on a fixed start-to-start interval.
+
+Each repeat is an ordinary, independently verifiable recording in its own timestamped
+folder. They are linked only by a shared session identifier in metadata, so a failure in
+one repeat cannot damage the others and a partially completed loop still leaves every
+finished recording valid and verifiable on its own.
+
+The interval is start-to-start, matching how stimulation protocols are specified. It must
+leave room for the acquisition plus finalisation, otherwise repeats would overlap and the
+board would still be running when the next one tried to arm.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from driftlessflip.acquisition.runner import ProgressCallback, RecordingRunner
+from driftlessflip.config import AcquisitionConfig
+
+#: Headroom beyond the acquisition itself for writing, verifying, and arming again.
+FINALISATION_MARGIN_S = 0.5
+
+
+@dataclass(slots=True)
+class LoopOutcome:
+    """What a looped session produced, including any repeat that failed."""
+
+    session_uuid: str
+    directories: list[Path] = field(default_factory=list)
+    failures: list[tuple[int, str]] = field(default_factory=list)
+    completed: int = 0
+    requested: int = 0
+    stopped_early: bool = False
+
+    @property
+    def all_succeeded(self) -> bool:
+        return not self.failures and self.completed == self.requested
+
+
+def validate_loop(config: AcquisitionConfig) -> None:
+    """Reject a loop whose repeats would overlap, before anything is recorded."""
+    if config.loop_repeats < 1:
+        raise ValueError("loop_repeats must be at least 1")
+    if config.loop_repeats == 1:
+        return
+    minimum = config.duration_s + FINALISATION_MARGIN_S
+    if config.loop_interval_s < minimum:
+        raise ValueError(
+            f"loop interval {config.loop_interval_s:g} s is shorter than the "
+            f"{minimum:g} s needed for a {config.duration_s:g} s acquisition plus "
+            "finalisation; repeats would overlap"
+        )
+
+
+class LoopRunner:
+    """Runs N recordings on a fixed start-to-start interval."""
+
+    def __init__(self, config: AcquisitionConfig) -> None:
+        self.config = config
+        self.stop_event = threading.Event()
+        self._active: RecordingRunner | None = None
+        self._lock = threading.Lock()
+
+    def request_stop(self) -> None:
+        """Stop after the current repeat; the running acquisition is asked to stop too."""
+        self.stop_event.set()
+        with self._lock:
+            if self._active is not None:
+                self._active.request_stop()
+
+    def request_annotation(self, message: str, started_monotonic_ns: int | None = None) -> Any:
+        with self._lock:
+            if self._active is None:
+                raise RuntimeError("annotations are accepted only while a recording is running")
+            runner = self._active
+        return runner.request_annotation(message, started_monotonic_ns)
+
+    def update_notes(self, text: str) -> None:
+        """Forward to whichever repeat is currently recording.
+
+        Silently does nothing between repeats -- there is no current recording for the
+        edit to belong to, and (unlike an annotation) there is no operator-facing error
+        to report for a field that just keeps accepting keystrokes either way.
+        """
+        with self._lock:
+            runner = self._active
+        if runner is not None:
+            runner.update_notes(text)
+
+    def run(self, progress: ProgressCallback | None = None) -> LoopOutcome:
+        validate_loop(self.config)
+        callback = progress or (lambda update: None)
+        session_uuid = str(uuid.uuid4())
+        outcome = LoopOutcome(session_uuid=session_uuid, requested=self.config.loop_repeats)
+
+        for repeat in range(self.config.loop_repeats):
+            if self.stop_event.is_set():
+                outcome.stopped_early = True
+                break
+            started = time.monotonic()
+            runner = RecordingRunner(
+                self.config,
+                session_uuid=session_uuid,
+                session_repeat_index=repeat,
+                session_repeat_count=self.config.loop_repeats,
+            )
+            with self._lock:
+                self._active = runner
+            callback(
+                {
+                    "state": "LOOP_REPEAT_STARTING",
+                    "message": f"Repeat {repeat + 1} of {self.config.loop_repeats}",
+                    "session_uuid": session_uuid,
+                    "repeat_index": repeat,
+                }
+            )
+            try:
+                outcome.directories.append(runner.run(callback))
+                outcome.completed += 1
+            except Exception as error:
+                # One repeat failing must not abandon the rest of the session.
+                outcome.failures.append((repeat, str(error)))
+                callback(
+                    {
+                        "state": "LOOP_REPEAT_FAILED",
+                        "message": f"Repeat {repeat + 1} failed: {error}",
+                        "repeat_index": repeat,
+                    }
+                )
+            finally:
+                with self._lock:
+                    self._active = None
+
+            remaining = self.config.loop_repeats - repeat - 1
+            if remaining <= 0 or self.stop_event.is_set():
+                continue
+            # Start-to-start, so the wait is the interval minus however long this repeat took.
+            wait = self.config.loop_interval_s - (time.monotonic() - started)
+            deadline = time.monotonic() + max(0.0, wait)
+            while time.monotonic() < deadline and not self.stop_event.is_set():
+                time.sleep(min(0.05, deadline - time.monotonic()))
+
+        if self.stop_event.is_set():
+            outcome.stopped_early = True
+        callback(
+            {
+                "state": "LOOP_COMPLETE",
+                "message": (
+                    f"{outcome.completed} of {outcome.requested} repeats completed"
+                    + (f", {len(outcome.failures)} failed" if outcome.failures else "")
+                ),
+                "session_uuid": session_uuid,
+                "directories": [str(path) for path in outcome.directories],
+                "failures": outcome.failures,
+            }
+        )
+        return outcome

driftlessflip/acquisition/preview.py

@@ -0,0 +1,485 @@
+"""Non-recording live acquisition for setting up an experiment.
+
+Preview exists so an operator can adjust discriminator levels, offsets, sync
+divider, and the MPET window while watching real count rates and a real decay
+curve, then commit to a recording once the signal looks right. Every preview
+start re-applies the current settings through `configure`, so changing a value
+and previewing again always reflects the new value.
+
+This module deliberately imports nothing from `driftlessflip.storage`. Preview
+cannot create a run directory, a raw TTTR file, or a manifest, so a preview can
+never be mistaken for or promoted into a recording.
+
+Afterpulse and dead-time corrections are applied, so a retuned afterpulse ratio has a
+visible effect. A background *recording* is not, because loading one would mean reaching
+into the storage layer and giving up the guarantee above; background correction belongs
+to the recording, where its provenance can be captured.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+import numpy as np
+
+from driftlessflip.config import (
+    AcquisitionConfig,
+    AnalysisConfig,
+    validate_preview_window,
+)
+from driftlessflip.hardware.base import AcquisitionBackend, release_backend
+from driftlessflip.hardware.simulator import SimulatorBackend
+from driftlessflip.hardware.timeharp import TimeHarpBackend
+from driftlessflip.processing.analysis import calculate_metrics, decode_marker_events
+from driftlessflip.processing.corrections import Corrections
+from driftlessflip.processing.t3 import DecodedT3Chunk, TimeHarpT3Decoder
+
+PreviewCallback = Callable[[dict[str, Any]], None]
+
+PREVIEW_BACKEND_DURATION_S = 359_999.0
+
+
+@dataclass(slots=True)
+class PreviewAccumulator:
+    """Rolling per-sample histograms over a bounded window of the newest samples.
+
+    Sample indices stay absolute so the time axis keeps advancing, but storage is a
+    ring of `window_samples` slots. Because T3 macro-sync is monotonic, a slot only
+    ever needs clearing when the window advances past it.
+    """
+
+    window_samples: int
+    channel_count: int
+    lifetime_bins: int
+    sample_rate_hz: float
+    sync_period_s: float
+    hardware_resolution_ps: float
+    lifetime_bin_width_ps: float
+    histograms: np.ndarray = None  # type: ignore[assignment]
+    marker_bits: np.ndarray = None  # type: ignore[assignment]
+    newest_sample: int = -1
+
+    def __post_init__(self) -> None:
+        self.histograms = np.zeros(
+            (self.window_samples, self.channel_count, self.lifetime_bins), dtype=np.uint32
+        )
+        self.marker_bits = np.zeros(self.window_samples, dtype=np.uint8)
+
+    @property
+    def oldest_sample(self) -> int:
+        return max(0, self.newest_sample - self.window_samples + 1)
+
+    def _sample_index(self, macro_sync: np.ndarray) -> np.ndarray:
+        return np.floor(
+            macro_sync.astype(np.float64) * self.sync_period_s * self.sample_rate_hz
+        ).astype(np.int64)
+
+    def add(self, decoded: DecodedT3Chunk) -> None:
+        photon_sample = (
+            self._sample_index(decoded.photon_macro_sync)
+            if len(decoded.photon_macro_sync)
+            else None
+        )
+        marker_sample = (
+            self._sample_index(decoded.marker_macro_sync)
+            if len(decoded.marker_macro_sync)
+            else None
+        )
+        present = [block for block in (photon_sample, marker_sample) if block is not None]
+        if not present:
+            return
+        self._advance_to(int(max(int(block.max()) for block in present)))
+
+        if photon_sample is not None:
+            lifetime_bin = np.floor(
+                decoded.photon_dtime.astype(np.float64)
+                * self.hardware_resolution_ps
+                / self.lifetime_bin_width_ps
+            ).astype(np.int64)
+            channel = decoded.photon_channels.astype(np.int64)
+            keep = (
+                (photon_sample > self.newest_sample - self.window_samples)
+                & (photon_sample >= 0)
+                & (channel >= 0)
+                & (channel < self.channel_count)
+                & (lifetime_bin >= 0)
+                & (lifetime_bin < self.lifetime_bins)
+            )
+            np.add.at(
+                self.histograms,
+                (
+                    photon_sample[keep] % self.window_samples,
+                    channel[keep],
+                    lifetime_bin[keep],
+                ),
+                1,
+            )
+        if marker_sample is not None:
+            keep = marker_sample > self.newest_sample - self.window_samples
+            np.bitwise_or.at(
+                self.marker_bits,
+                marker_sample[keep] % self.window_samples,
+                decoded.marker_bits[keep].astype(np.uint8),
+            )
+
+    def _advance_to(self, newest: int) -> None:
+        if newest <= self.newest_sample:
+            return
+        advanced = newest - self.newest_sample
+        if advanced >= self.window_samples:
+            self.histograms[:] = 0
+            self.marker_bits[:] = 0
+        else:
+            slots = np.arange(self.newest_sample + 1, newest + 1) % self.window_samples
+            self.histograms[slots] = 0
+            self.marker_bits[slots] = 0
+        self.newest_sample = newest
+
+    def ordered_window(self) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Histograms, marker bits, and absolute sample indices in time order."""
+        if self.newest_sample < 0:
+            empty_hist = np.zeros((0, self.channel_count, self.lifetime_bins), dtype=np.uint32)
+            return empty_hist, np.zeros(0, dtype=np.uint8), np.zeros(0, dtype=np.int64)
+        indices = np.arange(self.oldest_sample, self.newest_sample + 1, dtype=np.int64)
+        slots = indices % self.window_samples
+        return self.histograms[slots], self.marker_bits[slots], indices
+
+
+class PreviewRunner:
+    """Runs acquisition for display only. Writes nothing, anywhere."""
+
+    #: Parameters applied when metrics are calculated from an already-filled histogram,
+    #: so they can be retuned while a preview runs. Everything else either reprograms the
+    #: board -- which TH260Lib forbids during a measurement -- or fixes a buffer shape.
+    LIVE_ADJUSTABLE = frozenset(
+        {"t0_ns", "mpet_window_start_ns", "mpet_window_end_ns", "afterpulse_ratio"}
+    )
+
+    #: Per-sample metrics the display needs, cached in a ring beside the histograms.
+    CACHED_METRICS = (
+        "intensity_photons_per_s",
+        "mpet_ns",
+        "corrected_photons",
+        "phasor_g",
+        "phasor_s",
+    )
+
+    def __init__(self, config: AcquisitionConfig) -> None:
+        self.config = config
+        self.stop_event = threading.Event()
+        self.backend: AcquisitionBackend | None = None
+        self._analysis_lock = threading.Lock()
+        # Metrics for samples that are already complete do not change, so they are kept
+        # in a ring parallel to the histograms and only the newly filled samples are
+        # recalculated. Recomputing the whole window every snapshot made the cost grow
+        # with elapsed time until the window was full.
+        self._metrics: dict[str, np.ndarray] = {}
+        self._metrics_through = -1
+        self._metrics_signature: tuple[Any, ...] | None = None
+        #: Populated when the device did not stop or close cleanly.
+        self.device_release_failures: list[str] = []
+        self._clear_decay_requested = threading.Event()
+        #: The decay curve sums samples newer than this. Left at -1 (everything in the
+        #: window qualifies) until "Clear" moves it forward -- a display-only reference
+        #: that never touches the accumulator itself, so the intensity/MPET trace history
+        #: (built from the same window) is not disturbed by clearing the decay curve.
+        self._decay_reference_sample = -1
+
+    def request_stop(self) -> None:
+        self.stop_event.set()
+
+    def request_clear_decay(self) -> None:
+        """Make the decay curve start summing fresh from the next sample onward.
+
+        A long preview window makes a real change (CFD threshold, sync offset, even
+        excitation power adjusted externally) hard to see, since the decay curve is the
+        sum over the whole window and old photons dominate until the window naturally
+        rolls past them. This restarts that sum immediately without stopping preview or
+        touching the underlying rolling accumulator, so nothing already displayed on the
+        intensity/MPET trace is rewritten.
+        """
+        self._clear_decay_requested.set()
+
+    def update_analysis(self, **changes: float) -> AnalysisConfig:
+        """Retune a post-processing parameter without restarting the preview."""
+        rejected = set(changes) - self.LIVE_ADJUSTABLE
+        if rejected:
+            raise ValueError(
+                "these parameters cannot change while a measurement is running: "
+                + ", ".join(sorted(rejected))
+            )
+        with self._analysis_lock:
+            updated = replace(self.config.analysis, **changes)
+            updated.validate()
+            self.config.analysis = updated
+            return updated
+
+    def _analysis_snapshot(self) -> AnalysisConfig:
+        with self._analysis_lock:
+            return self.config.analysis
+
+    def validate(self) -> None:
+        """Check only what preview actually uses; no output location is required."""
+        self.config.hardware.validate()
+        self.config.analysis.validate()
+        validate_preview_window(self.config.preview_window_s)
+        budget = self.config.max_histogram_memory_mb * 1024 * 1024
+        if self.estimated_preview_bytes() > budget:
+            raise ValueError(
+                f"preview window requires {self.estimated_preview_bytes() / 1048576:,.1f} MiB, "
+                f"exceeding the {self.config.max_histogram_memory_mb:,} MiB budget"
+            )
+
+    def window_samples(self) -> int:
+        return max(1, int(np.ceil(self.config.preview_window_s * self.config.analysis.sample_rate_hz)))
+
+    def estimated_preview_bytes(self) -> int:
+        return (
+            self.window_samples()
+            * len(self.config.hardware.channels)
+            * self.config.analysis.lifetime_bins
+            * 4
+        )
+
+    def _make_backend(self) -> AcquisitionBackend:
+        if self.config.backend == "simulator":
+            return SimulatorBackend()
+        return TimeHarpBackend(self.config.timeharp_library_path, self.config.device_serial)
+
+    def run(self, progress: PreviewCallback | None = None) -> dict[str, Any]:
+        """Preview until `request_stop`. Returns a summary; creates no files."""
+        self.validate()
+        callback = progress or (lambda update: None)
+        self.backend = self._make_backend()
+        started_monotonic = time.perf_counter()
+        chunk_count = 0
+        overrun_seen = False
+        try:
+            callback({"state": "PREVIEW_OPENING", "message": "Opening acquisition backend"})
+            device_info = self.backend.open()
+            # Settings are re-applied on every preview start, so an edited value takes
+            # effect the next time the operator previews.
+            effective = self.backend.configure(
+                replace(self.config, duration_s=PREVIEW_BACKEND_DURATION_S)
+            )
+            tick_rate = float(effective.get("t3_macrotime_tick_rate_hz") or 0)
+            if tick_rate <= 0:
+                raise RuntimeError("T3 macrotime tick rate is not available or not positive")
+            resolution_ps = float(
+                effective.get("hardware_resolution_ps")
+                or self.config.analysis.lifetime_bin_width_ps
+            )
+            analysis = self.config.analysis
+            accumulator = PreviewAccumulator(
+                window_samples=self.window_samples(),
+                channel_count=len(self.config.hardware.channels),
+                lifetime_bins=analysis.lifetime_bins,
+                sample_rate_hz=analysis.sample_rate_hz,
+                sync_period_s=1 / tick_rate,
+                hardware_resolution_ps=resolution_ps,
+                lifetime_bin_width_ps=analysis.lifetime_bin_width_ps,
+            )
+            decoder = TimeHarpT3Decoder()
+            callback(
+                {
+                    "state": "PREVIEW_RUNNING",
+                    "message": "Preview running; nothing is being saved",
+                    "device": device_info,
+                    "effective_hardware_configuration": effective,
+                    "preview_window_s": self.config.preview_window_s,
+                }
+            )
+            preview_start_utc = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+            self.backend.start(PREVIEW_BACKEND_DURATION_S)
+            marker_event_count = 0
+            marker_record_count = 0
+            last_update = 0.0
+            while not self.stop_event.is_set():
+                chunk = self.backend.read_fifo()
+                # Preview saves nothing, so a lost chunk costs a redraw, not data.
+                if chunk.integrity_lost:
+                    overrun_seen = True
+                if len(chunk.records):
+                    chunk_count += 1
+                    decoded = decoder.decode(chunk.records)
+                    accumulator.add(decoded)
+                    marker_events = decode_marker_events(
+                        decoded,
+                        self.config.hardware.markers,
+                        sync_period_s=1 / tick_rate,
+                        sample_rate_hz=analysis.sample_rate_hz,
+                        recording_start_utc=preview_start_utc,
+                        first_sequence=marker_event_count,
+                        first_marker_record_sequence=marker_record_count,
+                    )
+                    marker_event_count += len(marker_events)
+                    marker_record_count += decoded.marker_record_count
+                    for marker_event in marker_events:
+                        callback(
+                            {
+                                "state": "MARKER_EVENT",
+                                "message": "TTL marker event observed in preview",
+                                "recording": False,
+                                "marker_event": marker_event,
+                            }
+                        )
+                elif self.backend.is_complete():
+                    break
+                else:
+                    time.sleep(0.002)
+                if self._clear_decay_requested.is_set():
+                    self._decay_reference_sample = accumulator.newest_sample
+                    self._clear_decay_requested.clear()
+                now = time.monotonic()
+                if now - last_update >= 0.2:
+                    callback(self._snapshot(accumulator, overrun_seen))
+                    last_update = now
+            callback(self._snapshot(accumulator, overrun_seen, state="PREVIEW_STOPPED"))
+            return {
+                "state": "stopped",
+                "elapsed_s": time.perf_counter() - started_monotonic,
+                "chunks_read": chunk_count,
+                "fifo_overrun_observed": overrun_seen,
+                "effective_hardware_configuration": effective,
+            }
+        except Exception as error:
+            callback({"state": "PREVIEW_ERROR", "message": str(error)})
+            raise
+        finally:
+            self.device_release_failures = release_backend(
+                self.backend,
+                lambda message: callback({"state": "DEVICE_RELEASE_FAILED", "message": message}),
+            )
+
+    def _window_metrics(
+        self,
+        accumulator: PreviewAccumulator,
+        histograms: np.ndarray,
+        marker_bits: np.ndarray,
+        indices: np.ndarray,
+        analysis: AnalysisConfig,
+    ) -> dict[str, np.ndarray]:
+        """Per-sample metrics for the whole window, recalculating only what changed.
+
+        A completed sample's histogram never changes again, so its metrics do not
+        either. Only the samples filled since the last snapshot are recalculated, plus
+        the sample on the boundary, which was still accumulating when it was last seen.
+        Retuning a live parameter changes the signature and forces a full recalculation,
+        because it applies to every sample in the window.
+        """
+        # Afterpulse and dead time are applied here too, so retuning the afterpulse ratio
+        # during a preview visibly changes MPET rather than doing nothing.
+        channels = self.config.hardware.channels
+        corrections = Corrections(
+            dead_time_s=np.asarray([channel.dead_time_ns * 1e-9 for channel in channels]),
+            afterpulse_ratio=np.asarray(
+                self.config.hardware.afterpulse_ratios(analysis.afterpulse_ratio)
+            ),
+            sample_period_s=1.0 / analysis.sample_rate_hz,
+        )
+        signature = (
+            analysis.t0_ns,
+            analysis.mpet_window_start_ns,
+            analysis.mpet_window_end_ns,
+            analysis.sample_rate_hz,
+            analysis.lifetime_bins,
+            analysis.lifetime_bin_width_ps,
+            analysis.laser_repetition_rate_hz,
+            tuple(np.asarray(corrections.afterpulse_ratio).tolist()),
+            tuple(np.asarray(corrections.dead_time_s).tolist()),
+            accumulator.window_samples,
+            accumulator.channel_count,
+        )
+        window, newest = accumulator.window_samples, accumulator.newest_sample
+        if signature != self._metrics_signature:
+            self._metrics = {
+                name: np.zeros((window, accumulator.channel_count), dtype=np.float64)
+                for name in self.CACHED_METRICS
+            }
+            self._metrics_signature = signature
+            self._metrics_through = -1
+
+        # The boundary sample was still filling when it was cached, so recompute it.
+        first_stale = max(int(indices[0]), self._metrics_through)
+        stale = np.arange(first_stale, newest + 1, dtype=np.int64)
+        if len(stale):
+            offsets = stale - int(indices[0])
+            fresh = calculate_metrics(
+                histograms[offsets],
+                marker_bits[offsets],
+                analysis,
+                corrections=corrections,
+            )
+            slots = stale % window
+            for name in self.CACHED_METRICS:
+                self._metrics[name][slots] = fresh[name]
+        self._metrics_through = newest
+
+        slots = indices % window
+        return {name: self._metrics[name][slots] for name in self.CACHED_METRICS}
+
+    def _snapshot(
+        self,
+        accumulator: PreviewAccumulator,
+        overrun_seen: bool,
+        state: str = "PREVIEW_RUNNING",
+    ) -> dict[str, Any]:
+        assert self.backend is not None
+        histograms, marker_bits, indices = accumulator.ordered_window()
+        update: dict[str, Any] = {
+            "state": state,
+            "message": "Preview running; nothing is being saved"
+            if state == "PREVIEW_RUNNING"
+            else "Preview stopped; nothing was saved",
+            "recording": False,
+            "fifo_overrun_observed": overrun_seen,
+            "preview_window_s": self.config.preview_window_s,
+        }
+        try:
+            update["status"] = self.backend.status()
+        except Exception:
+            update["status"] = None
+        if not len(indices):
+            return update
+        analysis = self._analysis_snapshot()
+        metrics = self._window_metrics(accumulator, histograms, marker_bits, indices, analysis)
+        if state == "PREVIEW_RUNNING" and len(indices) > 1:
+            # The newest sample was still accumulating at the moment this snapshot was
+            # taken -- more records belonging to it may arrive before the next one. Shown
+            # as if complete, it reads as a spurious low point at the live edge, since
+            # intensity/MPET are computed as if a full sample period had elapsed. Holding
+            # it back one snapshot means it only appears once genuinely finished; the
+            # final snapshot after Stop shows it regardless, since there is no "next" one
+            # to reveal it as complete.
+            histograms = histograms[:-1]
+            indices = indices[:-1]
+            metrics = {name: values[:-1] for name, values in metrics.items()}
+        update.update(
+            {
+                "sample_time_s": (indices.astype(np.float64) + 0.5) / analysis.sample_rate_hz,
+                "sample_indices": indices,
+                "intensity": metrics["intensity_photons_per_s"],
+                "mpet": metrics["mpet_ns"],
+                "corrected_photons": metrics["corrected_photons"],
+                # Already computed by calculate_metrics, so publishing them costs nothing
+                # and lets the lower panel offer the same choices it does while recording.
+                "phasor_g": metrics["phasor_g"],
+                "phasor_s": metrics["phasor_s"],
+                # The summed decay over the window is what CFD, offset, and t0 are set
+                # from -- restricted to samples newer than the last "Clear" (§
+                # request_clear_decay), if any.
+                "decay_counts": (
+                    histograms[indices > self._decay_reference_sample].sum(axis=0)
+                    if np.any(indices > self._decay_reference_sample)
+                    else np.zeros_like(histograms[0])
+                ),
+                "decay_time_ns": (np.arange(analysis.lifetime_bins, dtype=np.float64) + 0.5)
+                * analysis.lifetime_bin_width_ps
+                / 1000.0,
+            }
+        )
+        return update