Tether

A provenance-first desktop suite for single-molecule FRET (smFRET) analysis.

Tether is a cross-platform application for the Mondragón Lab (Northwestern University) that takes you from a raw TIRF movie to curated, corrected, idealized smFRET traces — without ever losing the link between a trace and the pixels it came from. Extraction, curation, corrections, idealization and analysis are all in the application today; the documentation site is the user manual.

Does Tether fit my data? Check supported inputs, acquisition geometry, scale and non-goals before you install.

Most smFRET pipelines discard provenance: once traces are extracted, you can no longer ask "which spot in which movie produced this trace, and exactly how was it corrected?" Tether is built the other way around — every datum carries its origin: coordinates, correction factors, parameters, and the app version are stamped into a single self-describing project file, and the trace ⇄ movie round-trip is a property of the data model, not a fragile convenience.

• Native extraction — faithful TIFF movie → trace extraction (channel split, à trous spot detection, polynomial registration, donor-anchored colocalization, aperture integration), validated against Deep-LASI.
• Round-trip browser — a PySide6 shell with an embedded napari movie panel and a fast pyqtgraph trace dock; click a trace → jump to its spot, click a spot → open its trace, across many movies.
• Curation — keyboard-driven accept/reject/categorize with full label provenance, feeding a per-condition, incrementally-retrained quality ranker (sort/rank only, never auto-drop).
• Corrections — native per-channel Bayesian photobleach detection → leakage α → γ → corrected FRET, with an apparent-E fallback that never emits a NaN.
• Idealization — one-click vbFRET / consensus VB-HMM / ebFRET via an isolated tMAVEN sidecar, plus a non-destructive hand-off to standalone tMAVEN.
• Analysis — histograms with CI, transition-density and dwell-time plots, the raw FRET cloud, and provenance-stamped exports.

Tether ships as one self-contained, offline installer per platform — a Windows .exe, a macOS .pkg and a Linux .sh — that bundles the application and its isolated tMAVEN sidecar. Follow Install Tether to download, verify, install, run and uninstall it.

The installers are not OS-code-signed, so expect a Windows SmartScreen or macOS Gatekeeper warning; the published SHA-256 manifests and build-provenance attestation are the integrity check instead (ADR-0059).

For development, restore the pinned base environment from the committed conda-lock.yml (never re-solve it) and install Tether into it without dependencies:

git clone https://github.com/bioedca/tether.git
cd tether
micromamba create -n tether -f conda-lock.yml
micromamba activate tether
pip install -e . --no-deps

Idealization needs the separate tMAVEN sidecar environment, which python scripts/setup_sidecar.py builds from sidecar/conda-lock.yml. CONTRIBUTING.md has the full setup.

The installer does not edit your PATH. It writes both launchers into <install-root>/bin/ (<install-root>\bin\ on Windows), and on Windows and Linux it also adds a Tether entry to the Start Menu or applications menu.

Open the desktop application from that menu entry, or run the window launcher:

<install-root>/bin/tether-gui        # Windows: <install-root>\bin\tether-gui.bat

To use the command line, add <install-root>/bin to the end of your PATH (on Linux and macOS it also holds the installer's own python, pip and conda, which should not shadow yours), check the install, and extract a dual-channel TIFF movie into a new project. Install Tether shows how to make the PATH change permanent.

export PATH="$PATH:<install-root>/bin"   # PowerShell: $env:PATH = "$env:PATH;<install-root>\bin"
tether --version
tether extract movie.tif -o project.tether

--donor-side (default left) must match which half of your frame carries the donor, and nothing warns you when it is wrong. The command-line reference covers that, every other flag, and tether batch.

• User manual: https://bioedca.github.io/tether/ — use the version selector to match your installed release.
• First run: Your first analysis — a guided tutorial on a sample movie, from extraction to an exported table.
• Installers: Packaging & installers and launching Tether after an install.
• Does Tether fit my data? — supported inputs, acquisition geometry, scale and non-goals.
• Architecture decisions: docs/adr/ (MADR format).
• Contributing: CONTRIBUTING.md — workflow, gates, schema-freeze rule, Conventional Commits.
• Product spec: docs/PRD.md — the §-numbered source of truth.

• Something went wrong? Check Troubleshooting first.
• A question? Ask in Discussions Q&A, or use the Question form under New issue.
• A bug or a docs gap? Open the matching form under New issue.
• A security problem? Never open a public issue; follow SECURITY.md to report it privately.

If you use Tether, please cite it with its Zenodo concept DOI, which always resolves to the newest archived version: 10.5281/zenodo.23306397. The same metadata is in CITATION.cff (GitHub's "Cite this repository" button).

The Citing Tether page lists which upstream papers to cite as well for each part of the pipeline you ran (idealization backend, corrections, deep classifier), and how to report the exact version that produced your data. Licensing credit for tMAVEN, Deep-LASI and MASH-FRET is in NOTICE.

Tether is free software licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE. GPL-3.0 is required to embed the tMAVEN sidecar; Tether itself is never linked into proprietary code.