openflo 2.6.0__py3-none-any.whl

openflo/__init__.py

@@ -0,0 +1,286 @@
+"""OpenFlo — flow cytometry analysis pipeline.
+
+Public surface re-exported here so ``from openflo import FlowSample`` works
+without callers needing to know which submodule the symbol lives in. The
+heavyweight submodules (``openflo.gui``, ``openflo.preview``) are NOT
+imported here — importing the package shouldn't load Tk or matplotlib's
+Tk backend.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Static type checkers see the public surface up-front. At runtime the
+    # ``__getattr__`` hook below resolves these lazily without paying the
+    # phenograph / pandas import cost just to ``import openflo``.
+    from .annotate import (
+        annotate_by_reference,
+        mem_label,
+        mem_scores,
+        parse_signature_table,
+        population_states,
+    )
+    from .audit import AuditLog
+    from .calibration import (
+        apply_calibration,
+        detect_bead_peaks,
+        fit_mesf_calibration,
+    )
+    from .compliance import (
+        build_manifest,
+        record_to_markdown,
+        sign_manifest,
+        verify_record,
+    )
+    from .diffexp import (
+        cluster_abundance,
+        differential_abundance,
+        differential_test,
+        marker_expression,
+    )
+    from .interop import (
+        mds_embed,
+        sample_distance_matrix,
+        to_anndata,
+        write_h5ad,
+    )
+    from .pipeline import (
+        ClusteringError,
+        CompensationError,
+        CytoNorm,
+        FcsParseError,
+        FlowExperiment,
+        FlowSample,
+        FMOGater,
+        GateError,
+        OpenFloError,
+        WspParseError,
+        WspReader,
+        WspWriter,
+        concatenate,
+        cumulative_gate_mask,
+        describe_gate,
+        flowsom_layout,
+        flowsom_mst,
+        gate_to_mask,
+        optimize_compensation,
+        read_compensation_matrix,
+        read_template_gates,
+        set_default_palette,
+        write_compensation_matrix,
+        write_fcs,
+    )
+    from .report import (
+        build_html_report,
+        df_to_html_table,
+        figure_to_data_uri,
+    )
+    from .spectral import (
+        apply_unmixing,
+        build_reference_spectra,
+        spectral_condition_number,
+        spectral_similarity_matrix,
+        spillover_spread_matrix,
+        unmix,
+        unmixing_qc,
+    )
+    from .stats import (
+        compare_all_features,
+        compare_groups,
+        group_kde,
+        p_to_stars,
+        to_prism_column,
+        to_prism_grouped,
+        volcano_data,
+    )
+    from .trajectory import (
+        compute_pseudotime,
+        pseudotime_trends,
+        robust_root,
+    )
+    from .voltage import VoltageTitration
+
+try:
+    __version__ = _pkg_version("openflo")
+except PackageNotFoundError:
+    # Package not installed (e.g. running from a source checkout without
+    # `pip install -e .`). Fall back to a sentinel so callers can still
+    # introspect.
+    __version__ = "0.0.0+unknown"
+
+# Public surface — submodules are imported lazily on first attribute access
+# (PEP 562), so `import openflo` does not pay for the scientific stack.
+# Re-measured 2026-09-10 (numpy 2.5, pandas 3.0): `import openflo` ~81 ms and
+# loads neither numpy, pandas nor scipy; numpy + pandas alone is ~330 ms and
+# `import openflo.pipeline` ~506 ms. The previous note here said "~150 ms for
+# numpy+pandas", which was true of a lighter stack and is now off by 2x —
+# which is the trouble with a timing in a comment.
+#
+# tests/test_import_is_lazy.py pins the PROPERTY rather than the numbers: one
+# stray top-level `import numpy` here, or in anything this imports, and the
+# laziness is gone with nothing to say so.
+_PUBLIC = {
+    # Calibration
+    "detect_bead_peaks":     "openflo.calibration",
+    "fit_mesf_calibration":  "openflo.calibration",
+    "apply_calibration":     "openflo.calibration",
+    # Compliance
+    "build_manifest":        "openflo.compliance",
+    "sign_manifest":         "openflo.compliance",
+    "verify_record":         "openflo.compliance",
+    "record_to_markdown":    "openflo.compliance",
+    # Annotation
+    "mem_scores":            "openflo.annotate",
+    "mem_label":             "openflo.annotate",
+    "population_states":     "openflo.annotate",
+    "parse_signature_table": "openflo.annotate",
+    "annotate_by_reference": "openflo.annotate",
+    # Provenance
+    "AuditLog":              "openflo.audit",
+    # Core pipeline
+    "FlowSample":            "openflo.pipeline",
+    "FMOGater":              "openflo.pipeline",
+    "FlowExperiment":        "openflo.pipeline",
+    "CytoNorm":              "openflo.pipeline",
+    "concatenate":           "openflo.pipeline",
+    # IO
+    "WspReader":             "openflo.pipeline",
+    "WspWriter":             "openflo.pipeline",
+    "read_template_gates":   "openflo.pipeline",
+    "read_compensation_matrix":  "openflo.pipeline",
+    "write_compensation_matrix": "openflo.pipeline",
+    "optimize_compensation": "openflo.pipeline",
+    # Gates
+    "describe_gate":         "openflo.pipeline",
+    "gate_to_mask":          "openflo.pipeline",
+    "cumulative_gate_mask":  "openflo.pipeline",
+    # Defaults / config
+    "set_default_palette":   "openflo.pipeline",
+    "write_fcs":             "openflo.pipeline",
+    "flowsom_mst":           "openflo.pipeline",
+    "flowsom_layout":        "openflo.pipeline",
+    # Tools
+    "VoltageTitration":      "openflo.voltage",
+    "differential_test":     "openflo.diffexp",
+    "differential_abundance": "openflo.diffexp",
+    "cluster_abundance":     "openflo.diffexp",
+    "marker_expression":     "openflo.diffexp",
+    "sample_distance_matrix": "openflo.interop",
+    "mds_embed":             "openflo.interop",
+    "to_anndata":            "openflo.interop",
+    "write_h5ad":            "openflo.interop",
+    "build_reference_spectra": "openflo.spectral",
+    "unmix":                 "openflo.spectral",
+    "apply_unmixing":        "openflo.spectral",
+    "spectral_similarity_matrix": "openflo.spectral",
+    "spectral_condition_number":  "openflo.spectral",
+    "spillover_spread_matrix":    "openflo.spectral",
+    "unmixing_qc":           "openflo.spectral",
+    "build_html_report":     "openflo.report",
+    "df_to_html_table":      "openflo.report",
+    "figure_to_data_uri":    "openflo.report",
+    "compare_groups":        "openflo.stats",
+    "compare_all_features":  "openflo.stats",
+    "volcano_data":          "openflo.stats",
+    "group_kde":             "openflo.stats",
+    "to_prism_column":       "openflo.stats",
+    "to_prism_grouped":      "openflo.stats",
+    "p_to_stars":            "openflo.stats",
+    "compute_pseudotime":    "openflo.trajectory",
+    "pseudotime_trends":     "openflo.trajectory",
+    "robust_root":           "openflo.trajectory",
+    # Exception hierarchy
+    "OpenFloError":          "openflo.pipeline",
+    "FcsParseError":         "openflo.pipeline",
+    "CompensationError":     "openflo.pipeline",
+    "WspParseError":         "openflo.pipeline",
+    "GateError":             "openflo.pipeline",
+    "ClusteringError":       "openflo.pipeline",
+}
+
+
+def __getattr__(name):
+    mod_name = _PUBLIC.get(name)
+    if mod_name is None:
+        raise AttributeError(f"module 'openflo' has no attribute {name!r}")
+    import importlib
+    mod = importlib.import_module(mod_name)
+    obj = getattr(mod, name)
+    globals()[name] = obj   # cache
+    return obj
+
+
+# Build __all__ as a plain literal so pyright can verify it. Keep in sync
+# with _PUBLIC above.
+__all__ = [
+    "AuditLog",
+    "ClusteringError",
+    "annotate_by_reference",
+    "apply_calibration",
+    "build_manifest",
+    "CompensationError",
+    "CytoNorm",
+    "FcsParseError",
+    "FlowExperiment",
+    "FlowSample",
+    "FMOGater",
+    "GateError",
+    "OpenFloError",
+    "VoltageTitration",
+    "WspParseError",
+    "WspReader",
+    "WspWriter",
+    "apply_unmixing",
+    "build_html_report",
+    "build_reference_spectra",
+    "cluster_abundance",
+    "compare_groups",
+    "compare_all_features",
+    "volcano_data",
+    "compute_pseudotime",
+    "concatenate",
+    "cumulative_gate_mask",
+    "describe_gate",
+    "detect_bead_peaks",
+    "df_to_html_table",
+    "differential_abundance",
+    "differential_test",
+    "figure_to_data_uri",
+    "fit_mesf_calibration",
+    "flowsom_layout",
+    "flowsom_mst",
+    "gate_to_mask",
+    "group_kde",
+    "marker_expression",
+    "mds_embed",
+    "mem_label",
+    "mem_scores",
+    "optimize_compensation",
+    "p_to_stars",
+    "parse_signature_table",
+    "population_states",
+    "pseudotime_trends",
+    "read_compensation_matrix",
+    "read_template_gates",
+    "record_to_markdown",
+    "robust_root",
+    "sample_distance_matrix",
+    "set_default_palette",
+    "sign_manifest",
+    "spectral_condition_number",
+    "spectral_similarity_matrix",
+    "spillover_spread_matrix",
+    "to_anndata",
+    "to_prism_column",
+    "to_prism_grouped",
+    "unmix",
+    "unmixing_qc",
+    "verify_record",
+    "write_compensation_matrix",
+    "write_fcs",
+    "write_h5ad",
+    "__version__",
+]

openflo/_console.py

@@ -0,0 +1,39 @@
+"""One-line guard against the Windows console killing a CLI.
+
+Every command-line entry point here prints characters outside cp1252 — check
+and cross marks in the self-test table, arrows in the titration output, `Δ` in
+the comparison report, superscripts in the synthetic marker names. A legacy
+Windows console encodes stdout as cp1252, so printing any of them raises
+``UnicodeEncodeError`` and the command dies having reported nothing.
+
+That is worst on exactly the commands a new user runs first: `openflo-selftest`
+crashed mid-table instead of saying whether the install reproduces reference
+behaviour, and `openflo-doctor --help` crashed on the arrow in its own epilog.
+
+Call this FIRST in ``main()`` — before building the argument parser. Argparse
+prints ``--help`` and exits from inside ``parse_args``, so a guard placed after
+that line does not protect the help text (which is how the doctor's crash
+survived having the guard at all).
+
+`openflo.cli` does the same thing at import time, which is fine for a module
+that is only ever a CLI. This is a function so that importing, say,
+``openflo.selftest`` as a library does not silently reconfigure the caller's
+streams.
+"""
+from __future__ import annotations
+
+import sys
+
+
+def force_utf8_streams() -> None:
+    """Re-encode stdout/stderr as UTF-8, replacing anything unencodable.
+
+    Deliberately best-effort: a stream that does not support ``reconfigure``
+    (a pytest capture buffer, a pipe wrapper, an embedded interpreter) is left
+    alone rather than failing the command that was about to run.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding='utf-8', errors='replace')  # type: ignore[union-attr]
+        except Exception:                                            # noqa: BLE001
+            pass

