`haniwers.v1.threshold.fitter`#

Threshold fitting functionality for analysis of scan results.

This module provides threshold fitting analysis for ThresholdScanResult data, calculating optimal threshold values using complementary error function fitting.

Functions: erfc_function: Complementary error function for threshold fitting fit_threshold_by_channel: Fit error function to threshold scan data for a single channel fit_thresholds: Calculate optimal thresholds for multiple channels

Examples: Basic threshold fitting workflow:

>>> import pandas as pd
>>> from haniwers.v1.threshold.fitter import fit_thresholds
>>> data = pd.read_csv('scan_results.csv')
>>> optimal_thresholds = fit_thresholds(data, channels=[1, 2, 3], params=[10, 300, 1, 1])
>>> print(optimal_thresholds[['ch', '3sigma']])

Module Contents#

Classes#

ThresholdFitResult

Result of threshold fitting for a single channel.

Functions#

`erfc_function`	Complementary error function for threshold fitting.
`fit_threshold_by_channel`	Determine optimal threshold values using error function fitting.
`fit_thresholds`	Calculate optimal threshold values for multiple channels.
`verify_fit_quality`	Verify threshold fit quality and reasonableness.
`plot_fit_results`	Create and save interactive hvplot visualizations of fit results.

API#

class haniwers.v1.threshold.fitter.ThresholdFitResult#

Bases: typing.NamedTuple

Result of threshold fitting for a single channel.

Attributes: ch: Channel number (1-3) timestamp: ISO8601 timestamp of when fit was performed mean: Mean threshold value (b parameter from erfc fit) sigma: Sigma parameter (width of transition region) sigma_0: Optimal threshold at 0σ level (mean) sigma_1: Optimal threshold at 1σ level sigma_3: Optimal threshold at 3σ level (recommended) sigma_5: Optimal threshold at 5σ level

ch: int#: None

timestamp: str#: None

mean: float#: None

sigma: float#: None

sigma_0: float#: None

sigma_1: float#: None

sigma_3: float#: None

sigma_5: float#: None

haniwers.v1.threshold.fitter.erfc_function(x: numpy.ndarray, a: float, b: float, c: float, d: float) → numpy.ndarray#

Complementary error function for threshold fitting.

Mathematical function used to fit threshold scan data S-curves. This function models the probability distribution of detector response as a function of threshold voltage.

The function is defined as: f(x) = a * erfc((x - b) / c) + d

where erfc(x) = 1 - erf(x) is the complementary error function.

Parameters

x : np.ndarray Input values (threshold voltages). a : float Height parameter (amplitude of the S-curve). b : float Mean parameter (center position of the transition). c : float Sigma parameter (width of the transition region). d : float Offset parameter (baseline level).

Returns

np.ndarray Fitted function values at input points.

Examples

import numpy as np x = np.array([250, 260, 270, 280, 290]) result = erfc_function(x, a=10, b=275, c=5, d=1) len(result) 5

Notes

This function is typically used with scipy.optimize.curve_fit to determine optimal threshold values from scan data.

haniwers.v1.threshold.fitter.fit_threshold_by_channel(data: pandas.DataFrame, ch: int, func, params: list[float]) → tuple[pandas.DataFrame, pandas.DataFrame, pandas.DataFrame]#

Determine optimal threshold values using error function fitting.

Analyzes threshold scan data for a specific channel by fitting a complementary error function to the event rate vs threshold curve. Calculates multiple sigma levels (0σ, 1σ, 3σ, 5σ) for threshold selection.

The fitting process:

Extracts data for the specified channel
Calculates event rates (events/event_count)
Performs curve fitting with provided initial parameters
Repeats fitting using optimized parameters for better convergence
Generates fit curve and calculates threshold recommendations

Parameters

data : pd.DataFrame Threshold scan data with columns for channel thresholds and hit counts. Expected to contain columns: ‘ch1’, ‘ch2’, ‘ch3’ for thresholds and ‘top’, ‘mid’, ‘btm’ for hit counts. ch : int Channel number (1-3) to analyze for threshold determination. func : callable Fitting function, typically erfc_function for threshold analysis. params : list[float] Initial parameters for curve fitting [height, mean, sigma, offset].

Returns

thresholds : pd.DataFrame DataFrame with calculated threshold values at different sigma levels: columns [‘timestamp’, ‘ch’, ‘0sigma’, ‘1sigma’, ‘3sigma’, ‘5sigma’]. data_fitted : pd.DataFrame Data subset for the specified channel with added ‘event_rate’ column. fit_curve : pd.DataFrame Fitted curve data points for plotting with columns [‘vth’, ‘event_rate’, ‘ch’].

Examples

import pandas as pd from haniwers.v1.threshold.fitter import fit_threshold_by_channel, erfc_function data = pd.read_csv(‘scan_results.csv’) thresholds, fitted_data, curve = fit_threshold_by_channel( … data, ch=1, func=erfc_function, params=[10, 300, 1, 1] … ) thresholds[‘3sigma’].iloc[0] # Recommended threshold 283

Notes

