daplis.functions.fits module

Module for fitting timestamp differences with Gaussian function.

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

fit_with_gaussian - fit timestamp differences of a pair of pixels

with a Gaussian function and plot a histogram of timestamp differences and the fit in a single figure.

fit_with_gaussian_combine - combine timestamp differences for the

requested pixels before fitting them with a Gaussian function. Then, plot a histogram together with the fit.

fit_with_gaussian_all - find all peaks above the given threshold

and fit them individually with a Gaussian function.

fit_with_gaussian_full_sensor - fit timestamp differences of a

pair of pixels (one from each half of the sensor) with a Gaussian function and plot a histogram of timestamp differences and the fit in a single figure. The cross-board coincidence peak sits at the constant board-to-board skew rather than at zero, so the peak center is located automatically before fitting.

fit_with_gaussian_lmfit - fit timestamp diferences of a pair of

pixels using the lmfit library. The main parameters reported are the standard deviation, mean value, and contrast, together with residuals and signal-to-noise ratio (SNR) defined as a ratio of peak height to standard deviation of background.

unpickle_fit - unpickle the ‘.pkl’ file, show the plot, and

return the plot data for each line found (histogram, fit 1, fit 2, etc.).

daplis.functions.fits.fit_with_gaussian(path: str, pixels: list[int] | list[list[int]], ft_file: str | None = None, range_left: float = -5000.0, range_right: float = 5000.0, multiplier: int = 1, normalize: bool = False, color_data: str | None = None, color_fit: str | None = None, title_on: bool = True, correct_pix_address: bool = False, return_fit_params: bool = False, pickle_figure: bool = False, file_offset_abs: str | None = None) → DataFrame[source]

Fit with Gaussian function and plot it.

Fits timestamp differences of a pair of pixels with Gaussian function and plots it next to the histogram of the differences. Timestamp differences are collected from a ‘.feather’ file if it exists.

Parameters:

path (str) – Path to the folder with ‘.dat’ data files or where the ‘.feather’ file with timestamp differences is located.
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.
ft_file (str, optional) – Name of the ‘.feather’ file to use for plotting. Can be used when the raw ‘.dat’ data is not available. The default is None.
range_left (float, optional) – Left limit for the signal window. The default is -5e3.
range_right (float, optional) – Right limit for the signal window. The default is 5e3.
multiplier (int, optional) – Bins of delta t histogram should be in units of 17.857 (average LinoSPAD2 TDC bin width), this parameter helps with changing the bin size while maintaining that rule. Default is 1.
normalize (bool, optional) – Switch for normalizing the plot to median. The default is False.
color_data (str, optional) – For changing the color of the data. The default is “rebeccapurple”.
color_fit (str, optional) – For changing the color of the fit. The default is “darkorange”.
title_on (bool, optional) – Switch for turning on/off the title of the plot, the title shows the pixels for which the fit is done. The default is True.
correct_pix_address (bool, optional) – Correct pixel address for the FPGA board on side 23. The default is False.
return_fit_params (bool, optional) – Switch for returning the fit parameters for further analysis. 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 None.

Raises:

FileNotFoundError – Raised if no ‘.dat’ data files are found.
FileNotFoundError – Raised if no ‘.feather’ file with timestamp differences is found.
ValueError – Raised if no data for the requested pair of pixels is found in the ‘.feather’ file.

Returns:

A dataframe with fit parameters and their standard errors. Returned only if the “return_fit_params” is set to True.

Return type:

DataFrame.

daplis.functions.fits.fit_with_gaussian_all(path: str, pixels: list[int] | list[list[int]], ft_file: str | None = None, threshold_multiplier: float = 1.2, range_left: float = -5000.0, range_right: float = 5000.0, multiplier: int = 1, normalize: bool = False, color_d: str | None = None, color_f: str | None = None, title_on: bool = True, correct_pix_address: bool = False, return_fit_params: bool = False, pickle_figure: bool = False) → DataFrame[source]

Find all peaks above threshold and fit each with Gaussian.

