Module loader#

This module contains functions to load each supported data format. Each loader function loads data from a third-party formats into a python dictionary which has the structure of a Photon-HDF5 file. These dictionaries can be passed to phconvert.hdf5.save_photon_hdf5() to save the data in Photon-HDF5 format.

The loader module contains high-level functions which “fill” the dictionary with the appropriate arrays. The actual decoding of the input binary files is performed by low-level functions in other modules (smreader.py, pqreader.py, bhreader.py). When trying to decode a new file format, these modules can provide useful examples.

phconvert.loader.loadfile_bh(filename, setfilename=None, spc_model='infer', SPC_type='auto')#

Load .spc (Beckr & Hickl) file as dictionary for saving with hdf5.save_photon_hdf5(). Any field that cannot be infered from data or metadata necessary for saving is given as a key with value of None. All None valued fields must be replaced with appropriate value before saving. For detectors fields that cannot be infered, all detectors are assigned to photon_data(X)/measurement_specs/detectors_specs/spectral_polarization_split_chN, this element should be removed from the dictioanry, and each index within assigned to the appropriate spectral_chX, polarization_chX or split_chX array.

Parameters:

  • filename (str) – Name of file, must end in .spc/.SPC.

  • setfilename (str, optional) – Name of cooresponding .set file, if not specified, infer name of set filename from filename. The default is None.

  • SPC_type (str, optional) –

    Identifier for card type, use only if your card is newer than phconvert. Options are:

    • ’SPC-1XX’ for SPC-1XX and SPC-8XX cards (this is the most common format)

    • ’SPC-6XX-48bit’ for SPC-6XX cards with 12 bit TCSPC resolution (most common for these cards)

    • ’SPC-6XX-32bit’for SPC-6XX cards with 8 bit TCSPC resolution (most common for these cards)

    • ’QC-X04’ for SPC-QC-X04 cards

    • ’QC-X06’for SPC-QC-X06 cards

  • spc_model (str, optional) – Deprecated use SPC_type intead. Originally used to determine bit layout of .spc file. Now read_set can determine layout of .spc file automatically. New cards may come out that will confuse this function however, thus, if you have a newer card that supported by phconvert, but still uses a supported .spc format, use SPC_type argument.

Raises:

FileNotFoundError – One or both file and/or setfile names provided do not exist on system.

Returns:

  • data (dict) – Dictionary of fields relevant to photon-HDF5.

  • metadata (dict) – Metadata from set file with information not pertinent to photon-HDF5, data should be saved in /user/becker_hickl group.

phconvert.loader.loadfile_ptu(filename: str)#

Load a .ptu (picoquant) file as dictionary for saving with hdf5.save_photon_hdf5(). Any field that cannot be infered from data or metadata necessary for saving is given as a key with value of None. All None valued fields must be replaced with appropriate value before saving. For detectors fields that cannot be infered, all detectors are assigned to photon_data(X)/measurement_specs/detectors_specs/spectral_polarization_split_chN, this element should be removed from the dictioanry, and each index within assigned to the appropriate spectral_chX, polarization_chX or split_chX array.

Parameters:

filename (str) – Name of ptu file to load.

Raises:

FileNotFoundError – Given filename does not exist on the system.

Returns:

  • data (dict) – Dictionary with identical structure to photon-HDF5 format, with all fields that can be infered from the metadata completed. Required fields that cannot be infered are incldued with their values set to None.

  • metadata (dict) – Metadata read from picoquant header.

phconvert.loader.loadfile_sm(filename, software='LabVIEW Data Acquisition usALEX', warn=False, print_warning=True)#

Load .sm file filling in all fields that can be filled from metadata in LabVIEW acquired usALEX data file.

Parameters:

  • filename (str) – Name of file to be converted.

  • software (str, optional) – Description of software that was used to acuire the data. The default is ‘LabVIEW Data Acquisition usALEX’.

  • warn (bool, optional) – Whether or not to warn if there are potential problems in the data. The default is False.

  • print_warning (TYPE, optional) – DESCRIPTION. The default is True.

Raises:

FileNotFoundError – Given filename does not exist on the system.

Returns:

data – Dictionary of data, with unknown but necessary values provided as keys with value of None. Once None values are replaced with appropriate values data can be passed to hdf5.save_photon_hdf5().

Return type:

dict

phconvert.loader.nsalex_bh(filename_spc: str, donor=4, acceptor=6, alex_period_donor=(10, 1500), alex_period_acceptor=(2000, 3500), excitation_wavelengths=(5.32e-07, 6.35e-07), detection_wavelengths=(5.8e-07, 6.8e-07), allow_missing_set=False, tcspc_num_bins=None, tcspc_unit=None, filename_set: None | str = None)#

Load a .spc and (optionally) .set files for ns-ALEX and return 2 dict.

The first dictionary can be passed to the phconvert.hdf5.save_photon_hdf5() function to save the data in Photon-HDF5 format.

Returns:

the first contains the main photon data (timestamps, detectors, nanotime, …); the second contains the raw data from the .set file (it can be saved in a user group in Photon-HDF5).

Return type:

Two dictionaries

phconvert.loader.nsalex_ht3(filename, donor=0, acceptor=1, alex_period_donor=(150, 1500), alex_period_acceptor=(1540, 3050), excitation_wavelengths=(5.23e-07, 6.28e-07), detection_wavelengths=(5.8e-07, 6.8e-07))#

Load a .ht3 file containing ns-ALEX data and return a dict.

WARNING: This function is deprecated. Please use nsalex_pq() instead.

phconvert.loader.nsalex_pq(filename, donor=0, acceptor=1, alex_period_donor=(150, 1500), alex_period_acceptor=(1540, 3050), excitation_wavelengths=(5.23e-07, 6.28e-07), detection_wavelengths=(5.8e-07, 6.8e-07))#

Load PicoQuant PTU, HT3 or PT3 files containing ns-ALEX data.

This function returns a dictionary that can be passed to phconvert.hdf5.save_photon_hdf5() to save a Photon-HDF5 file.

phconvert.loader.nsalex_pt3(filename, donor=0, acceptor=1, alex_period_donor=(150, 1500), alex_period_acceptor=(1540, 3050), excitation_wavelengths=(5.23e-07, 6.28e-07), detection_wavelengths=(5.8e-07, 6.8e-07))#

Load a .pt3 file containing ns-ALEX data and return a dict.

WARNING: This function is deprecated. Please use nsalex_pq() instead.

phconvert.loader.nsalex_t3r(filename, donor=0, acceptor=1, alex_period_donor=(150, 1500), alex_period_acceptor=(1540, 3050), excitation_wavelengths=(5.23e-07, 6.28e-07), detection_wavelengths=(5.8e-07, 6.8e-07))#

Load a .t3r file containing ns-ALEX data and return a dict.

This dictionary can be passed to the phconvert.hdf5.save_photon_hdf5() function to save the data in Photon-HDF5 format.

phconvert.loader.usalex_sm(filename, donor=0, acceptor=1, alex_period=4000, alex_offset=750, alex_period_donor=(2850, 580), alex_period_acceptor=(930, 2580), excitation_wavelengths=(5.32e-07, 6.35e-07), detection_wavelengths=(5.8e-07, 6.8e-07), software='LabVIEW Data Acquisition usALEX')#

Load a .sm us-ALEX file and returns a dictionary.

This dictionary can be passed to the phconvert.hdf5.save_photon_hdf5() function to save the data in Photon-HDF5 format.