Package: ptufile
Ptufile is a Python library to read image and metadata from PicoQuant PTU
and related files: PHU, PCK, PCO, PFS, PUS, and PQRES.
PTU files contain time correlated single photon counting (TCSPC)
measurement data and instrumentation parameters.Author:Christoph GohlkeLicense:BSD 3-ClauseVersion:2024.2.20DOI:10.5281/zenodo.10120021QuickstartInstall the ptufile package and all dependencies from thePython Package Index:python -m pip install -U ptufile[all]SeeExamplesfor using the programming interface.Source code and support are available onGitHub.RequirementsThis revision was tested with the following requirements and dependencies
(other versions may work):CPython3.9.13, 3.10.11, 3.11.8, 3.12.2 (64-bit)Numpy1.26.4Xarray2024.2.0 (recommended)Matplotlib3.8.3 (optional)Tifffile2024.2.12 (optional)Numcodecs0.12.1 (optional)Revisions2024.2.20Change definition of PtuFile.frequency (breaking).Add option to specify number of bins returned by decode_histogram.Add option to return histograms of one period.2024.2.15Add PtuFile.scanner property.Add numcodecs compatible PTU codec.2024.2.8Support sinusoidal scanning correction.2024.2.2Change positive dtime parameter from index to size (breaking).Fix segfault with ImgHdr_TimePerPixel = 0.Rename MultiHarp to Generic conforming with changes in PicoQuant reference.2023.11.16Fix empty line when first record is start marker.2023.11.13Change image histogram dimension order to TYXCH (breaking).Change frame start to start of first line in frame (breaking).Improve trimming of incomplete frames (breaking).Remove trim_dtime option (breaking).Fix selection handling in PtuFile.decode_image.Add option to trim T, C, and H axes of image histograms.Add option to decode histograms to memory-mapped or user-provided arrays.Add__getitem__interface to image histogram.2023.11.1Initial alpha release.NotesTheChan Zuckerberg Initiativefinancially supported the development of this library.PicoQuant GmbHis a manufacturer of photonic
components and instruments.The PicoQuant unified file formats are documented at thePicoQuant-Time-Tagged-File-Format-Demos.The following features are currently not implemented: PT2 and PT3 files,
decoding images from T2 formats, bidirectional scanning, and deprecated
image reconstruction.Other Python modules for reading PicoQuant files are:Read_PTU.pyreadPTU_FLIMPyPTUtttrlibpicoquantioptuparserphconverttrattoria(wrapper oftrattoria-coreandtttr-toolbox)napari-flim-phasor-plotterExamplesRead properties and tags from any type of PicoQuant unified tagged file:>>> pq = PqFile('tests/Settings.pfs')
>>> pq.magic
<PqFileMagic.PFS: ...>
>>> pq.guid
UUID('86d428e2-cb0b-4964-996c-04456ba6be7b')
>>> pq.tags
{...'CreatorSW_Name': 'SymPhoTime 64', 'CreatorSW_Version': '2.1'...}
>>> pq.close()Read metadata from a PicoQuant PTU FLIM file:>>> ptu = PtuFile('tests/FLIM.ptu')
>>> ptu.magic
<PqFileMagic.PTU: ...>
>>> ptu.type
<PtuRecordType.PicoHarpT3: 66307>
>>> ptu.measurement_mode
<PtuMeasurementMode.T3: 3>
>>> ptu.measurement_submode
<PtuMeasurementSubMode.IMAGE: 3>Decode TTTR records from the PTU file tonumpy.recarray.>>> decoded = ptu.decode_records()Get global times of frame changes from markers:>>> decoded['time'][(decoded['marker'] & ptu.frame_change_mask) > 0]
array([1571185680], dtype=uint64)Decode TTTR records to overall delay-time histograms per channel:>>> ptu.decode_histogram(dtype='uint8')
array([[ 5,  7,  7, ..., 10,  9,  2]], dtype=uint8)Get information about the FLIM image histogram in the PTU file:>>> ptu.shape
(1, 256, 256, 2, 3126)
>>> ptu.dims
('T', 'Y', 'X', 'C', 'H')
>>> ptu.coords
{'T': ..., 'Y': ..., 'X': ..., 'H': ...}
>>> ptu.dtype
dtype('uint16')Decode parts of the image histogram tonumpy.ndarrayusing slice notation.
Slice step sizes define binning, -1 being used to integrate along axis:>>> ptu[:, ..., 0, ::-1]
array([[[103, ..., 38],
              ...
        [ 47, ..., 30]]], dtype=uint16)Alternatively, decode the first channel and integrate all histogram bins
to axarray.DataArray, keeping reduced axes:>>> ptu.decode_image(channel=0, dtime=-1, asxarray=True)
<xarray.DataArray (T: 1, Y: 256, X: 256, C: 1, H: 1)> ...
array([[[[[103]],
           ...
         [[ 30]]]]], dtype=uint16)
Coordinates:
  * T        (T) float64... 0.05625
  * Y        (Y) float64... -0.0001304 ... 0.0001294
  * X        (X) float64... -0.0001304 ... 0.0001294
  * H        (H) float64... 0.0
Dimensions without coordinates: C
Attributes...
    frequency:      19999200.0
...
>>> ptu.close()Preview the image and metadata in a PTU file from the console:python -m ptufile tests/FLIM.ptu