Performs two-stage fitting for improved convergence
Sigma levels represent: mean + N*sigma threshold recommendations
3σ level is typically used as the optimal threshold
Fit curve spans the full range of input threshold values

haniwers.v1.threshold.fitter.fit_thresholds(data: pandas.DataFrame, channels: list[int], params: list[float]) → pandas.DataFrame#

Calculate optimal threshold values for multiple channels.

Processes threshold scan data for multiple channels and determines optimal threshold values using complementary error function fitting. Returns a consolidated DataFrame with threshold recommendations for all specified channels.

Parameters

data : pd.DataFrame Complete threshold scan data containing measurements for all channels. Expected to have columns: ‘event_count’, ‘ch1’, ‘ch2’, ‘ch3’, ‘top’, ‘mid’, ‘btm’. channels : list[int] List of channel numbers (1-3) to calculate thresholds for. params : list[float] Initial parameters for curve fitting [height, mean, sigma, offset].

Returns

pd.DataFrame Consolidated DataFrame with threshold values for all channels. Contains columns: [‘timestamp’, ‘ch’, ‘0sigma’, ‘1sigma’, ‘3sigma’, ‘5sigma’]. Each row represents one channel’s calculated thresholds.

Examples

import pandas as pd from haniwers.v1.threshold.fitter import fit_thresholds data = pd.read_csv(‘scan_results.csv’) channels = [1, 2, 3] params = [10, 300, 1, 1] # [height, mean, sigma, offset] thresholds = fit_thresholds(data, channels, params) thresholds[[‘ch’, ‘3sigma’]] # Show recommended thresholds ch 3sigma 0 1 283 1 2 278 2 3 285

Notes

Calls fit_threshold_by_channel() for each specified channel
Only returns threshold DataFrames, discards fitted data and curves
Results are concatenated with reset index for clean output
3σ level is typically used as the optimal threshold value

haniwers.v1.threshold.fitter.verify_fit_quality(scan_data: pandas.DataFrame, fit_results: pandas.DataFrame, verbose: bool = True) → dict#

Verify threshold fit quality and reasonableness.

Performs statistical and physical validation of fitting results, checking for data completeness, reasonable threshold values, event distribution, and potential fitting issues.

Parameters

scan_data : pd.DataFrame Threshold scan data with columns: timestamp, event_count, ch1, ch2, ch3, top, mid, btm fit_results : pd.DataFrame Fit results with columns: timestamp, ch, 0sigma, 1sigma, 3sigma, 5sigma verbose : bool Print verification results to console

Returns

dict Verification results for all channels with keys: - channel: Channel number - sigma_0: 0σ threshold value - sigma_3: 3σ threshold value (recommended) - data_points: Number of data points for fitting - x_range: (min, max) of threshold values in scan - y_range: (min, max) of event counts - warnings: List of warning messages (if any)

Example

results = verify_fit_quality(scan_data, fit_results) for ch, info in results.items(): … if info[‘warnings’]: … print(f"Channel {ch}: {info[‘warnings’]}")

haniwers.v1.threshold.fitter.plot_fit_results(scan_data: pandas.DataFrame, fit_results: pandas.DataFrame, output_dir: pathlib.Path = None, verbose: bool = False) → dict#

Create and save interactive hvplot visualizations of fit results.

Generates per-channel plots showing:

Scan data points (actual threshold measurements)
Fitted curve (complementary error function)
Threshold recommendations at different sigma levels (0σ, 1σ, 3σ, 5σ)
Event rate vs threshold voltage

Each channel gets its own interactive HTML visualization saved to disk.

Parameters

scan_data : pd.DataFrame Original threshold scan data with columns: timestamp, event_count, ch1, ch2, ch3, top, mid, btm fit_results : pd.DataFrame Fitted threshold values with columns: timestamp, ch, 0sigma, 1sigma, 3sigma, 5sigma (output from fit_thresholds) output_dir : Path, optional Directory to save visualization HTML files. If None, creates ‘threshold_plots’ subdirectory in current working directory. verbose : bool Print status messages during visualization creation

Returns

dict Visualization metadata with keys: - channel: Channel number - plot_file: Path to saved HTML file - data_points: Number of scan data points - threshold_3sigma: Recommended threshold (3σ level)

Example

import pandas as pd from haniwers.v1.threshold.fitter import fit_thresholds, plot_fit_results scan_data = pd.read_csv(‘scan_results.csv’) fit_results = fit_thresholds(scan_data, channels=[1, 2, 3], params=[10, 300, 1, 1]) plot_results = plot_fit_results(scan_data, fit_results, output_dir=Path(‘./plots’)) print(plot_results[1][‘plot_file’]) # Path to channel 1 plot

Notes

Requires hvplot and bokeh for interactive HTML generation
Each plot includes interactive legend, zoom, pan, and hover tools
Threshold lines (0σ, 1σ, 3σ, 5σ) are color-coded for easy interpretation
Output files are named: threshold_fit_ch{N}.html (where N is channel number)

haniwers.v1.threshold.fitter

目次

haniwers.v1.threshold.fitter#

Module Contents#

Classes#

Functions#

API#

`haniwers.v1.threshold.fitter`#