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_version
root-node attribute (see Root-level parameters). The version must be'0.4'
or greater. - Optionally load metadata from setup, sample, provenance and identity groups. This is not needed for the analysis. The fields may not be present.
- Same as in point 2 for root fields description and acquisition_duration.
- 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:
- 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
timestamps
and its unit (timestamps_specs/timestamps_unit
). If present, load alsodetectors
,nanotimes
andparticles
. Ifnanotimes
is present loadnanotime_specs
(tcspc_unit
andtcspc_num_bins
). - Load measurements-specs. Refer to Measurement specs
documentation for details. Note that
measurement_specs
may not be present. - If
measurement_specs
is present and the measurement-type starts withsmFRET
load detectors definitions (donor:measurement_specs/detectors_specs/spectral_ch1
, acceptor:measurement_specs/detectors_specs/spectral_ch2
). - For μs-ALEX load
alex_period
, and for ns-ALEX loadlaser_repetition_rate
. - For both μs-ALEX and ns-ALEX, load the donor and acceptor
period definitions (
alex_excitation_period1
andalex_excitation_period1
). For μs-ALEX also loadalex_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).