openflo/_golden.json

@@ -0,0 +1,53 @@
+{
+  "_comment": "Golden behavior baseline for `openflo-selftest` and the pytest continuity suite. Values are computed from the SEEDED synthetic generators (openflo.synthetic), so they must reproduce run-to-run. A metric drifting outside its tolerance means a feature's behavior changed. Update these numbers ONLY for an intended change (regenerate via `openflo-selftest --update`). The tight 1e-9 tolerances on count/literal metrics (debris/doublets/compensation) rely on the numpy==2.4.6 pin holding on every synonymous stack (incl. RAPIDS 26.06) \u2014 the RNG stream + pure-float64 ops are then bit-identical, so a numpy bump requires re-baselining. calibration.slope/r2 sit at 1e-3 (KMeans peaks are stable; only LAPACK lstsq wiggles ~1e-12). viability_pct (logicle C-ext + scipy histogram valley) and leiden_n (leidenalg/igraph version) are genuinely platform-variable and stay loose by design. compensation.* APPLY compensation to data with a known spillover baked in and check the true signal is recovered: residual_err is the max error relative to the signal (a transposed matmul leaves this large) and signal_retained guards the degenerate 'zero everything' answer that would flatter the residual. The previous apc_leak metric only round-tripped the generator's own matrix through a CSV and ran no compensation code, so it stayed green through the 2.2.1 transpose bug.",
+  "metrics": {
+    "autoclean.debris_pct": {
+      "value": 7.05,
+      "tol": 1e-09,
+      "label": "Auto-clean debris removed (bead 4 \u00b5m)",
+      "unit": "%"
+    },
+    "autoclean.viability_pct": {
+      "value": 7.97,
+      "tol": 0.6,
+      "label": "Auto-clean dead cells removed (viability)",
+      "unit": "%"
+    },
+    "autoclean.doublets_pct": {
+      "value": 5.0,
+      "tol": 1e-09,
+      "label": "Auto-clean doublets removed",
+      "unit": "%"
+    },
+    "cluster.leiden_n": {
+      "value": 18,
+      "tol": 2,
+      "label": "Leiden clusters (PBMC, res 0.5)",
+      "unit": "count"
+    },
+    "calibration.slope": {
+      "value": 1.9978,
+      "tol": 0.001,
+      "label": "MESF calibration slope (MESF = 2\u00b7MFI + 100)",
+      "unit": ""
+    },
+    "calibration.r2": {
+      "value": 1.0,
+      "tol": 0.001,
+      "label": "MESF calibration R\u00b2",
+      "unit": ""
+    },
+    "compensation.residual_err": {
+      "value": 0.0,
+      "tol": 1e-09,
+      "label": "Compensation residual vs true signal",
+      "unit": ""
+    },
+    "compensation.signal_retained": {
+      "value": 1.0,
+      "tol": 1e-06,
+      "label": "Compensation signal retained",
+      "unit": "x"
+    }
+  }
+}

