daplis.functions.delta_t module

Module for calculating and plotting the timestamp differences.

This script utilizes an unpacking module used specifically for the LinoSPAD2 binary data output.

This file can also be imported as a module and contains the following functions:

• _flatten - flatten the input list into a single list of numbers.

The input list could contain any number of lists of numbers.

• _combine_intermediate_feather_files - combine ‘.feather’ files

into one. Used for combining the intermediate steps of saving the timestamp differences into a single file.

• calculate_and_save_timestamp_differences - unpacks the binary

data, calculates timestamp differences, and saves into a ‘.feather’ file.

• calculate_and_save_timestamp_differences_1v1 - unpacks the

binary data, calculates timestamp differences, and saves into a ‘.feather’ file. Uses a faster algorithm than the standard version. Calculated only for the diagonal pixels, i.e., 1-1, 2-2, etc., and not for all pairs.

• calculate_and_save_timestamp_differences_full_sensor - unpacks the

binary data, calculates timestamp differences and saves into a ‘.feather’ file. Works with firmware versions ‘2208’, ‘2212s’ and ‘2212b’. Analyzes data from both sensor halves/both FPGAs. Useful for data where the signal is at 0 across the whole sensor from the start of data collecting.

• calculate_and_save_timestamp_differences_full_sensor_alt - unpacks

the binary data, finds the constant board-to-board offset automatically from the absolute timestamps, calculates timestamp differences and saves into a ‘.feather’ file. Works with firmware versions ‘2212s’ and ‘2212b’. Analyzes data from both sensor halves/both FPGAs that share a common external clock but no common trigger. Useful for data where signal is above zero right from the start.

• collect_and_plot_timestamp_differences - collect timestamps from a

‘.feather’ file and plot them in a grid.

• collect_and_plot_timestamp_differences_full_sensor - collect

timestamps from a ‘.feather’ file and plot histograms of them in a grid. This function should be used for the full sensor setup.

• unpickle_plot - unpickle the ‘.pkl’ file with a delta_t histogram.

Can be used to presaved ‘.pkl’ files for fine control over the plot.

daplis.functions.delta_t.calculate_and_save_timestamp_differences(path: str, pixels: list[int] | list[list[int]], rewrite: bool, daughterboard_number: str, motherboard_number: str, firmware_version: str, timestamps: int = 512, delta_window: float = 50000.0, cycle_length: float | None = None, apply_mask: bool = True, include_offset: bool = False, apply_calibration: bool = True, absolute_timestamps: bool = False, correct_pix_address: bool = False)

Calculate and save timestamp differences into a ‘.feather’ file.

Unpacks data, computes timestamp differences for the requested pixels, and saves them into a ‘.feather’ table. Compatible with firmware versions 2212 and uses a faster algorithm.

Parameters:

• path (str) – Path to the folder containing ‘.dat’ data files.

• pixels (List[int] | List[List[int]]) – List of pixel numbers for which timestamp differences should be computed, or a list of two lists for peak-vs-peak calculations.

• rewrite (bool) – Switch for rewriting the ‘.feather’ file if it already exists. Used as a safeguard to avoid unwanted overwriting.

• daughterboard_number (str) – LinoSPAD2 daughterboard number.

• motherboard_number (str) – LinoSPAD2 motherboard (FPGA) number, including the ‘#’.

• firmware_version (str) – LinoSPAD2 firmware version. Versions ‘2212s’ (skip) and ‘2212b’ (block) are recognized.

• timestamps (int, optional) – Number of timestamps per acquisition cycle per pixel. The default is 512.

• delta_window (float, optional) – Width of the window in which timestamp differences are counted. The default is 50e3 (50 ns).

• cycle_length (float, optional) – Length of one acquisition cycle. The default is None.

• apply_mask (bool, optional) – Apply mask for hot pixels. The default is True.

• include_offset (bool, optional) – Apply offset calibration. The default is False.

• apply_calibration (bool, optional) – Apply TDC and offset calibration. If True while include_offset is False, only TDC calibration is applied. The default is True.

• absolute_timestamps (bool, optional) – Indicates whether the data contains absolute timestamps. The default is False.

• correct_pix_address (bool, optional) – Correct pixel addresses for the sensor half on side 23 of the daughterboard. The default is False.

Raises:

• TypeError – If pixels is not a list.

• TypeError – If firmware_version is not a string.

• TypeError – If rewrite is not a boolean.

• TypeError – If daughterboard_number is not a string.

