tttrlib is a file format agnostic high performance library to read, process, and write time-tagged-time resolved (TTTR) data acquired by PicoQuant (PQ) and Becker & Hickl measurement devices/cards or TTTR files in the open Photon-HDF format.
tttrlib is a high-performance, file-format-agnostic library to read, process, and write time-tagged time-resolved (TTTR) data from PicoQuant, Becker & Hickl, and Photon-HDF5 files.
Written in C++ with Python bindings, it provides a fast, vendor-independent API for handling photon streams and enables integration into advanced data analysis pipelines for time-resolved fluorescence spectroscopy and imaging.
- Fast TTTR file reading (IO-limited)
- Multi-dimensional histogramming
- Correlation analysis
- Fluorescence decay generation and analysis
- Photon distribution (FIDA/PCH)
- Burst and time-window selection
- FLIM and ISM image generation
- Experimental ISM tools (Adaptive Pixel Reassignment, Focus-ISM background rejection)
tttrlib typically outperforms pure Python implementations by
~40× in decay histogramming and ~2–5× in burst selection.
pip install tttrlibPre-built wheels are available on PyPI for Linux (x86_64), macOS (arm64, x86_64), and Windows (x86_64) across Python 3.9–3.13.
macOS / Linux (via bioconda)
mamba install -c conda-forge -c bioconda tttrlibWindows (via tpeulen)
mamba install -c tpeulen tttrlibWe recommend Miniforge with the fast mamba solver.
git clone https://github.com/fluorescence-tools/tttrlib.git
cd tttrlib
pip install -e .Pre-compiled packages are available for Windows, Linux (x86_64), and macOS (arm64, x86_64). Legacy 32-bit and Python 2.7 are not supported.
See docs.peulen.xyz/tttrlib for the full API and tutorials. Below are minimal examples.
Detailed build instructions for developers are available in BUILDING.md.
importtttrlibdata=tttrlib.TTTR("photon_stream.ptu")
macro=data.macro_timesmicro=data.micro_timesrouting=data.routing_channelsimporttttrlibfn='photon_stream.ptu'data=tttrlib.TTTR(fn)
print(data.header.json)
print(data.header.to_csv())importtttrlibfn='photon_stream.ptu'data=tttrlib.TTTR(fn)
correlator=tttrlib.Correlator(
channels=([1], [2]),
tttr=data
)
taus=correlator.x_axis,
correlation_amplitude=correlator.correlationimporttttrlibfn='image.ptu'data=tttrlib.TTTR(fn)
clsm=tttrlib.CLSMImage(data)
channels= [0, 1]
prompt_range= [0, 16000]
clsm.fill(channels=channels, micro_time_ranges=[prompt_range])
intensity_image=clsm.intensity# Alternativelyclsm=tttrlib.CLSMImage(fn, fill=True)
intensity_image=clsm.intensityimporttttrlibimportnumpyasnpfn='photon_stream.ptu'tttr=tttrlib.TTTR(fn)
# Bust selectionL, m, T=30, 10, 1e-3# min photons, window photons, window time [s]ranges=tttr.burst_search(L=L, m=m, T=T) # flat [start, stop, start, stop, ...]bursts=list(zip(ranges[0::2], ranges[1::2]))For PIE/ALEX data, add micro-time gating before burst search; see the tutorial for donor/acceptor prompt examples. For details, parameters, and plotting examples, see the Burst Analysis tutorial.
- PicoQuant: PicoHarp/TimeHarp/HydraHarp (
ptu,ht3, T2/T3) - Becker & Hickl:
spc132,spc630(256 & 4096 mode) - Photon-HDF5: open standard format
To add support for a new format / microscope:
- Open a GitHub issue describing the format and instrument.
- Share a small demo file (<100 MB) with expected results.
- If relevant, document your workflow or analysis steps.
With this information, we can integrate and test the new format automatically.
- Low memory footprint for large datasets (e.g. FLIM)
- Cross-platform C/C++ library with SWIG bindings (Python, C#, Java, etc.)
- Modular and extendable design for fluorescence spectroscopy and imaging
If you use this software, please cite:
Thomas-Otavio Peulen, Katherina Hemmen, Annemarie Greife, Benjamin M. Webb, Suren Felekyan, Andrej Sali, Claus A. M. Seidel, Hugo Sanabria, Katrin G. Heinze. “tttrlib: modular software for integrating fluorescence spectroscopy, imaging, and molecular modeling.”Bioinformatics 41 (2): btaf025 (2025). https://doi.org/10.1093/bioinformatics/btaf025
Copyright 2007–2026 tttrlib developers Licensed under the BSD-3-Clause license.