Module pqreader

This module contains functions to load and decode files from PicoQuant hardware.

The three main functions to decode PTU, HT3 adn PT3 files are respectively:

These functions return the arrays timestamps, detectors, nanotimes and an additional metadata dict.

Other lower level functions are:

  • ptu_reader() which loads metadata and raw t3 records from PTU files
  • ht3_reader() which loads metadata and raw t3 records from HT3 files
  • pt3_reader() which loads metadata and raw t3 records from PT3 files
  • process_t3records() which decodes the t3 records returning timestamps (after overflow correction), detectors and TCSPC nanotimes.

Note that the functions performing overflow/rollover correction can take advantage of numba, if installed, to significanly speed-up the processing.

List of functions

High-level functions to load and decode several PicoQuant file formats:

phconvert.pqreader.load_ht3(filename, ovcfunc=None)

Load data from a PicoQuant .ht3 file.

Parameters:
  • filename (string) – the path of the HT3 file to be loaded.
  • ovcfunc (function or None) – function to use for overflow/rollover correction of timestamps. If None, it defaults to the fastest available implementation for the current machine.
Returns:

A tuple of timestamps, detectors, nanotimes (integer arrays) and a dictionary with metadata containing at least the keys ‘timestamps_unit’ and ‘nanotimes_unit’.

phconvert.pqreader.load_pt3(filename, ovcfunc=None)

Load data from a PicoQuant .pt3 file.

Parameters:
  • filename (string) – the path of the PT3 file to be loaded.
  • ovcfunc (function or None) – function to use for overflow/rollover correction of timestamps. If None, it defaults to the fastest available implementation for the current machine.
Returns:

A tuple of timestamps, detectors, nanotimes (integer arrays) and a dictionary with metadata containing at least the keys ‘timestamps_unit’ and ‘nanotimes_unit’.

Low-level functions

These functions are the building blocks for loading and decoding the different files:

phconvert.pqreader.ht3_reader(filename)

Load raw t3 records and metadata from an HT3 file.

phconvert.pqreader.pt3_reader(filename)

Load raw t3 records and metadata from a PT3 file.

phconvert.pqreader.process_t3records(t3records, time_bit=10, dtime_bit=15, ch_bit=6, special_bit=True, ovcfunc=None)

Extract the different fields from the raw t3records array.

The input array of t3records is an array of “records” (a C struct). It packs all the information of each detected photons. This function decodes the different fields and returns 3 arrays containing the timestamps (i.e. macro-time or number of sync, ns resolution), the nanotimes (i.e. the micro-time or TCSPC time, ps resolution) and the detectors.

Assuming the t3records are in little-endian order, the fields are assumed in the following order:

| Optional special bit | detectors | nanotimes | timestamps |
  MSB                                                   LSB
  • the lowest time_bit bits contain the timestamps
  • the next dtime_bit bits contain the nanotimes
  • the next ch_bit contain the detector number
  • if special_bit = True, the highest bit is the special bit.

The returned timestamps are overflow-corrected, and therefore should be monotonically increasing. Each overflow event is marked by a special detector (or a special bit) and this information is used for the correction. These overflow “events” are not removed in the returned arrays resulting in spurious detectors. This choice has been made for safety (you can always go and check where there was an overflow) and for efficiency (removing a few elements requires allocating a new array that is potentially expensive for big data files). Under normal usage the additional detectors take negligible space and can be safely ignored.

Parameters:
  • t3records (array) – raw array of t3records as saved in the PicoQuant file.
  • time_bit (int) – number of bits in the t3record used for timestamps (or macro-time).
  • dtime_bit (int) – number of bits in the t3record used for the nanotime (TCSPC time or micro-time)
  • ch_bit (int) – number of bits in the t3record used for the detector number.
  • special_bit (bool) – if True the t3record contains a special bit for overflow correction. This special bit will become the MSB in the returned detectors array. If False, it assumes no special bit in the t3record.
  • ovcfunc (function or None) – function to perform overflow correction of timestamps. If None use the default function. The default function is the numba-accelerated version is numba is installed otherwise it is function using plain numpy.
Returns:

A 3-element tuple containing the following 1D arrays (all of the same length):

  • timestamps (array of int64): the macro-time (or number of sync) of each photons after overflow correction. Units are specified in the file header.
  • nanotimes (array of uint16): the micro-time (TCSPC time), i.e. the time lag between the photon detection and the previous laser sync. Units (i.e. the bin width) are specified in the file header.
  • detectors (arrays of uint8): detector number. When special_bit = True the highest bit in detectors will be the special bit.