pyfli.io.detector#

Coordinate detector-specific loading workflows for SS2, SS3, ICCD, TCSPC, and generic data.

This module belongs to pyfli.io and is part of PyFLI detector importers, file readers, saving helpers, and processed-data loaders. Public API includes classes Detector.

Classes

Detector([data_path, irf_path, bg_path, ...])

Provide detector-specific loading workflows for PyFLI experiments.
class Detector(data_path=None, irf_path=None, bg_path=None, mask_path=None, hp_path=None, bit_size=10)[source]#

Bases: object

Provide detector-specific loading workflows for PyFLI experiments. Use this high- level loader for SS3, SS2, ICCD, BH TCSPC, and generic data sources with optional background subtraction, pile-up correction, masks, and hot-pixel handling.

Parameters:

  • data_path (str | None) – Path to the primary decay data source.

  • irf_path (str | None) – Path to the instrument response data source.

  • bg_path (str | None) – Path to the background measurement used for subtraction or correction.

  • mask_path (str | None) – Path to a binary or labeled mask used to select valid pixels.

  • hp_path (str | None) – Path to a hot-pixel mask or image used for interpolation.

  • bit_size (int) – Detector digitization bit depth used for pile-up correction.

SS3(name='Experiment_1', sub_bg=True, pile_up=True, hot_pixel=True, make_hp_map=True, threshold_sigma=5.0, config=None)[source]#

Load SwissSPAD3 HDF5 data.

Single-file input applies optional pile-up and folding. Folder input can also apply hot-pixel correction and background subtraction before file combination.

Parameters:

  • name (str) – Dataset or experiment name.

  • sub_bg (bool) – Whether to subtract background in folder mode.

  • pile_up (bool) – Whether to apply pile-up correction.

  • hot_pixel (bool) – Whether to apply hot-pixel correction in folder mode.

  • make_hp_map (bool) – Whether to derive the hot-pixel map from background data.

  • threshold_sigma (float) – MAD threshold used for automatic hot-pixel detection.

  • config (SpadConfig | dict[str, Any] | None) – SPAD loading and folding options.

Returns:

Standard PyFLI dataset package.

Return type:

Any

SS2(name='Experiment_1', sub_bg=True, pile_up=True, hot_pixel=True, make_hp_map=True, threshold_sigma=5.0, config=None)[source]#

Load SwissSPAD2 HDF5 or native BIN data.

HDF5 input uses Gate Images/Gate N. Native BIN input uses matched topN.bin and btmN.bin files. Single-acquisition input applies optional pile-up and folding. HDF5 folder input can also apply hot-pixel correction and background subtraction before file combination.

Parameters:

  • name (str) – Dataset or experiment name.

  • sub_bg (bool) – Whether to subtract background in HDF5 folder mode.

  • pile_up (bool) – Whether to apply pile-up correction.

  • hot_pixel (bool) – Whether to apply hot-pixel correction in HDF5 folder mode.

  • make_hp_map (bool) – Whether to derive the hot-pixel map from background data.

  • threshold_sigma (float) – MAD threshold used for automatic hot-pixel detection.

  • config (SpadConfig | dict[str, Any] | None) – SPAD loading, BIN, and folding options.

Returns:

Standard PyFLI dataset package.

Return type:

Any

SPAD(name='Experiment_1', config=None)[source]#

Generic SPAD detector loader for HDF5 and native SwissSPAD2 binary data.

HDF5 files are discovered from their structure, dimensions, attributes, and numeric ordering rather than fixed detector-specific group names. SwissSPAD2 binary acquisitions are decoded from matched topN.bin / btmN.bin chunks and stitched into a 512 x 512 detector cube.

Optional pile-up correction is applied before optional periodic temporal folding. Folding detects or uses an explicit circular phase shift, aligns the complete acquisition on the time axis, and sums repeated excitation periods. Background subtraction is not performed by this loader.

Parameters:

  • name (str) – Dataset or experiment name stored in the returned PyFLI package.

  • config (SpadConfig | dict[str, Any] | None) – SPAD input, pile-up, HDF5 discovery, SwissSPAD2 binary, and folding options.

Returns:

Standard PyFLI dataset package containing SPAD decay, optional IRF/background, mask, and complete import metadata.

Return type:

Any

ICCD(name='Experiment_1')[source]#

Intensified CCD detector.

Both data_path and irf_path must be folders of TIFF files. Each TIFF represents one gate position; files are sorted alphabetically and stacked along the time axis → (H, W, N_gates). IRF is pixel-variant: its shape must exactly match the data shape. No pile-up, hot-pixel, or background correction is applied.

Parameters:

name (str)

Return type:

Any

BH_TCSPC(name='Experiment_1', sub_bg=True, channel=0)[source]#

Time-Correlated Single Photon Counting detectors.

Supported formats: .sdt (Becker & Hickl), .ptu (PicoQuant), .asc, .mat, .npy, .tif

Pile-up correction is NOT applied. TCSPC pile-up follows a dead-time model C_true = C_meas / (1 − C_meas · τ_dead · f_rep) that is detector-dependent and must be applied externally when needed.

channel : SDT measurement block index for multi-block files (default 0).

Parameters:
Return type:

Any

generic(name='Experiment_1', sub_bg=True, pile_up=False, hot_pixel=False)[source]#

Generic loader: TIFF / NPY / MAT / TXT / HDF5. All corrections opt-in.

Parameters:
Return type:

Any