Finds all peaks above the given threshold (uses the ‘threshold_multiplier’ parameter as a multiplier of the median) and fits each with a Gaussian function.

Parameters:

path (str) – Path to the folder with ‘.dat’ data files or where the ‘.feather’ file with timestamp differences is located.
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.
ft_file (str, optional) – Name of the ‘.feather’ file to use for plotting. Can be used when the raw ‘.dat’ data is not available. The default is None.
threshold_multiplier (float, optional) – Multiplier for the median of the histogram counts. Used for setting a threshold for the peak discovery in the histogram. The default is 1.2, or 20% above the median.
range_left (float, optional) – Left limit for the signal window. The default is -5e3.
range_right (float, optional) – Right limit for the signal window. The default is 5e3.
multiplier (int, optional) – Bins of delta t histogram should be in units of 17.857 (average LinoSPAD2 TDC bin width). Default is 1.
normalize (bool, optional) – Switch for normalizing the plot to median. The default is False.
color_d (str, optional) – Color for the histogram. The default is “rebeccapurple”.
color_f (str, optional) – Color for the fit with Gaussian. The default is “darkorange”.
title_on (bool, optional) – Switch for showing the plot title. The default is “True”.
correct_pix_address (bool, optional) – Correct pixel address for the FPGA board on side 23. The default is False.
return_fit_params (bool, optional) – Switch for returning the fit parameters for further analysis. 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.

Raises:

FileNotFoundError – Raised when no ‘.dat’ data files are found.
FileNotFoundError – Raised when no ‘.feather’ file with timestamp differences is found.
ValueError – Raised when no data for the requested pair of pixels was found in the ‘.feather’ file.

Returns:

A dataframe with fit parameters and their standard errors. Returned only if the “return_fit_params” is set to True.

Return type:

DataFrame.

daplis.functions.fits.fit_with_gaussian_combine(path: str, pixels: list[int] | list[list[int]], ft_file: str | None = None, range_left: float = -5000.0, range_right: float = 5000.0, multiplier: int = 1, normalize: bool = False, color_data: str | None = None, color_fit: str | None = None, title_on: bool = True, correct_pix_address: bool = False, return_fit_params: bool = False, pickle_figure: bool = False, file_offset_abs: str | None = None) → DataFrame[source]

Fit with Gaussian function and plot it, merging the pixels.

Fits timestamp differences of a pair of pixels with Gaussian function and plots it next to the histogram of the differences. Timestamp differences are collected from a ‘.feather’ file if it exists. Merges the data from all pixel pairs requested into a single peak.

Parameters:

path (str) – Path to the folder with ‘.dat’ data files or where the ‘.feather’ file with timestamp differences is located.
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.
ft_file (str, optional) – Name of the ‘.feather’ file to use for plotting. Can be used when the raw ‘.dat’ data is not available. The default is None.
range_left (float, optional) – Left limit for the signal window. The default is -5e3.
range_right (float, optional) – Right limit for the signal window. The default is 5e3.
multiplier (int, optional) – Bins of delta t histogram should be in units of 17.857 (average LinoSPAD2 TDC bin width), this parameter helps with changing the bin size while maintaining that rule. Default is 1.
normalize (bool, optional) – Switch for normalizing the plot to median. The default is False.
color_data (str, optional) – For changing the color of the data. The default is “rebeccapurple”.
color_fit (str, optional) – For changing the color of the fit. The default is “darkorange”.
title_on (bool, optional) – Switch for turning on/off the title of the plot, the title shows the pixels for which the fit is done. The default is True.
correct_pix_address (bool, optional) – Correct pixel address for the FPGA board on side 23. The default is False.
return_fit_params (bool, optional) – Switch for returning the fit parameters for further analysis. 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 None.

Raises:

FileNotFoundError – Raised if no ‘.dat’ data files are found.
FileNotFoundError – Raised if no ‘.feather’ file with timestamp differences is found.
ValueError – Raised if no data for the requested pair of pixels is found in the ‘.feather’ file.

