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, 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 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)[source]

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)[source]

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)[source]

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, threshold: int = 0, apply_mask: bool = True, include_offset: bool = False, apply_calibration: bool = True, absolute_timestamps: bool = False)[source]

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. Uses the threshold value to find the first cycle in each sensor half where the signal is above that value. Useful for when the signal is above zero right from the start of data collecting.

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) – First LinoSPAD2 motherboard (FPGA) number, including the ‘#’.
motherboard_number2 (str) – Second 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).
threshold (int, optional) – Threshold for the number of timestamps per cycle in the given pixels that is used to find the specific cycle. With value of 0 this will find the first cycle where there is any positive signal in the pixel, while a value of 15 will find first cycle when signal is above approx. 4 kHz strong. The default is 0.
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.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)[source]

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)[source]

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[source]

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.