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).
- Get the Photon-HDF5 version from
format_versionroot-node attribute (see Root-level parameters). The version must be
- 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.
- Do the same as in point 2 for root fields description and acquisition_duration. These two fields should always be present though.
- If there is a
/photon_datagroup the file is single-spot. Call the function to load single-spot data (see next section). If there is no
/photon_datathe 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
Read the photon-data following these steps:
- 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).
- Load photon-data arrays. Load the array
timestampsand its unit (
timestamps_specs/timestamps_unit). If present, load also
nanotimesis present load
- Load measurements-specs. Refer to Measurement specs
documentation for details. Note that
measurement_specsmay not be present.
measurement_specsis present and the measurement-type starts with
smFRETload detectors definitions (donor:
- For μs-ALEX load
alex_period, and for ns-ALEX load
- For both μs-ALEX and ns-ALEX, load the donor and acceptor
period definitions (
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_dataand for each group load the data for that channel. There can be missing channels (e.g. if there are dead pixels).