Returns:

A dataframe with fit parameters and their standard errors. Returned only if the “return_fit_params” is set to True.

Return type:

DataFrame.

daplis.functions.fits.fit_with_gaussian_full_sensor(path: str, pix_pair: list[int], ft_file: str | None = None, range_left: float = -5000.0, range_right: float = 5000.0, center: float | None = None, multiplier: int = 1, normalize: bool = False, color_data: str | None = None, color_fit: str | None = None, title_on: bool = True, return_fit_params: bool = False, pickle_figure: bool = False) → DataFrame[source]

Fit with Gaussian function and plot it.

Fits timestamp differences of a pair of pixels (one from each half of the sensor) with a Gaussian function and plots a histogram of timestamp differences alongside the fit.

Parameters:

path (str) – Path to the folder containing board sub-folders or the ‘.feather’ file with timestamp differences.
pix_pair (list) – Two pixel numbers for which the fit is done.
ft_file (str, optional) – Name of the ‘.feather’ file to use for plotting. Can be used when the raw ‘.dat’ data is not available. The default is None.
range_left (float, optional) – Left edge of the fit window, relative to the located peak center. The default is -5e3.
range_right (float, optional) – Right edge of the fit window, relative to the located peak center. The default is 5e3.
center (float, optional) – Peak center (in ps) around which the fit window is applied. For cross-board data the coincidence peak sits at the constant board-to-board skew rather than at zero, so by default (None) the center is located automatically from the data before fitting. Pass a value to force it. The default is None.
multiplier (int, optional) – Bins of delta t histogram should be in units of 17.857 (average LinoSPAD2 TDC bin width), this parameter helps with changing the bin size while maintaining that rule. Default is 1.
normalize (bool, optional) – Switch for normalizing the plot to median. The default is False.
color_data (str, optional) – For changing the color of the data. The default is “rebeccapurple”.
color_fit (str, optional) – For changing the color of the fit. The default is “darkorange”.
title_on (bool, optional) – Switch for turning on/off the title of the plot, the title shows the pixels for which the fit is done. The default is True.
return_fit_params (bool, optional) – Switch for returning the fit parameters for further analysis. 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.

Raises:

FileNotFoundError – Raised when no ‘.feather’ file with timestamp differences is found.
ValueError – Raised when no data for the requested pair of pixels was found in the ‘.feather’ file.

Returns:

A dataframe with fit parameters and their standard errors. Returned only if the “return_fit_params” is set to True.

Return type:

DataFrame.

daplis.functions.fits.fit_with_gaussian_lmfit(path: str, pixels: list[int] | list[list[int]], ft_file: str | None = None, range_left: float = -5000.0, range_right: float = 5000.0, multiplier: int | None = None, normalize: bool = False, return_fit_params: bool = False, interpolate_fit: bool = True, correct_pix_address: bool = False, pickle_figure: bool = False)[source]

Fit with Gaussian function and plot it, using lmfit library.

Fits timestamp differences of a pair of pixels with Gaussian function and plots it over to the histogram of the differences. Timestamp differences are collected from a ‘.feather’ file. Additionally, the residuals are calculated and plotted below the data and fit, together with a normal distribution of them.

Parameters:

path (str) – Path to the folder with ‘.dat’ data files or where the ‘.feather’ file with timestamp differences is located.
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.
ft_file (str, optional) – Name of the ‘.feather’ file with the timestamp differences. Should be provided when the data files are not available. The default is None.
range_left (float, optional) – Left limit for the signal window. The default is -5e3.
range_right (float, optional) – Right limit for the signal window. The default is 5e3.
multiplier (int, optional) – Bins of delta t histogram should be in units of 17.857 (average LinoSPAD2 TDC bin width), this parameter helps with changing the bin size while maintaining that rule. Default is 1.
normalize (bool, optional) – Switch for normalizing the plot to median. The default is False.
return_fit_parameters (bool, optional) – Switch for returning the fit parameters as they are returned by the lmfit library. The default is False.
interpolate_fit (bool, optional) – Switch for an interpolated fit. The default is True.
correct_pix_address (bool, optional) – Correct pixel address for the FPGA board on side 23. 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.

