Analysis scripts

Pflib has a wide variety of data analysis and plotting Python scripts, located in the ana/ directory. These scripts serve to interpret the data gathered via pftool DAQ functions. This page contains the documentation for some of them.

Glossary

• RMSD - root-mean-square deviation, equivalent to standard deviation. In the scripts often referred to as RMS;

Mean pedestal evaluation

The pedestal/averagesplot.py script allows the user to determine the mean pedestal values across link 0 (channels 0-35) and link 1 (channels 36-71). The code also calculates the RMSD across samples of each channel and across each link. For example, if the pedestals were taken with a 100 samples per channel, the channel-wise RMSD would be the stddev of the 100 samples. The link-wise RMSD would be the stddev of the mean pedestal values of each link. The link-wise RMSD can be saved as a csv file.

Both the mean pedestal values and the channel-wise RMSD can be plotted for each link, as seen in examples below:

Manual

To engage with the different functions of the script, the user needs to provide an initial run setting. These can be found by running python3 averagesplot.py -h. The current settings are:

• -pd - Path to directory for saved figures;
• -lc - Mark the first pedestal file as pre-lowering and second as post-lowering;
• -rms - Calculate and save the RMS of the mean pedestals for each link - provide a file path.

An example that engages all the settings would be: python3 averagesplot.py [pedestals.csv] [pedestals_lowered.csv] -pd [/plot_directory/] -lc -rms [link-wise-RMSD-results.csv]

---

Time-scan evaluation

The charge/time-scan-evaluation.py is designed for analysis of both peak and pedestal ADC alignment in time-scan data. The peak-ADC alignment serves to ensure all channels show a similar ADC response to the same CALIB, i.e. that they have the same gain. Moreover, the script provides the option to track the pedestal alignment from the time-scan data (pedestals assumed to be the minima). This can be used for comparison with the pedestal-alignment results. Similarly to mean pedestal evaluation, the script uses RMSD as the primary evaluation metric. The link-wise RMSD (stddev of mean peak-ADC values across each link) can be calculated and saved to a csv file, while the channel-wise RMSD (stddev of N ADC-samples taken on each channel) is plotted.

Ideally, time-scan data files taken on all channels, across various CALIB values and with multiple samples are provided for analysis. One file should contain only one channel and CALIB, but can (and preferably should!) contain multiple samples.

As an example, the peak-ADC alignment and their channel-wise RMSD results for both links, preCC, could look like this:

Manual

To engage with the different functions of the script, the user needs to provide an initial run setting. These can be found by running python3 time-scan-evaluation.py -h. The current settings are:

• -p - Plot results;
• -tp - Track pedestal values (minima) instead of peaks;
• -rms - Calculate the RMS of the mean-ADC-peak distribution across each link (link-wise RMSD);
• -pd - Figures directory path. If not provided, figures are not saved automatically;
• -csv - Save the RMSD results to a csv with the given path (-h says "fit results" right now, it's a mistake);

An example that engages all the settings would be: python3 time-scan-evaluation.py [time-scan-data.csv or time-scan-data-folder/*] -p -tp -rms -pd [/plot_directory/] -csv [link-wise-RMSD-results.csv]

---

Time-scan outlier identification algorithm

Algorithm types

The charge/outlier_scan.py is an algorithm for identifying potential anomalies in time-scan data. The script is still fairly experimental, but has been successfully used to find various irregularities in the time-scan ADC data, like in the figure below.

The user can choose one of three available algorithm options, with the default "CLUSTER" scan performing the best by far during initial testing (low false-positive rate). Each algorithm option (or "scan") has a different "outlier" definition. Each scan requires at minimum 10 samples to be taken during the time-scan. The different scans are described below:

• CLUSTER scan: Designed to divide the sample-distributions at each phase into clusters. First, the algorithm finds the mode (most frequent ADC value) of the sample-distribution. The script then splits into two loops, each moving up and down by one ADC unit from the mode. Each loop marks samples with equal ADC values. If no sample is found within a range of two to five ADC units from the last identified sample, the algorithm marks the last sample as the lower/upper-end of the ‘true’ cluster (containing the mode). The samples after that gap are then marked as ‘potential outliers’. Similarly, when no sample is found for more than five ADC units, the samples after the gap are marked as ‘outliers’. Furthermore, any new clusters found after the (potential) outlier-cluster are marked as ‘outliers’ themselves. Gaps of one ADC unit are ignored to account for natural fluctuations.

• DELTA-ADC scan: This method monitors the differences in ADC values (∆ADC) of subsequent phases of a reconstructed ‘sample-pulse’. The samples first categorized by their measurement order within each phase. They are then coalesced into a single sample-pulse. For example, each third ADC-sample of every phase is taken out to a separate array, making up the third sample-pulse. Then, each phase is assigned a ∆ADC value, taken by subtracting the ADC value of the previous phase from its ADC value. The first phase is assigned a ∆ADC value of 0.

• STDEV scan: Instead of treating samples as part of the same pulse, this method focuses on the distribution of ADC values at each phase, and identifies outliers based on the standard deviation (σ). Considering each phase one-by-one, the algorithm finds the sample-distribution mean and σ. Samples are marked as outliers when their corresponding ADC value is at least 3σ away from the mean.

After choosing an algorithm, the results can be saved to a csv file. The code now allows for analysis of multiple time-scan data files, provided each contains at most one channel and one CALIB value. This can be done with "bulk evaluation" (see manual).

Plotting

The user is provided with range of plotting tools for outlier analysis. These are as follows:

• CLUSTER - Allows the user to see all the samples plotted together for a specific channel and CALIB value.

• SINGULAR - Illustrates a "reconstructed sample-pulse", as defined in the DELTA-ADC scan description, with marked outliers.

• EVALUATION - Only works with --bulk_evaluation. Shows a histogram of outlier frequency and/or total count. The outlier frequency is defined as the fraction of samples per channel (with a specific CALIB value) with one or more outliers identified. For example, a channel with a 100 samples, where 10 of the samples contain a single outlier ADC value, would have a frequency of 0.1.

• --phase_analysis - Though not a "plot type", the phase analysis function produces a histogram of the time-points and phases, at which outliers were identified. This option only works when not performing bulk evaluation (I think).

Manual

The initial settings for the script are as follows:

• -s - Number of samples per phase (sample number chosen in the time-scan);
• -st - Choose a method for outlier identification: CLUSTER, DELTA-ADC, STDEV. Default: CLUSTER;
• -t - Set the threshold ADC-value for a DELTA-ADC identification-scan (-h says "STDEV scan", which is a mistake);
• -ph - Perform and plot phase analysis of the outliers (include -pd for plot directory path);
• -be - Perform analysis to evaluate multiple channels and CALIBs in terms of outliers found;
• -p - Plot results. Available types: CLUSTER, SINGULAR, EVALUATION;
• -pd - Figures directory path. If not provided, figures are not saved automatically;
• -csv - Save the scan results to a csv with the given directory path;

As an example, if I want to analyse time-scan data from a single channel and CALIB value, I would use: python3 outlier_scan.py [time-scan-data.csv] -s 100 -st CLUSTER -ph -p CLUSTER -pd [/plot_directory/] -csv [outlier_results.csv]. If, instead, I wanted to analyse all data from 72 channels, I would use: python3 outlier_scan.py [data_folder/*] -s 100 -st CLUSTER -be -p EVALUATION -pd [/plot_directory/] -csv [outlier_results.csv].