openflo/annotate.py

@@ -0,0 +1,213 @@
+"""Automated population annotation.
+
+Two complementary, dependency-light ways to turn numeric cluster IDs into
+biological labels:
+
+  * **MEM** (Marker Enrichment Modeling; Diggins et al. 2017) — a quantitative
+    enrichment score per marker per population, against a reference (the rest of
+    the cells by default), yielding labels like ``CD3⁺⁸ CD4⁺⁶ CD8⁻⁴``. Captures
+    both the median shift and the spread (IQR) change.
+  * **Reference-table** annotation (ACDC / Scyan style) — match each
+    population's +/- marker pattern to a user-supplied ``name: CD3+ CD4+ CD8-``
+    table and assign the best-fitting cell type.
+
+Pure numpy / pandas — no deep learning. The GUI runs these on a clustered
+sample and writes the names back onto the populations.
+"""
+from __future__ import annotations
+
+import re
+
+import numpy as np
+import pandas as pd
+
+# Subscript/superscript-free signed format keeps cp1252 stdout happy.
+_SIGN = {1: '+', -1: '-'}
+
+
+def scale_markers(X, lo_pct=1.0, hi_pct=99.0, out_max=10.0):
+    """Scale each marker (column) to ``[0, out_max]`` using robust percentiles
+    (``lo_pct``→0, ``hi_pct``→out_max), clipped — so the MEM magnitude term is
+    comparable across markers on different intensity scales."""
+    X = np.asarray(X, dtype=float)
+    lo = np.nanpercentile(X, lo_pct, axis=0)
+    hi = np.nanpercentile(X, hi_pct, axis=0)
+    rng = np.where(hi > lo, hi - lo, 1.0)
+    return np.clip((X - lo) / rng, 0.0, 1.0) * out_max
+
+
+def _iqr(a):
+    a = a[np.isfinite(a)]
+    if a.size == 0:
+        return 0.0
+    return float(np.percentile(a, 75) - np.percentile(a, 25))
+
+
+def mem_scores(data, labels, markers, reference=None, scale=True, eps=0.5):
+    """Marker Enrichment Modeling scores.
+
+    ``data`` : DataFrame or array (cells × len(markers)).
+    ``labels`` : per-cell population label (array-like).
+    ``markers`` : marker names (columns / order of ``data``).
+    ``reference`` : a label to use as the reference population for every
+        comparison; ``None`` (default) uses "all other cells" per population.
+
+    For each population *p* and marker *m*::
+
+        MAG = median_p − median_ref
+        raw = |MAG| + IQR_ref / IQR_p − 1          (floored at 0)
+        MEM = sign(MAG) · raw
+
+    Scores are then globally rescaled so the largest |MEM| maps to 10 (the MEM
+    convention). Returns a DataFrame indexed by population, columns = markers,
+    of (rounded) MEM values in ``[-10, 10]``."""
+    if isinstance(data, pd.DataFrame):
+        X = data[list(markers)].to_numpy(dtype=float)
+    else:
+        X = np.asarray(data, dtype=float)
+    labels = np.asarray(labels)
+    if scale:
+        X = scale_markers(X)
+    pops = [p for p in pd.unique(labels) if p is not None and p == p]  # noqa: PLR0124
+    pops = sorted(pops, key=str)
+
+    rows = {}
+    for p in pops:
+        in_p = labels == p
+        if int(in_p.sum()) == 0:
+            continue
+        ref_mask = (labels == reference) if reference is not None else ~in_p
+        if int(ref_mask.sum()) == 0:
+            ref_mask = ~in_p
+        vals = np.empty(len(markers))
+        for j in range(len(markers)):
+            pj, rj = X[in_p, j], X[ref_mask, j]
+            mag = float(np.nanmedian(pj) - np.nanmedian(rj))
+            iqr_p = _iqr(pj)
+            # The IQR ratio is the "this population is tighter than the rest"
+            # half of the score. A population with NO measurable spread — a
+            # single event, or every event identical — has an IQR of exactly
+            # 0, and `+ eps` turned that into "perfectly tight", which the
+            # ratio rewards. Because MEM then rescales globally so the largest
+            # |score| maps to 10, one such cluster set the scale for the whole
+            # table: measured, a single-event cluster pushed three real
+            # populations from 10 down to 4. No measurable spread supports no
+            # claim about spread, so the term drops out and the score rests on
+            # the median shift alone.
+            ratio = (_iqr(rj) + eps) / (iqr_p + eps) if iqr_p > 0 else 1.0
+            raw = abs(mag) + ratio - 1.0
+            vals[j] = np.sign(mag) * max(raw, 0.0)
+        rows[p] = vals
+
+    mem = pd.DataFrame(rows, index=pd.Index(markers)).T  # pops × markers
+    mx = float(np.nanmax(np.abs(mem.to_numpy()))) if mem.size else 0.0
+    if mx > 0:
+        mem = (mem / mx * 10.0).round(0)
+    return mem
+
+
+def mem_label(mem_row, markers=None, threshold=2.0, max_markers=8):
+    """Build a MEM text label from one population's score row (a Series or
+    array): markers sorted by descending |score|, kept above ``threshold``,
+    formatted ``CD3+8 CD4+6 CD8-4``. Returns '' when nothing is enriched."""
+    if isinstance(mem_row, pd.Series):
+        items = [(m, float(v)) for m, v in mem_row.items()]
+    else:
+        items = list(zip(markers or [], [float(v) for v in mem_row],
+                         strict=True))
+    items = [(m, v) for m, v in items if abs(v) >= threshold]
+    items.sort(key=lambda t: abs(t[1]), reverse=True)
+    items = items[:max_markers]
+    return ' '.join(f"{m}{_SIGN.get(int(np.sign(v)), '')}{abs(int(round(v)))}"
+                    for m, v in items)
+
+
+def population_states(mem, threshold=3.0):
+    """Reduce a MEM DataFrame to per-population +/- marker states
+    (``{population: {marker: +1 | -1}}``) for reference matching: a marker is
+    ``+1`` above ``+threshold``, ``-1`` below ``-threshold``, omitted if
+    ambiguous."""
+    states = {}
+    for pop, row in mem.iterrows():
+        st = {}
+        for m, v in row.items():
+            if v >= threshold:
+                st[m] = 1
+            elif v <= -threshold:
+                st[m] = -1
+        states[pop] = st
+    return states
+
+
+def parse_signature_table(text):
+    """Parse a reference cell-type table into ``{name: {marker: +1 | -1}}``.
+
+    One cell type per line, ``Name: CD3+ CD4+ CD8-`` (or comma/whitespace
+    separated). A marker token ending in ``+``/``hi`` is required-positive,
+    ``-``/``lo`` required-negative. Blank lines and ``#`` comments are ignored.
+    """
+    table = {}
+    for line in (text or '').splitlines():
+        line = line.strip()
+        if not line or line.startswith('#'):
+            continue
+        if ':' in line:
+            name, rest = line.split(':', 1)
+        else:
+            parts = line.split(None, 1)
+            if len(parts) != 2:
+                continue
+            name, rest = parts
+        name = name.strip()
+        sig = {}
+        for tok in re.split(r'[,\s]+', rest.strip()):
+            if not tok:
+                continue
+            m = re.match(r'^(.*?)(\+\+?|--?|hi|lo|high|low)$', tok,
+                         flags=re.IGNORECASE)
+            if not m:
+                continue
+            marker, sign = m.group(1).strip(), m.group(2).lower()
+            sig[marker] = -1 if sign.startswith(('-', 'lo', 'low')) else 1
+        if name and sig:
+            table[name] = sig
+    return table
+
+
+def annotate_by_reference(states, table, min_score=1):
+    """Assign each population the best-matching cell type from ``table``.
+
+    Scoring weights the *defining* (positive) markers: a matched required-
+    positive marker is worth +2, a matched required-negative +1, and a
+    contradiction (the population has the opposite sign) −2. A cell type is only
+    eligible if at least one of its positive markers is present in the
+    population (so a type can't win on a shared negative like ``CD3-`` alone).
+    Returns ``{population: {name, score, n_match, n_required}}``; ``name`` is
+    ``'unknown'`` when no eligible type scores ≥ ``min_score``. ``states`` comes
+    from :func:`population_states`."""
+    out = {}
+    for pop, st in states.items():
+        best = ('unknown', 0, 0, 0)
+        for name, sig in table.items():
+            pos = [m for m, w in sig.items() if w == 1]
+            score = 0
+            n_match = 0
+            pos_hit = 0
+            for marker, want in sig.items():
+                have = st.get(marker, 0)
+                if have == want:
+                    n_match += 1
+                    score += 2 if want == 1 else 1
+                    pos_hit += (want == 1)
+                elif have == -want:
+                    score -= 2
+            # A type with positive requirements must hit at least one of them.
+            if pos and pos_hit == 0:
+                continue
+            if score > best[1]:
+                best = (name, score, n_match, len(sig))
+        name, score, n_match, n_req = best
+        out[pop] = {'name': name if score >= min_score else 'unknown',
+                    'score': int(score), 'n_match': int(n_match),
+                    'n_required': int(n_req)}
+    return out