daplis.functions.delta_t.calculate_and_save_timestamp_differences_1v1(path: str, pixels: list[int] | list[list[int]], rewrite: bool, daughterboard_number: str, motherboard_number: str, firmware_version: str, timestamps: int = 512, delta_window: float = 50000.0, cycle_length: float | None = None, apply_mask: bool = True, include_offset: bool = False, apply_calibration: bool = True, absolute_timestamps: bool = False, correct_pix_address: bool = False)

Calculate and save timestamp differences into ‘.feather’ file.

Unpacks data into a dictionary, calculates timestamp differences for the requested pixels, and saves them into a ‘.feather’ table. Works with firmware version 2212. Uses a faster algorithm. Calculated only for the diagonal pixels, i.e., 1-1, 2-2, etc., and not for all pairs.

Parameters:

• path (str) – Path to the folder with ‘.dat’ data files.

• pixels (List[int] | List[List[int]]) – List of pixel numbers for which the timestamp differences should be calculated and saved or list of two lists with pixel numbers for peak vs. peak calculations.

• rewrite (bool) – switch for rewriting the plot if it already exists. used as a safeguard to avoid unwanted overwriting of the previous results. Switch for rewriting the ‘.feather’ file if it already exists.

• daughterboard_number (str) – LinoSPAD2 daughterboard number.

• motherboard_number (str) – LinoSPAD2 motherboard (FPGA) number, including the ‘#’.

• firmware_version (str) – LinoSPAD2 firmware version. Versions “2212s” (skip) and “2212b” (block) are recognized.

• timestamps (int, optional) – Number of timestamps per acquisition cycle per pixel. The default is 512.

• delta_window (float, optional) – Size of a window to which timestamp differences are compared. Differences in that window are saved. The default is 50e3 (50 ns).

• cycle_length (float, optional) – Length of the acquisition cycle. The default is None.

• apply_mask (bool, optional) – Switch for applying the mask for hot pixels. The default is True.

• include_offset (bool, optional) – Switch for applying offset calibration. The default is True.

• apply_calibration (bool, optional) – Switch for applying TDC and offset calibration. If set to ‘True’ while apply_offset_calibration is set to ‘False’, only the TDC calibration is applied. The default is True.

• absolute_timestamps (bool, optional) – Indicator for data with absolute timestamps. The default is False.

• correct_pix_address (bool, optional) – Correct pixel address for the sensor half on side 23 of the daughterboard. The default is False.

Raises:

• TypeError – Raised if “pixels” is not a list.

• TypeError – Raised if “firmware_version” is not a string.

• TypeError – Raised if “rewrite” is not a boolean.

• TypeError – Raised if “daughterboard_number” is not a string.

daplis.functions.delta_t.calculate_and_save_timestamp_differences_full_sensor(path, pixels: list, rewrite: bool, daughterboard_number: str, motherboard_number1: str, motherboard_number2: str, firmware_version: str, timestamps: int = 512, delta_window: float = 50000.0, apply_mask: bool = True, include_offset: bool = False, apply_calibration: bool = True, absolute_timestamps: bool = False)

Calculate and save timestamp differences into ‘.feather’ file.

Unpacks data into a dictionary, calculates timestamp differences for the requested pixels and saves them into a ‘.feather’ table. Works with firmware version 2212. Analyzes data from both sensor halves/both FPGAs, hence the two input parameters for LinoSPAD2 motherboards.

Parameters:

• path (str) – Path to where two folders with data from both motherboards are. The folders should be named after the motherboards.

• pixels (list) – List of two pixels, one from each sensor half.

• rewrite (bool) – switch for rewriting the plot if it already exists. used as a safeguard to avoid unwanted overwriting of the previous results. Switch for rewriting the ‘.feather’ file if it already exists.

• daughterboard_number (str) – LinoSPAD2 daughterboard number.

• motherboard_number1 (str) – LinoSPAD2 motherboard (FPGA) number, including the ‘#’.

• motherboard_number2 (str) – Second LinoSPAD2 motherboard (FPGA) number.

• firmware_version (str) – LinoSPAD2 firmware version. Versions “2212s” (skip) and “2212b” (block) are recognized.

• timestamps (int, optional) – Number of timestamps per acquisition cycle per pixel. The default is 512.

• delta_window (float, optional) – Size of a window to which timestamp differences are compared. Differences in that window are saved. The default is 50e3 (50 ns).

• apply_mask (bool, optional) – Switch for applying the mask for hot pixels. The default is True.

• include_offset (bool, optional) – Switch for applying offset calibration. The default is True.

• apply_calibration (bool, optional) – Switch for applying TDC and offset calibration. If set to ‘True’ while include_offset is set to ‘False’, only the TDC calibration is applied. The default is True.

• absolute_timestamps (bool, optional) – Switch for unpacking data that were collected together with absolute timestamps. The default is False.

Raises:

