e15190.neutron_wall.pulse_shape_discrimination.PulseShapeDiscriminator¶
- class e15190.neutron_wall.pulse_shape_discrimination.PulseShapeDiscriminator(AB, max_workers=12)¶
Functions
__init__(AB[, max_workers])Construct a class to perform pulse shape discrimination.
cache_run(run[, tree_name])Read in the data from ROOT file and save relevant branches to an HDF5 file.
create_ranges(low, upp, width[, step])denormalize_features([df])Denormalize features.
discrimination_using_pca([normalize_psd_values])figure_of_merit(arr, **find_peaks_kwargs)Calculate the figure-of-merit that quantifies the two-peak separation
find_topN_peaks(arr[, n_peaks, bins, ...])Find the first-N highest peaks from the distribution of arr.
find_two_2dpeaks(x, y, **find_peaks_kwargs)fit()To calculate the pulse shape discrimination parameters.
fit_fast_total(side[, position_range, ...])Fit and update
self.cfast_total.fit_position_correction([light_GM_cut])get_position(df_time, pos_calib_params)Calculate the positions from time and calibration parameters.
normalize_features([df])Normalize features.
normalize_psd_values(psd_column, ...)A function that maps (vpsd_L, vpsd_R, pos) to (ppsd, ppsd_perp)
preprocessing()randomize_integer_features([seed])Randomize the integer columns in
self.df.read(run, bar[, from_cache, verbose])Read in the data needed to do pulse shape discrimintion.
read_run_from_root_file(run[, tree_name, ...])Read in the data from Daniele's ROOT file.
remove_distorted_fast_total()Remove Veto Wall coincidences.
save_parameters([path])Save pulse shape discrimination parameters as a JSON file.
update_hyperparameters(args)value_assign(side)Value-assign a PSD value to each entry.
Properties
adc_rangedatabase_dirft_breakpoint1ft_breakpoint2light_GM_rangemin_samples_gammamin_samples_neutronpos_rangeroot_files_dirx_switch_neutron- __init__(AB, max_workers=12)¶
Construct a class to perform pulse shape discrimination.
- Parameters
AB ('A' or 'B') – The neutron wall to use.
max_workers (int, default 12) – The maximum number of workers to use for parallelization. This value will be passed to the concurrent.futures.ThreadPoolExecutor for constructing
self.decompression_executorandself.interpretation_executor. Each executor is assigned with a thread pool of sizemax_workers.
- classmethod _cut_for_root_file_data(AB)¶
Returns a string that specifies the first common cut.
This cut is the first common cut that is applied to all the data before analysis. Their purpose is only to remove the events that are unphysical. Further analysis cuts will have to be applied separately for each bar.
- Parameters
AB ('A' or 'B') – The neutron wall to use.
- read_run_from_root_file(run, tree_name=None, apply_cut=True)¶
Read in the data from Daniele’s ROOT file.
- Parameters
run (int) – The run number.
tree_name (str, default None) – The name of the tree to read. If None, the default tree name is automatically determined. An exception is raised if multiple objects are found in the ROOT file.
apply_cut (bool, default True) – Whether to apply the first common cut to the data. If
True,self._cut_for_root_file_data(self.AB)is used as the cut.
- static get_position(df_time, pos_calib_params)¶
Calculate the positions from time and calibration parameters.
- Parameters
df_time (pandas.DataFrame) – The dataframe with columns
bar,time_L, andtime_R.pos_calib_params (panda.DataFrame) – The calibration parameters. The index is bar number; the first column is the calibration offset; the second column is the calibration slope.
- Returns
positions – The calibrated positions in cm.
- Return type
numpy.1darray
- cache_run(run, tree_name=None)¶
Read in the data from ROOT file and save relevant branches to an HDF5 file.
The data will be categorized according to bar number, because future retrieval by this class will most likely analyze only one bar at a time.
- Parameters
run (int) – The run number.
tree_name (str, default None) – The name of the tree to read. If None, the default tree name is automatically determined. An exception is raised if multiple objects are found in the ROOT file.
- _read_single_run(run, bar, from_cache=True)¶
Read in the data from a single bar in a single run.
- Parameters
run (int) – The run number.
bar (int) – The bar number.
from_cache (bool, default True) – Whether to read the data from the cache. If
False, the data is read from the ROOT file.
- Returns
df – The dataframe with the data.
- Return type
pandas.DataFrame
- read(run, bar, from_cache=True, verbose=False)¶
Read in the data needed to do pulse shape discrimintion.
Attributes
self.barandself.dfwill be updated. The data will be read from the HDF5 file if it exists, otherwise they will be read in from the ROOT file (generated by Daniele’s framework).- Parameters
- runint or list of ints
The run number(s) to read in. Most of the time, this will be a list of at least five runs. Otherwise, the algorithm will have a hard time find the pulse shape discrimintion parameters due to low statistics.
- barint
The bar number to read in.
- from_cachebool, default True
Whether to read in the data from the HDF5 cache. If False, the data will be read in from the ROOT file. A new cache will be created, overwriting any existing cache.
- verbosebool, default False
Whether to print out the progress of the read in.
- randomize_integer_features(seed=None)¶
Randomize the integer columns in
self.df.For each integer column, we add a uniform random number between -0.5 and +0.5 to the values. This is done in-place.
- Parameters
seed (int, default None) – The seed for the random number generator. If None, the randomization non-reproducible.
- normalize_features(df=None)¶
Normalize features.
Normalization is done such that the resulting variables have mean 0 and standard deviation 1. Under the hood, this is done by
sklearn.preprocessing.StandardScaler. The normalization parameters are stored inself.feature_scaler. This allows for denormalization later on.- Parameters
df (pandas.DataFrame, default None) – The dataframe to normalize. If None, the dataframe in
self.dfis used, and the normalization is done in-place.- Returns
normed_df – The normalized dataframe.
- Return type
pandas.DataFrame
- denormalize_features(df=None)¶
Denormalize features.
Recovers the original values of the features from the normalized ones. This is done by applying the inverse transformation by
self.feature_scaler. The attributeself.feature_scalerwill also be deleted after this operation to prevent further denormalization.- Parameters
df (pandas.DataFrame, default None) – The dataframe to denormalize. If None, the dataframe in
self.dfis used, and the denormalization is done in-place.- Returns
denormed_df – The denormalized dataframe.
- Return type
pandas.DataFrame
- remove_vetowall_coincidences(df=None)¶
Remove Veto Wall coincidences.
This is done to effectively remove charged particles from the data. Currently, this is done by removing the entire event as long as there is any non-zero Veto Wall multiplicity. In the future, this could be further improved by removing only hits that fall within a certain solid angle from the point of contact of the veto wall.
- Parameters
df (pandas.DataFrame, default None) – The dataframe to remove the Veto Wall coincidences from. If None, the dataframe in
self.dfis used in-place.- Returns
df_result – The dataframe with the Veto Wall coincidences removed.
- Return type
pandas.DataFrame
- static find_topN_peaks(arr, n_peaks=2, bins=150, hrange=None, hist_log=False, kernel_width=0.05, kernel_half_range=2.0, fit_range_width=None, return_gaus_fit=False, use_kde=False, kde_bandwidth=None)¶
Find the first-N highest peaks from the distribution of arr.
The algorithm is of recursive nature. It will always find only one peak - the highest peak - at a time, then it subtracts the peak out from the current distribution and proceeds to find the next highest peak. In each recursion, the algorithm simply looks for the highest count of the distribution (in histogram), meaning that it does not check whether the peak is of any statistical significance. While users can specify as many n_peaks as they want, the result only makes sense if arr does actually contain that many peaks.
The algorithm uses a simple local Gaussian fit to each peak in order to improve the precision of the peak locations.
- Parameters
arr –
1D array The array to find the peaks in its distribution. Normalization of arr is done to set the mean to 0 and the standard deviation to 1, so that the algorithm and hyperparameters are more robust to various ranges of arr. Nonetheless, any results will be de-normalized before being returned, i.e. they will be in the original scale or unit.
All other arguments that use the same units as arr will always be specified in the original unit. The normalization is always done internally, so that users do not have to worry about it.
n_peaks – int, default 2 The number of peaks to find.
bins – int, default 150 The number of bins to use in the histogram that approximates the distribution of arr.
hrange – 2-tuple, default None The range of the histogram in the unit of arr. If None, the range is set to [-3, 3] in the normalized unit.
hist_log – bool, default False If True, the counts of the histogram will be log-transformed, i.e. h = log(h + 1), where log is the natural logarithm
kernel_width – float, default 0.05 The width of the kernel used to smooth the histogram.
kernel_half_range – float, default 2.0 The half-range of the kernel.
fit_range_width – float, default None The width, in the unit of arr, specifies regions around the estimated peak positions that will be used to fit the Gaussian curves. If None, the width is set to 1.0 in the normalized unit.
return_gaus_fit – bool, default False If True, the Gaussian fit to each peak is also returned.
use_kde – bool, default False If True, KDE is used to find the peak location after the Gaussian fit.
kde_bandwidth – float, default None The bandwidth of the KDE in the unit of arr. If None, the bandwidth is set to 0.05 in the normalized unit.
- Returns
If return_gaus_fit is False, returns a 1D array of the peak positions xpeaks, sorted from left to right; if return_gaus_fit is True, returns a tuple (xpeaks, gpars), where gpars contain the Gaussian parameters for each peak.
- fit_fast_total(side, position_range=None, find_peaks_kwargs=None)¶
Fit and update
self.cfast_total.- Parameters
side ('L' or 'R') – The side to fit.
position_range (list of 2 floats, default None) – The range of positions to fit . If None, use the default ranges. For left side, the range is [-100, -30]; for right side, the range is [30, 100].
find_peaks_kwargs (dict, default None) – The keyword arguments for
find_topN_peaks().
- Returns
cfast_total – The fitted parameters.
- Return type
dict
- value_assign(side)¶
Value-assign a PSD value to each entry.
Assigns gamma to 0 and neutron to 1. Values in between, e.g. 0.5, would mean that the algorithm has a hard time confidently distinguishing between gamma and neutron. However, values that are far from the assigned values, e.g. 10.0 or -10.0, are likely to be noise too. So when trying to select a particle, it is better to specify a range of assigned values, VPSDs, e.g. [-1, 0.5] for gamma and [0.5, 2] for neutron.
Of course, this function is only assigning the PSD value based on information from one side of the NW bar, which does not give very good neutron-gamma separation. Also, hit position information is not used at all. Eventually, the method PulseShapeDiscriminator.fit() would provide a better PSD parameter that is built on top of this one-sided VPSD parameter.
- Parameters
side ('L' or 'R') – The side of the NW bar to do the value-assignment.
- position_correction()¶
A function that maps (vpsd_L, vpsd_R, pos) to (ppsd, ppsd_perp)
- fit()¶
To calculate the pulse shape discrimination parameters.
This is a wrapper for multiple functions. If you run into any bugs and need to debug the program, it is recommended to run the individual functions one by one.
- static figure_of_merit(arr, **find_peaks_kwargs)¶
Calculate the figure-of-merit that quantifies the two-peak separation
The formula is F.O.M. = |x0 - x1| / (FWHM0 + FWHM1), which is standard adopted in many literature on the subject of pulse shape discrimination. One slight modification here is that, instead of using the actual FWHM, we estimate it by first fitting a Gaussian around the peak, then take FWHM to be ~2.3548 times sigma, the standard deviation.
- property _run_hash_str¶
Returns a string that uniquely identifies the runs.
- save_parameters(path=None)¶
Save pulse shape discrimination parameters as a JSON file.
By default, this function saves the parameters to the database as a JSON file. An example path would be: $PROJECT_DIR/database/calib_params/run-4082-4123-ha88b0/NWB-bar01.json
- Parameters
path (str or pathlib.Path, default None) – The path to save the parameters. If None, the parameters will be saved to the default database.