TFADS-Analysis

TFADS-Analysis is a Python desktop application for TFADS peak analysis with a best-practice v2 detector and an interactive workflow for timeline inspection and gating.

What It Does

• Loads multi-channel PMT traces from csv, tsv, xls/xlsx, fcs, h5/hdf5, tdms, and binary sources.
• Detects peaks with prominence + minimum spacing logic (scipy.signal.find_peaks) and robust boundary extraction.
• Computes v2 metrics: height, width, area, prominence, peak/base/boundary indices.
• Supports arbitrary channel counts with independent trace display and shared analysis controls.
• Provides primary and secondary gating views.
• Adds inclusive time-window gating from the timeline.
• Supports timeline time scaling (time_scale) for datasets with known export timing bugs.
• Exports selected peaks to CSV/Excel with v2 reproducibility metadata columns.
• Converts loaded Excel traces to FCS 3.0, with an optional source-folder prompt on ingest and a later raw-data export action.
• Saves/loads sessions (thresholds, gates, time-scale, display settings).

Current UI Features

• Interactive timeline with pan/zoom
• Wheel zoom modes:
  • wheel = X zoom
  • Shift + wheel = Y zoom
  • Ctrl + Shift + wheel = X+Y zoom
• Manual and auto Y-axis range controls
• Channel display controls:
  • show/hide per channel
  • draw order
  • color picker
  • opacity
• Time-gate regions (inclusive) for downstream gating/export
• Load-time QC summary for finite values, constant channels, duration, and shape
• Sortable Peak Table linked to the focused timeline peak and scatter point
• Cooperative analysis cancellation with per-channel progress reporting
• Detector presets (Sensitive/Balanced/Conservative) with configurable width relative height
• Atomic session saves with a recoverable backup and a last-autosave restore action

Installation

Option 1: Local Development (recommended)

python -m venv .venv

Windows PowerShell:

.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Windows CMD:

.venv\Scripts\activate.bat
pip install -e ".[dev]"

Linux/macOS:

source .venv/bin/activate
pip install -e ".[dev]"

Option 2: Windows helper script

setup.bat

Run the App

tfads

or

python -m tfads.app

Basic Usage

1. Open a data file.
2. When opening an .xlsx/.xls, optionally save an FCS 3.0 copy beside it.
3. Choose a detector preset and adjust threshold/prominence, minimum spacing, and width relative height.
4. Run analysis.
5. Review the load-time QC summary, then draw/update gates in scatter plots.
6. Select any row in the Peak Table to focus that peak across the timeline and scatter view.
7. Add timeline time gates if needed; use Cancel Analysis if a long run needs to stop.
8. Export selected peaks or the raw trace as FCS later from the File menu; exports include detector configuration metadata.

Programmatic API

from tfads import load_data, detect_peaks, apply_gates, export_results

data = load_data("path/to/file.csv", fs=10_000_000)
peaks = detect_peaks(data["data"], data["fs"])
masks = apply_gates(peaks)
export_results(peaks, masks, fs=data["fs"], output_path="peaks.csv")

# Optional raw-trace FCS export (channels x samples)
from tfads import write_fcs

write_fcs(data["data"], "trace.fcs", fs=data["fs"], source_name="trace.xlsx")

v2 Export Schema

export_results(...) now writes a stable v2 table schema including:

• Core metrics: height_V, width_ms, area_Vms, prominence_V
• Indices: peak_index, start_index, end_index, left_base_index, right_base_index
• Selection + reproducibility: selected, detector_preset, processing_version

Legacy inputs (amplitude, area) are still accepted and mapped into v2 columns.

Validation and Quality Checks

ruff check tfads tests
black --check tfads tests
pytest -q
python ci/validate_labview_match.py

Example-data parity report:

python ci/validate_example_match.py

Build Windows Executable

powershell -ExecutionPolicy Bypass -File scripts/build_windows_exe.ps1

Output:

• dist/TFADS-Analysis.exe

Repository Hygiene Notes

• Large example datasets are intentionally not tracked in git (/Example_data is ignored).
• Local build/test artifacts are ignored (dist/, build/, caches, coverage files).
• Machine-local scratch/debug artifacts are ignored.

Attribution and Citation

If this project supports your work, please cite:

1. The original TFADS LabVIEW pipeline authors (TFADS Team / original method authors).
2. This Python desktop implementation by Matteo Broketa.

Citation metadata is provided in CITATION.cff.

License

MIT. See LICENSE.