gwsnr.threshold.snrthresholdfinder

This module implements the SNRThresholdFinder class to determine the optimal SNR threshold for gravitational wave detection using cross-entropy maximization (following Essick et al. 2023).

Module Contents

Classes

SNRThresholdFinder

A class to find the optimal SNR threshold for gravitational wave detection using cross-entropy maximization.

class gwsnr.threshold.snrthresholdfinder.SNRThresholdFinder(catalog_file=None, npool=4, selection_range=None, original_detection_statistic=None, projected_detection_statistic=None, parameters_to_fit=None, sample_size=20000, multiprocessing_verbose=True)

A class to find the optimal SNR threshold for gravitational wave detection using cross-entropy maximization.

Parameters:

catalog_filestr

Path to the HDF5 file containing the injection catalog data. The file should have something like the following structure (refer to https://zenodo.org/records/16740117): ` injections.hdf |-- events |   |-- z  (parameter to me fitted on) |   |-- mass1_source (parameter with which the data is to be selected with) |   |-- gstlal_far (original_detection_statistic) |   |-- observed_snr_net (projected_detection_statistic) `

original_detection_statisticdict, optional

Dictionary specifying the original detection statistic with keys: ‘parameter’ (str): Name of the key in the catalog for the original detection statistic. ‘threshold’ (float): Threshold value for the original detection statistic. Default is {‘parameter’: ‘gstlal_far’, ‘threshold’: 1}.

projected_detection_statisticdict, optional

Dictionary specifying the projected detection statistic with keys: ‘parameter’ (str): Name of the key in the catalog for the projected detection statistic. ‘threshold’ (float): Threshold value for the projected detection statistic. ‘threshold_search_bounds’ (tuple): Bounds for the threshold search. Default is {‘parameter’: ‘observed_snr_net’, ‘threshold’: None, ‘threshold_search_bounds’: (4, 14)}.

parameters_to_fitlist of str, optional

List of parameter to fit, e.g., [‘redshift’]. Default is [‘redshift’].

sample_sizeint, optional

Number of samples to use for KDE estimation. Default is 10000.

selection_rangedict, optional

Dictionary specifying the selection range with keys: ‘parameter’ (str or list): Parameter(s) to apply the selection range on. ‘range’ (tuple): Tuple specifying the (min, max) range for selection. Default is {‘parameter’: ‘mass1_source’, ‘range’: (5, 200)}.

Examples

>>> finder = SNRThresholdFinder(catalog_file='injection_catalog.h5')
>>> best_thr, del_H, H, H_true, snr_thrs = finder.find_threshold(iteration=10)
>>> print(f"Best SNR threshold: {best_thr:.2f}")

npool = '4'

multiprocessing_verbose = 'True'

selection_range = 'None'

sample_size = '20000'

det_data(catalog_file)

Function to load and preprocess the injection catalog data from an HDF5 file.

Parameters:

catalog_filestr

Path to the HDF5 file containing the injection catalog data.

Returns

-------

result_dictdict

Dictionary containing the preprocessed data for the specified parameters and detection statistics.

Raises:

ValueError

If ‘redshift’ is not included in parameters_to_fit.

find_threshold(iteration=10, print_output=True, no_multiprocessing=False)

Function to find the optimal SNR threshold by maximizing the cross-entropy difference.

Parameters:

iterationint, optional

Number of iterations for threshold search. Default is 10.

print_outputbool, optional

Whether to print the best SNR threshold. Default is True.

Returns:

best_thrfloat

The optimal SNR threshold that maximizes the cross-entropy difference.

del_Hnp.ndarray

Array of cross-entropy differences for each threshold tested.

Hnp.ndarray

Array of cross-entropy values for the KDE with cut.

H_truenp.ndarray

Array of cross-entropy values for the original KDE.

snr_thrsnp.ndarray

Array of SNR thresholds tested.

Raises:

ValueError

If the number of iterations is less than 1.

find_best_SNR_threshold(thrs, del_H)

Function to find the best SNR threshold using spline interpolation and optimization.

Parameters:

thrsnp.ndarray

Array of SNR thresholds tested.

del_Hnp.ndarray

Array of cross-entropy differences for each threshold tested.

Returns:

best_thrfloat

The optimal SNR threshold that maximizes the cross-entropy difference.