ANASEN Calibration is a package capable of performing silicon detector zero-offset, gain-matching, and energy calibration for detectors in the ANASEN array. It also performs front-back hit matching and provides a simple and (hopefully) inuitive data structure. AnasenCal requires ROOT (the CERN data analysis framework) as a dependency. To build AnasenCal fork or clone this repository and use the given Makefile, running the command make from within the AnasenCal directory. To clean a build run make clean.

Different stages of the analysis are run by calling different options at the commandline. The general execution format is: ./bin/anasencal --<option> <input file>, where the input file is of the format given by the example (input.txt) in the repository.

Different options are as follows: 1. organize-data : converts data to the AnasenEvent format specified in DataStructs. 2. zero-offset : calibrates the zero offset of each channel using pulser data 3. gain-match : performs all gain-matching steps in a single-shot (not recommended) 4. gain-match-backs : performs first step of gain-matching by aligning all back channels within each detector 5. gain-match-updown : performs second step of gain-matching by aligning the SX3 front upstream and downstream channels 6. gain-match-updown : performs last step of gain-matching by aligning front channels to back channels 7. calibrate-energy : calibrates the energy of each channel using alpha data 8. apply-calibrations : applies calibrations to a dataset, generating a new calibrated file

These options are listed above in the order that they should be run for best results (excluding gain-match, which should not be used unless you're very confident that you know what you're doing).

To see this list, one can always call ./bin/anasencal --help.

In general, data coming from the nscldaq Readout is formated on a ASIC motherboard-chipboard-channel basis. This is good for online and quick analysis, because it requires little external input to generate simple data heuristics. However, for more in depth analyses such as the full calibrations, it becomes a hinderance to think in terms of chipboard-channels. A much better basis upon which to organize the data is by physical detectors, as these are the groups of channels which we want to associate together. To this end, data must be converted from raw motherboard channel arrays to AnasenEvent structures. To save AnasenEvents to a ROOT tree, a ROOT dictionary must be implemented. The Makefile handles generation, compilation, and linking of the dictionary, however it should be noted that to use data generated by the AnasenCal program in another program, it is necessary to properly include and link this dictionary in the external code. In practice, this is not really an obstacle. For a ROOT macro, make sure to #include the DataStructs.h file from this repository and then include the line R__LOAD_LIBRARY(<fullpath_to_dictionary_lib>) where the fullpath is the fullpath to the shared library libAnasenEvent_dict.so generated by the Makefile (by default located in the objs directory). Examples of such macros can be found in the macros directory. For use in independently compiled code, one can simply again include the header where necessary and then use the shared library to dynamically link. Alternatively, one could regenerate the dictionary using similar methods to those outlined in the Makefile. If you decide to move the shared library, note that you must also move the .pcm file to the same directory!

ANASEN makes use of ASIC-style electronics. These electronics pose many advantages, particularly that discrimination parameters may be set on a per channel basis. However, this comes at the cost that the zero-value on the ADC scale is not fixed over the whole channel-range, and must be calibrated to compare ADC energy values from channel-to-channel. These calibrations are typically done using pulser data, since they are intrinsic to the ASIC electronics themselves, rather than the associated detector.

In practice, this is done by using the TSpectrum library in ROOT, which can scan for peaks in a spectrum, and return the centroid of these peaks. The pulser voltage values are then given and the plot of centroid vs. voltage is fitted with a line. The offset is taken from this fit, and stored in a text file as a list of global channels and their offsets.

The zero offset calibration is always the first step of any ANASEN calibration.

Gain-matching in general refers to the unification of the energy (ADC) scales of various detector channels. In ANASEN there are three gain-matching stages: 1. Back gain-matching 2. SX3 Upstream-downstream gain-matching 3. Front-Back gain-matching

Back gain matching is the stage at which, within each detector, all of the back channels have their ADC energy scales matched. In practice this is done using source calibration data, where there are well defined peaks with known energies. A specific back channel for each detector is chosen (typically the same channel number for all detectors of a given type), and all other back channels within a given detector are matched to that channel. Again, TSpectrum is used for automated peak identification. This is the first gain-matching stage, as the subsequent stages rely up on all back channels being uniform in scale. Each back channel is then plotted against its matching channel, and fitted with a line. Again, parameters are saved to a text file.

Micron SX3 silicon detectors have front strips which are resistive strips; this allows for positional information to be recovered from the charge (ADC energy) distribution between the two ends of the strip (referred to as upstream and downstream based on the orientation in ANASEN). In order to retrieve this information, the scales of the upstream and downstream channel for a given front strip must be matched. To achieve this, the following scheme is implemented: a good back channel hit is identified, and then a upstream-downstream pair is identified within the same detector as the back hit. The upstream and downstream energy is normalized to the back energy, and then these normalized eneriges are plotted against each other and fit with a line. This line is then corrected such that it follows a y=-x+1 correlation (a hit at either extreme is equal to 1). These fit parameters are saved to a text file. Again, this is typically done with source calibration data, however it could be done with a larger data set as well.

The final stage of ANASEN gain-matching, front-back matching is where the front channels of a detector are made uniform in scale with the back channels of a detector. For SX3s this refers to matching the gain-matched sum of of the upstream and downstream channel with a back channel (these parameters are then associated with the upstream global channel). This is done by plotting a good front hit against a good back hit, and fitting with a line. Typically, this stage is done using a large data run from the experiment, this way the entire dynamic range of the expriment is considered in the gain-matching. Note that this stage (and the SX3 Up-Down stage) does not make any assignment of front-back channels in terms of good particle hit; that is, all possible front-back combinations which were not determined to be noise are plotted. The fitter is then relied upon to properly exclude outliers corresponding to mismatched front-back pairs (these mismatches are in general rare, as it is unlikely to occur that two particles hit a single detector within a single event). Again parameters are saved to a text file.

The final analysis stage, energy calibration is the conversion of the ADC energy scale to a MeV unit scale. This is done using source data, on a per channel basis. Again, TSpectrum is used to identify peaks, and known energy values are assigned. Peak ADC channel is plotted against known energy, and a linear fit is used to determine parameters. Parameters are then written to a text file. Currently, energy calibration requires that every stage of previous analysis be done beforehand... however this is not in general necessary. Especially as a quick diagnostic, it can be useful to do a "dirty" calibration using just the energy calibration, but this can be misleading and should not be attempted without caution.

Finally, once all of the calibration stages have been completed, the program can take a data set and apply the calibrations to it. The data is converted from the AnasenEvent format to the CalibratedEvent format. This conversion includes the application of all calibrations, as well as the assertion of a matched front-back channel. A matched front-back is where the front energy is determined to match the back energy within 20%. Note that the current implementation does NOT require both a front and a back! It only requires that a back channel be present, due to the difficulties encountered with SX3 fronts in the November 2021 7Be dataset. Again, the CalibratedEvent sturcture is included in the ROOT dictionary. See Organizing Data for more information on ROOT dictionaries.

This code is quite general to ANASEN experiments, however, there are several places where modifications may need to be made. TSpectrum requires searching parameters, referred to as sigma and threshold. These deterime what a "good" peak is in TSpectrum, and may need to be modified to best suit a given experiment (see TSpectrum documentation for more info). Additonally, source calibration energy values and pulser voltage values will almost certainly vary from experiment to experiment, and need to be modified in the code. In general, if you're using this programm, you should expect to need to dive into the source to have it run properly, as much of it can be experiment dependent.

Currently only compatible with Linux, MacOS in progress. Requires ROOT Data Analysis Framework; tested with ROOT6, milleage with all other versions may vary.