• TypeError – Only boolean values of ‘rewrite’ and string values of ‘daughterboard_number’, ‘motherboard_number’, and ‘firmware_version’ are accepted. The first error is raised so that the plot does not accidentally get rewritten in the case no clear input was given.

• FileNotFoundError – Raised if data from the first LinoSPAD2 motherboard were not found.

• FileNotFoundError – Raised if data from the second LinoSPAD2 motherboard were not found.

daplis.functions.delta_t.calculate_and_save_timestamp_differences_full_sensor_alt(path, pixels: list, rewrite: bool, daughterboard_number: str, motherboard_number1: str, motherboard_number2: str, firmware_version: str, timestamps: int = 512, delta_window: float = 50000.0, include_offset: bool = False, apply_calibration: bool = True, scan_window: float = 1000000.0)

Calculate and save cross-board timestamp differences to ‘.feather’.

Unpacks data from both sensor halves/both FPGAs, finds the constant board-to-board offset automatically from the absolute timestamps, calculates timestamp differences for the requested pixels around that offset, and saves them into a ‘.feather’ table. Works with firmware versions “2212s” and “2212b”. Useful for data where the signal is above zero right from the start of data collecting.

The two boards are assumed to share a common external clock but NOT a common trigger (CLK_IN/J11 only). Each FPGA then has its own free-running 133.333 MHz absolute-timestamp counter (7.5 ns per tick) that starts at an arbitrary power-up moment, so the boards are related by a single large constant offset (Delta_epoch). For this acquisition mode the counters are monotonic and continuous across the whole run (each file’s first tick exceeds the previous file’s last), so one global offset aligns every photon on both boards:

T_right(event) - T_left(event) = Delta_epoch (constant)

Every requested pixel’s photons are pooled onto each board’s continuous timeline; the integer-cycle lag that maximizes the number of coincidences within ‘scan_window’ fixes Delta_epoch; then, per pixel pair, all differences within ‘delta_window’ of that offset are kept. There is no ‘epoch_offset_ps’ parameter - the offset is always found from the data.

Absolute timestamps are required: each data file must have been collected with ‘acqTimestamps’ enabled in the LinoSPAD2 GUI (adds a 2-word header per acquisition cycle).

Absolute timestamps are always required. Each data file must have been collected with ‘acqTimestamps’ enabled in the LinoSPAD2 GUI (adds a 2-word header per acquisition cycle). The per-cycle clock offset between the two boards is computed from these timestamps and subtracted from every photon timestamp difference before saving.

Parameters:

• path (str) – Path to where two folders with data from both motherboards are. The folders should be named after the motherboards.

• pixels (list) – Either a list of two pixels (one from each sensor half) or a list of two lists of pixels, [[left, …], [right, …]]. Pixels for the second (right) half are given as full-sensor indices (256..511).

• rewrite (bool) – Switch for rewriting the ‘.feather’ file if it already exists. Used as a safeguard to avoid unwanted overwriting.

• daughterboard_number (str) – LinoSPAD2 daughterboard number.

• motherboard_number1 (str) – First LinoSPAD2 motherboard (FPGA) number, including the ‘#’. Corresponds to the left sensor half.

• motherboard_number2 (str) – Second LinoSPAD2 motherboard (FPGA) number, including the ‘#’. Corresponds to the right sensor half.

• firmware_version (str) – LinoSPAD2 firmware version. Versions “2212s” (skip) and “2212b” (block) are recognized.

• timestamps (int, optional) – Number of timestamps per acquisition cycle per pixel. The default is 512.

• delta_window (float, optional) – Half-width of the window (in ps) around the located offset within which timestamp differences are kept. Must be wider than the board-to-board skew (tens of ns). The default is 50e3 (50 ns).

• include_offset (bool, optional) – Switch for applying offset calibration (requires an offset calibration file for both boards). The default is False.

• apply_calibration (bool, optional) – Switch for applying TDC calibration. If set to ‘True’ while ‘include_offset’ is ‘False’, only the TDC calibration is applied. The default is True.

• scan_window (float, optional) – Half-width of the window (in ps) used while locating the coarse board-to-board offset. The default is 1e6 (1 us).

Returns:

Dictionary describing the located alignment, with the keys: ‘feather’ (path to the saved file), ‘cycle_lag_N’ (the integer cycle lag that aligns the boards), ‘delta_epoch_ps’ and ‘delta_epoch_s’ (the board-to-board offset), and ‘pair_counts’ (number of differences saved per pixel pair).

Return type:

dict

Raises:

• TypeError – If ‘pixels’ is not a list, ‘firmware_version’ is not a string, ‘rewrite’ is not a boolean, or ‘daughterboard_number’ is not a string.