openflo/async_task.py

@@ -0,0 +1,78 @@
+"""Run a blocking job off the Tk thread and marshal the result back.
+
+A single helper that replaces the ad-hoc ``threading.Thread(target=work).start()``
++ ``self.after(0, lambda: …)`` pattern scattered across the editor and its
+dialogs. The work runs on a daemon thread; ``on_done`` / ``on_error`` /
+``on_finally`` are delivered on the Tk event loop via ``widget.after``, so they
+can safely touch widgets. ``widget`` only needs an ``after(ms, fn)`` method.
+
+Why a free function (not just a mixin method): the editor uses it through a
+``ComputeMixin.run_async`` wrapper that also drives the busy bar, but the
+standalone tool windows (ui_voltage / ui_synth / ui_compare / ui_statistics …)
+are plain ``tk.Toplevel`` subclasses with no access to that mixin — they call
+this directly.
+"""
+from __future__ import annotations
+
+import threading
+
+
+def run_async(widget, work, on_done=None, on_error=None, on_finally=None):
+    """Run ``work()`` on a daemon thread; deliver its return value to
+    ``on_done(result)`` — or any exception to ``on_error(exc)`` — back on
+    ``widget``'s Tk thread. ``on_finally()`` always runs last on the Tk thread
+    (use it to stop a spinner). Returns the started ``Thread``.
+
+    All callbacks are optional and best-effort: if the widget is gone (window
+    closed mid-run) the ``after`` call is swallowed rather than raising on the
+    worker thread."""
+    def _worker():
+        try:
+            result = work()
+        except Exception as exc:                       # noqa: BLE001
+            def _fail(e=exc):
+                # The window may have been closed while we computed: its `after`
+                # callback can still fire but its child widgets are gone, so
+                # touching them raises a stale-command TclError. Skip the
+                # callbacks entirely if the widget no longer exists.
+                if not _alive(widget):
+                    return
+                try:
+                    if on_error is not None:
+                        on_error(e)
+                finally:
+                    if on_finally is not None:
+                        on_finally()
+            _post(widget, _fail)
+            return
+
+        def _ok(r=result):
+            if not _alive(widget):
+                return
+            try:
+                if on_done is not None:
+                    on_done(r)
+            finally:
+                if on_finally is not None:
+                    on_finally()
+        _post(widget, _ok)
+
+    t = threading.Thread(target=_worker, daemon=True)
+    t.start()
+    return t
+
+
+def _alive(widget):
+    """True if the widget still exists (or doesn't expose winfo_exists)."""
+    try:
+        return bool(widget.winfo_exists())
+    except Exception:
+        return True
+
+
+def _post(widget, fn):
+    """Schedule ``fn`` on the widget's Tk thread; ignore a dead widget."""
+    try:
+        widget.after(0, fn)
+    except Exception:
+        pass