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, ...)

position_correction()

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_vetowall_coincidences([df])

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_range

database_dir

ft_breakpoint1

ft_breakpoint2

light_GM_range

min_samples_gamma

min_samples_neutron

pos_range

root_files_dir

x_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_executor and self.interpretation_executor. Each executor is assigned with a thread pool of size max_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, and time_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.bar and self.df will 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 in self.feature_scaler. This allows for denormalization later on.

Parameters

df (pandas.DataFrame, default None) – The dataframe to normalize. If None, the dataframe in self.df is 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 attribute self.feature_scaler will 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.df is 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.df is 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.