• FileNotFoundError – If data from either motherboard, or the calibration data, were not found.

• ValueError – If a data file does not contain absolute timestamps.

• RuntimeError – If the absolute-timestamp counters are not monotonic across the run, if the requested pixels contain no photons, or if no significant coincidence offset can be located.

daplis.functions.delta_t.collect_and_plot_timestamp_differences(path, pixels, rewrite: bool, ft_file: str | None = None, range_left: int = -10000.0, range_right: int = 10000.0, multiplier: int = 1, same_y: bool = False, color: str | None = None, correct_pix_address: bool = False, pickle_figure: bool = False, file_offset_abs: str | None = None)

Collect and plot timestamp differences from a ‘.feather’ file.

Plots timestamp differences from a ‘.feather’ file as a grid of histograms and as a single plot. The plot is saved in the ‘results/delta_t’ folder, which is created (if it does not already exist) in the same folder where data are.

Parameters:

• path (str) – Path to the folder with ‘.dat’ data files.

• pixels (list) – List of pixel numbers for which the timestamp differences should be plotted.

• rewrite (bool) – switch for rewriting the plot if it already exists. used as a safeguard to avoid unwanted overwriting of the previous results. Switch for rewriting the plot if it already exists. Used as a safeguard to avoid unwanted overwriting of the previous results.

• ft_file (str, optional) – Path to the feather file with timestamp differences. If used, the data files in the path are ignored. The default is None.

• range_left (int, optional) – Lower limit for timestamp differences, lower values are not used. The default is -10e3.

• range_right (int, optional) – Upper limit for timestamp differences, higher values are not used. The default is 10e3.

• multiplier (int, optional) – Histogram binning multiplier. Can be used for coarser binning. The default is 1.

• same_y (bool, optional) – Switch for plotting the histograms with the same y-axis. The default is False.

• color (str, optional) – Color for the plot. The default is ‘rebeccapurple’.

• correct_pix_address (bool, optional) – Correct pixel address for the sensor half on side 23 of the daughterboard. The default is False.

• pickle_figure (bool, optional) – Switch for pickling the plot. Can be used to extract the plot data. The default is False.

• file_offset_abs (str, optional) – Absolute path to the ‘.npy’ file with the offset calibration for the particular board. The default is “”.

Raises:

TypeError – Only boolean values of ‘rewrite’ are accepted. The error is raised so that the plot does not accidentally gets rewritten.

Return type:

None.

daplis.functions.delta_t.collect_and_plot_timestamp_differences_full_sensor(path, pixels, rewrite: bool, range_left: int = -10000.0, range_right: int = 10000.0, multiplier: int = 1, same_y: bool = False, color: str | None = None)

Collect and plot timestamp differences from a ‘.feather’ file.

Plots timestamp differences from a ‘.feather’ file as a grid of histograms and as a single plot. The plot is saved in the ‘results/delta_t’ folder, which is created (if it does not already exist) in the same folder where data are.

Parameters:

• path (str) – Path to the folder with ‘.dat’ data files.

• pixels (list) – List of pixel numbers for which the timestamp differences should be plotted.

• rewrite (bool) – switch for rewriting the plot if it already exists. used as a safeguard to avoid unwanted overwriting of the previous results. Switch for rewriting the plot if it already exists. Used as a safeguard to avoid unwanted overwriting of the previous results.

• range_left (int, optional) – Lower limit for timestamp differences, lower values are not used. The default is -10e3.

• range_right (int, optional) – Upper limit for timestamp differences, higher values are not used. The default is 10e3.

• multiplier (int, optional) – Histogram binning multiplier. Can be used for coarser binning. The default is 1.

• same_y (bool, optional) – Switch for plotting the histograms with the same y-axis. The default is False.

• color (str, optional) – Color for the plot. The default is ‘rebeccapurple’.

Raises:

TypeError – Only boolean values of ‘rewrite’ are accepted. The error is raised so that the plot does not accidentally gets rewritten.

Return type:

None.

daplis.functions.delta_t.unpickle_plot(delta_t_pickle_file: str) → dict

Unpickle a saved figure and return plot data.

Load a pickled figure, extract and return the data for each subplot found.

Parameters:

delta_t_pickle_file (str) – The absolute path to the pickle file with the histogram plot.

Returns:

A tuple containing: - fig (matplotlib.figure.Figure): The unpickled figure object. - plot_data (dict): A dictionary with keys “Histogram_i,j” where i,j are the pixels that were used for the particular histogram where each value is a tuple of x and y data for the corresponding bar plot.

Return type:

tuple

Raises:

FileNotFoundError – If the specified pickle file does not exist, a FileNotFoundError is raised and an error message is printed.