Metadata-Version: 2.2
Name: tttrlib
Version: 0.26.2
Summary: Read, write & process time-tagged time-resolved (TTTR) data.
Keywords: fluorescence,time-resolved,spectroscopy,imaging,microscopy
Author-Email: Thomas-Otavio Peulen <thomas.otavio.peulen@gmail.com>
License: BSD-3-Clause
Classifier: Topic :: Software Development
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Project-URL: homepage, https://github.com/fluorescence-tools/tttrlib
Project-URL: documentation, https://docs.peulen.xyz/tttrlib
Project-URL: repository, https://github.com/fluorescence-tools/tttrlib.git
Requires-Python: >=3.9
Requires-Dist: numpy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: scipy; extra == "test"
Requires-Dist: pooch>=1.8.0; extra == "test"
Provides-Extra: examples
Requires-Dist: matplotlib; extra == "examples"
Requires-Dist: scikit-image; extra == "examples"
Requires-Dist: click; extra == "examples"
Requires-Dist: click-didyoumean; extra == "examples"
Requires-Dist: tqdm; extra == "examples"
Description-Content-Type: text/markdown

# tttrlib

[![Anaconda](https://anaconda.org/tpeulen/tttrlib/badges/version.svg)](https://anaconda.org/tpeulen/tttrlib)
[![PyPI](https://badge.fury.io/py/tttrlib.svg)](https://pypi.org/project/tttrlib/)
[![CI](https://github.com/Fluorescence-Tools/tttrlib/actions/workflows/ci.yml/badge.svg)](https://github.com/Fluorescence-Tools/tttrlib/actions/workflows/ci.yml)

---

## General description
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.

![tttrlib FLIM][3]

### Key Features

* 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.


## Installation

### pip (recommended)

```bash
pip install tttrlib
```

Pre-built wheels are available on [PyPI](https://pypi.org/project/tttrlib/) for
**Linux** (x86_64), **macOS** (arm64, x86_64), and **Windows** (x86_64)
across Python 3.9–3.13.

### Conda / Mamba

**macOS / Linux** (via [bioconda](https://bioconda.github.io/recipes/tttrlib/README.html))

```bash
mamba install -c conda-forge -c bioconda tttrlib
```

**Windows** (via [tpeulen](https://anaconda.org/tpeulen/tttrlib))

```bash
mamba install -c tpeulen tttrlib
```

We recommend [**Miniforge**](https://github.com/conda-forge/miniforge) with the
fast **mamba** solver.

### From Source

```bash
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.

---

## Usage

See [**docs.peulen.xyz/tttrlib**](https://docs.peulen.xyz/tttrlib) for the full API and tutorials.
Below are minimal examples.

Detailed build instructions for developers are available in [BUILDING.md](BUILDING.md).

### Read TTTR data

```python
import tttrlib
data = tttrlib.TTTR("photon_stream.ptu")

macro = data.macro_times
micro = data.micro_times
routing = data.routing_channels
```

### Inspect header

```python
import tttrlib
fn = 'photon_stream.ptu'
data = tttrlib.TTTR(fn)
print(data.header.json)
print(data.header.to_csv())
```

### Cross-correlate photon streams

```python
import tttrlib
fn = 'photon_stream.ptu'
data = tttrlib.TTTR(fn)
correlator = tttrlib.Correlator(
    channels=([1], [2]),
    tttr=data
)
taus = correlator.x_axis,
correlation_amplitude = correlator.correlation
```

### Create intensity images (CLSM)

```python
import tttrlib
fn = '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

# Alternatively
clsm = tttrlib.CLSMImage(fn, fill=True)
intensity_image = clsm.intensity

```

### Minimal burst search

```python
import tttrlib
import numpy as np

fn = 'photon_stream.ptu'
tttr = tttrlib.TTTR(fn)

# Bust selection
L, 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.

## Supported File Formats

* **PicoQuant:** PicoHarp/TimeHarp/HydraHarp (`ptu`, `ht3`, T2/T3)
* **Becker & Hickl:** `spc132`, `spc630` (256 & 4096 mode)
* **Photon-HDF5:** open standard format

---

## Contributing

To add support for a new format / microscope:

1. Open a GitHub issue describing the format and instrument.
2. Share a small demo file (<100 MB) with expected results.
3. If relevant, document your workflow or analysis steps.

With this information, we can integrate and test the new format automatically.

---

## Design Goals

* 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

---

## Citation

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](https://doi.org/10.1093/bioinformatics/btaf025)

---

## License

Copyright 2007–2026 tttrlib developers
Licensed under the **BSD-3-Clause** license.

[3]: https://github.com/Fluorescence-Tools/tttrlib/blob/main/doc/logos/mashup.png?raw=true "tttrlib FLIM"

