3. Reading Photon-HDF5 files

You can easily read a Photon-HDF5 file in Python, MATLAB, LabVIEW or any other language that supports HDF5 (C, C++, Java, R, etc...). Photon-HDF5 files, like any other HDF5 file, are read using the HDF5 library for the language of choice. One specific advantage is that all field names (and their meaning) are defined in the specifications (Photon-HDF5 format definition).

To read Photon-HDF5 in a given programming language, the user only needs to install the HDF5 library and a wrapper for that language. Scientific Python distributions and MATLAB already include all the needed software support. In the case of Python, both pytables or h5py can be used. In the case of MATLAB, we suggest using 2013a or later, which include more user-friendly functions to access HDF5 files. LabVIEW users need to install the HDF5 library (www.hdfgroup.org) and a third-party wrapper to support HDF5 file reading or writing. h5labview is currently our recommended HDF5 wrapper for LabVIEW.

Simple examples on reading Photon-HDF5 files can be found in the paper describing Photon-HDF5 (section SM.2). Complete code example on reading Photon-HDF5 files in different programming languages (currently Python, MATLAB and LabVIEW) are provided on GitHub.

In the next section we discuss how to implement a generic Photon-HDF5 reader for a single-molecule FRET analysis program.

3.1. Reading Photon-HDF5 in a smFRET analysis program

This section describes an example of how to add support for reading Photon-HDF5 files to a smFRET analysis program. This scheme is implemented in the burst analysis program FRETBursts (see code for full details).

  1. Get the Photon-HDF5 version from format_version root-node attribute (see Root-level parameters). The version must be '0.4' or greater.
  2. Optionally, load metadata from setup, sample, provenance and identity groups. This is not needed for the analysis. These fields (i.e. the groups) may not be present. Even though complete Photon-HDF5 files will contain these groups, it is advisable that you write reader programs to be robust against missing metadata groups. For example detector dark-counts files we generated don’t have a setup group as it it irrelevant in this situation.
  3. Do the same as in point 2 for root fields description and acquisition_duration. These two fields should always be present though.
  4. If there is a /photon_data group the file is single-spot. Call the function to load single-spot data (see next section). If there is no /photon_data the file is a multi-spot one, call the multi-spot read function (next section).

3.1.1. Read single-spot function

Make a function that takes a channel parameter (N) and reads the data of the corresponding channel (/photon_dataN). If N is not passed, the function reads data from /photon_data.

Read the photon-data following these steps:

  1. Check if a photon-data group with given N is present, if not skip the channel. This is needed in cases of missing channels (e.g. dead pixel in SPAD array).
  2. Load photon-data arrays. Load the array timestamps and its unit (timestamps_specs/timestamps_unit). If present, load also detectors, nanotimes and particles. If nanotimes is present load nanotime_specs (tcspc_unit and tcspc_num_bins).
  3. Load measurements-specs. Refer to Measurement specs documentation for details. Note that measurement_specs may not be present.
  4. If measurement_specs is present and the measurement-type starts with smFRET load detectors definitions (donor: measurement_specs/detectors_specs/spectral_ch1, acceptor: measurement_specs/detectors_specs/spectral_ch2).
  5. For μs-ALEX load alex_period, and for ns-ALEX load laser_repetition_rate.
  6. For both μs-ALEX and ns-ALEX, load the donor and acceptor period definitions (alex_excitation_period1 and alex_excitation_period1). For μs-ALEX also load alex_offset. All these field may not be present.

3.1.2. Read multi-spot function

Implement the single-channel version then:

  • Find all the root groups starting with photon_data and for each group load the data for that channel. There can be missing channels (e.g. if there are dead pixels).