Returns:

Parameters of the fit as returned by the lmfit library. Returned only if the “return_fit_params” is set to True.

Return type:

lmfit.parameter.Parameters

Raises:

FileNotFoundError – Raised if the ‘delta_ts_data’ folder was not found.

daplis.functions.fits.fit_with_gaussian_lmfit_with_stats(path: str, pixels: list[int] | list[list[int]], ft_file: str | None = None, range_left: float = -5000.0, range_right: float = 5000.0, multiplier: int | None = None, normalize: bool = False, return_fit_params: bool = False, interpolate_fit: bool = True, correct_pix_address: bool = False, pickle_figure: bool = False)[source]

Fit with Gaussian + linear model and produce fit-quality diagnostics.

Extended version of fit_with_gaussian_fancy that adds four diagnostic layers on top of the standard fit:

AIC comparison — fits a linear-only (no-peak) model alongside the Gaussian + linear model. ΔAIC = AIC_linear - AIC_full is reported; ΔAIC > 10 is strong evidence the peak is real.
Pull plot — normalized residuals (y - fit) / sqrt(y) plotted against Δt with ±1σ and ±2σ reference lines, so systematic model failures are immediately visible.
Per-pair KS test — tests whether the pull distribution is consistent with N(0, 1), reported as a p-value on the residuals panel.
Parameter reliability check — flags any parameter whose stderr is None (fit unstable) or whose stderr/value ratio exceeds 0.5 (result uncertain). Printed to console per pair.

When more than one pixel pair is processed, a summary figure is also saved showing the chi2red distribution across pairs and the pooled pull distribution with a KS test.

Parameters:

path (str) – Path to the folder with ‘.dat’ data files or where the ‘.feather’ file with timestamp differences is located.
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.
ft_file (str, optional) – Name of the ‘.feather’ file with the timestamp differences. Should be provided when the data files are not available. The default is None.
range_left (float, optional) – Left limit for the signal window. The default is -5e3.
range_right (float, optional) – Right limit for the signal window. The default is 5e3.
multiplier (int, optional) – Bins of delta t histogram should be in units of 17.857 (average LinoSPAD2 TDC bin width), this parameter helps with changing the bin size while maintaining that rule. Default is None (auto).
normalize (bool, optional) – Switch for normalizing the plot to median. The default is False.
return_fit_params (bool, optional) – Switch for returning fit results per pixel pair as a dict. The default is False.
interpolate_fit (bool, optional) – Switch for an interpolated fit curve. The default is True.
correct_pix_address (bool, optional) – Correct pixel address for the FPGA board on side 23. The default is False.
pickle_figure (bool, optional) – Switch for pickling per-pair plots. The default is False.

Returns:

Keyed by “left,right” pixel pair strings. Each value is a dict with keys: params, redchi, chisqr, nfree, norm_residuals, delta_aic, ks_p. Returned only if return_fit_params is True.

Return type:

dict, optional

Raises:

FileNotFoundError – Raised if the ‘delta_ts_data’ folder was not found.

daplis.functions.fits.unpickle_fit(fit_pickle_file: str) → dict[source]

Unpickle a saved figure and return plot data.

Load a pickled figure, extract and return the histogram and fit data.

Parameters:: fit_pickle_file (str) – The absolute path to the pickle file with the fit plot.
Returns:: A tuple containing: - fig (matplotlib.figure.Figure): The unpickled figure object. - plot_data (dict): A dictionary with keys “Histogram” and “Fit_{i}” (for i >= 1), where each value is a tuple of x and y data for the corresponding line plot. - params_df (pandas.DataFrame): A DataFrame containing fit parameters extracted from the legend. Columns represent each fit.
Return type:: tuple
Raises:: FileNotFoundError – If the specified pickle file does not exist, a FileNotFoundError is raised and an error message is printed.