PEP: Per-pixel TCSPC info

[tritemio]

This is a Photon-HDF5 Enhancement Proposal (PEP).
This proposal builds upon PEP #33 (i.e. PEP #33 is required).

Summary

Currently, the TCSPC information (bins duration, number of bins) are fields in nanotimes_specs. The idea is that these are properties of the nanotimes array in the same way the timestamps_unit is a property of the timestamps array. However, in the case in which each detector has a separate TCSPC acquisition chain these properties (e.g. TCSPC bin with) could be different. This can happen in multichannel TCSPC hardware used with SPAD arrays, or when a separate discrete TACs are used for each detector. Admittedly, this is not a very common situation but we have encountered it in our setups.

We need a way to save TCSPC info on a per pixel/detector basis.

Proposal

According to PEP #33, we need a way to save some per pixel (or per detector) parameter. PEP proposes to add detectors groups to the setup group for the purpose.
We can add the per-pixel TCSPC info in the detectors groups as well, but only in case it is different between detectors in the same spot.

Reading a file would work as follow. The user check if there is a nanotimes array. If there is it checks if there is a nanotimes_specs group with the TCSPC info. Currently this group is mandatory for a file which contains nanotimes. With this proposal we will keep this group mandatory in all cases where all detectors included the nanotimes array have the same TCSPC parameters (so for the common case nothing changes).

But in cases where different detectors in the same nanotimes array have different TCSPC parameters (e.g. different TCSPC bin width) then we mandate that the nanotimes_specs group to be absent (so a user cannot accidentally load bogus data) and the per-pixel TCSPC info will be placed inside the detectors group (and having this TCSPC info is mandatory).

The names of the nanotimes_specs fields will not change, they will just be moved to the detectors group and only in this specific corner-case when TCSPC parameters are different across detectors.

detectors/
    counts
    ...
    nanotimes_specs/
        tcspc_unit: (array of float) array of TAC/TDC bin size (in seconds).
        tcspc_num_bins: (array of integers) array of number of TAC/TDC bins.

If accepted, this will be part of Photon-HDF5 0.5.

[tritemio]

As always comments are accepted from anybody interested in the Photon-HDF5 format.

[tritemio]

Since /setup/detectors contains arrays (one element per pixel) the nanotimes_specs will not be scalar anymore but arrays. I also propose putting the two fields directly in /setup:

detectors/
    counts
    ...
    tcspc_unit: (array of float) array of TAC/TDC bin size (in seconds).
    tcspc_num_bins: (array of integers) array of number of TAC/TDC bins.

[tritemio]

This feature is now documented in the 0.5 specification draft:

• http://photon-hdf5.readthedocs.io/en/0.5.dev/phdata.html#detectors-group

and supported by phconvert ( dev branch).

[tritemio]

• Add /setup/detectors/nanotimes_specs/ to the documentation
• Support /setup/detectors/nanotimes_specs/ in phconvert