configExample.cfg

###############################################
#                                             #
# ModuleCalibration configuration file v1.0.8 #
# Last version date 27 Mar 2018               #
#                                             #
###############################################

# This is an example of configuration file for ModuleCalibration
# To use the configuration file, run
#
# ModuleCalibration -c <configuration file name> <input file 1> [input file 2] ...
#
# ModuleCalibration runs on the input files and produces a TTree that then uses for the analysis. Since this operation
# has to be repeated every time, but in principle is always the same if no import parameter is changed, there is the alternative option
# to save the TTree produced at the end of the analysis, by providing a saveAnalysisTreeName. This TTre can be loaded next time by
# running ModuleCalibration without input files, and setting loadAnalysisTreeName  to the TTree file name.

# All configuration keys are listed in this file. Some are mandatory, some are optional. When a key is optional,
# a default value is specified in the description. All key without a default option are mandatory.

##############################
# Parallelization            #
##############################
# keys that can be used for parallelization
# they override the corresponding keys
# std::string parallelMPPC           // single MPPC to be analyzed    - default = 0
# int parallelCrystal                // single crystal to be analyzed - default = -1
# std::string parallelOutput         // output file prefix            - default = 0

##############################
# Input/Output               #
##############################
# std::string chainName              // name of the ttree in each file of the input tchain       - default = adc
# std::string output                 // name of the output file WITHOUT the .root (extension will be added by the program)
# int digitizerTotalCh               // total number of digitizer channels                       - default = 32
# int digitizerType                  // type of digitizer. 0 = desktop, 1 = vme                  - default = 0
# int amplitudeData                  // for digitizerType = 1, specify if amplitude data has been recorded. By default the latest DAQ version always writes the amplitude leaves in the output files. They are filled with 0 if te acq was not computing amplitude, otherwise they carry meaningful data. Anyway old DAQ did not write any amplitude leaves, so the program would crash looking for them. Hence, amplitudeData is set to 0 by default.
# bool saveAnalysisTree              // whether to save the TTree produced for the analysis or not - default = 0
# std::string loadAnalysisTreeName   // name of the analysis TTree to load
# std::string saveAnalysisTreeName   // name of file where to save the analysis TTree
chainName = adc
output    = output
digitizerTotalCh = 32
digitizerType = 0


##############################
# Structure                  #
##############################
## These values describe the geometrical structure of the crystal array and of the detector array:
# int ncrystalsx               // number of crystals in x direction per SiPM
# int ncrystalsy               // number of crystals in y direction per SiPM
# int nmppcx                   // number of SiPMs in x direction per MPPC
# int nmppcy                   // number of SiPMs in y direction per MPPC
# int nmodulex                 // number of MPPCs in x direction
# int nmoduley                 // number of MPPCs in y direction
# float moduleLateralSideX     // half lateral side of the module (useful for excluding weird u-v results)
# float moduleLateralSideY     //
ncrystalsx = 2
ncrystalsy = 2
nmppcx     = 4
nmppcy     = 4
nmodulex   = 1
nmoduley   = 1
## The following are strings of data (comma separated) that define name, position and saturation parameter of the detector channels in the detector array
## They are in the form of a comma separeted list. same position in the list corresponds to the same detector.
## The lists MUST have the same number of elements
# std::string digitizer         // channels of input that will be analyzed
# std::string timing            // corresponding timing channels - needed only for digitizerType 1. By default if nothing is specified the same string as digitizer is taken
# std::string mppc              // for each channel, the relative label
# std::string pedestal          // measured value of pedestals for each channel, ADC channels. If not given, default to 0 for all channels - default = 0
# bool applyNoiseCut            // apply or not the noise cut - default = 1 (true)
# int noiseCutLevel             // number of channels that can be equal to 0 for an event to be accepted   - default = 0
# std::string noise             // measured sigma of pedestals (i.e. the noise) for each channel, ADC channels. If not given, default to 0 for all channels - default = 0
# float noiseSigmas             // how many sigmas of noise far from "0" to cut the dataset
# std::string plotPositions     // for each channel, its position in a Root NxN canvas
# keep in mind the ROOT numbering of canvas ,like the following for 4x4 array (resembling ROOT Canvas->cd() )
# 1  2  3  4
# 5  6  7  8
# 9  10 11 12
# 13 14 15 16
# std::string xPositions        // x positions of the sensor center, in mm
# std::string yPositions        // y positions of the sensor center, in mm
# bool applyTriggerCut          // apply trigger cut (channel in analysis has biggest charge in the event) - FIXME bad implementation - default = 1 (applied)
digitizer     = 0 ,1 ,2 ,3 ,4 ,5 ,6 ,7 ,8 ,9 ,10,11,12,13,14,15
mppc          = D1,C1,B1,A1,D2,C2,B2,A2,D3,C3,B3,A3,D4,C4,B4,A4
plotPositions = 1,5,9,13,2,6,10,14,3,7,11,15,4,8,12,16
xPositions    = -4.8,-4.8,-4.8,-4.8,-1.6,-1.6,-1.6,-1.6,1.6,1.6,1.6,1.6,4.8,4.8,4.8,4.8
yPositions    = 4.8,1.6,-1.6,-4.8,4.8,1.6,-1.6,-4.8,4.8,1.6,-1.6,-4.8,4.8,1.6,-1.6,-4.8

## SATURATION CORRECTION
# bool correctingSaturation    // true if saturation correction is applied, false if it's not
# int saturationFormat         // format of saturation data. 0 = ADC channels, 1 = Charge (in which case it will be converted to ADC ch by the program, using the chargeBinningADC value) - deafult = 0
# std::string saturation       // for each channel, the saturation parameter      - there is no default but values are MANDATORY ONLY IF correctingSaturation = 1
correctingSaturation   = 1
saturationFormat       = 0
saturation             = 6525,6355,6456,6042,6375,6566,6645,6191,6340,6337,6361,6200,6176,6314,5946,6416

## These values describe the physical parameters of the system
# double crystalx               // Length of individual crystals in mm, x direction        - default = 1.53
# double crystaly               // Length of individual crystals in mm, y direction        - default = 1.53
# double crystalz               // Length of individual crystals in mm, z direction        - default = 15
# double chargeBinningADC       // Charge binning of ADC in Coulomb                        - default = 156e-15
# double esrThickness           // thickness of separation between crystals, in mm         - default = 0.07
crystalx         = 1.53
crystaly         = 1.53
crystalz         = 15
chargeBinningADC = 160e-15
esrThickness     = 0.07


##############################
# Histograms                 #
##############################
## These values control the limits and binning of histograms involved in the analysis
# int histo1Dmax                // max of the 1D charge histograms (in ADC channels)                 - default = 25000
# int histo1Dbins               // number of bins of the 1D charge histograms                        - default = 250
# int histoLYmax                // max of the 1D LY histograms (in Ph/MeV)                           - default = 20000
# int histoLYbins               // number of bins of the 1D LY histograms                            - default = 500
# int histo2DchannelBin         // number of bins of the 2D flood histograms, for single channels    - default = 250
# int histo2DglobalBins         // number of bins of the 2D flood histograms, for entire module      - default = 1000
# int histo3DglobalBins         // number of bins of the 3D flood histograms, for entire module      - default = 100
# float histo3Dmin              // min of w coordinate in 3D plots                                   - default = 0
# float histo3Dmax              // max of w coordinate in 3D plots                                   - default = 1
# int wHistogramsBins           // number of bins of the w histograms                                - default = 250
# float photopeakFitRangeMin    // photopeaks will be fitted from peaK_pos-photopeakFitRangeMin*peak_sigma - default = 1.2
# float photopeakFitRangeMax    // photopeaks will be fitted up to peaK_pos+photopeakFitRangeMan*peak_sigma - default = 1.2
# float photopeakSigmasMin      // how many sigmas far from mean is the lower bound of cut on photopeak  - default = 2.0
# float photopeakSigmasMax      // how many sigmas far from mean is the upper bound of cut on photopeak  - default = 4.0
# float spectrumSearchMin       // limits for peak search in 1d spectra BEFORE DOI CORRECTION in ADC ch  - default = 1
# float spectrumSearchMax       // limits for peak search in 1d spectra BEFORE DOI CORRECTION in ADC ch  - default = histo1Dmax

histo1Dmax        = 25000
histo1Dbins       = 250
histo2DchannelBin = 250
histo2DglobalBins = 1000
histo3DglobalBins = 100
wHistogramsBins   = 250


##############################
# Analysis parameters        #
##############################
#### Parameters of the analysis
# double nclock                  // number of clock samples from beginning of acquisition that will be ignored                                - default = 0
# bool comptonAnalysis           // whether to perform or not the compton recovery analysis part.                                             - default = 0
# float expectedEnergyResolution // expected energy resolution @photopeak. If 0 or not given, some wide values are used (0.25 and 0.12)       - default = 0
# float thresholdKev             // low global energy cut, if you want to get read of noise.   -default = 1.0
nclock = 0
comptonAnalysis = 0
expectedEnergyResolution = 0

### CHANNELS OR CRYSTALS OFF
## csv list of channels and/or crystals that will not be analyzed
# std::string mppcOFF            // list of channels (by label) that will not be analyzed
# std::string crystalOFF         // list of crystals (by number) that will not be analyzed
# mppcOFF    = A1,D2,C4
# crystalOFF = 12,13

### CHANNELS INVOLVED
##  which channels are involved in the calculation of u,v,w. It can be all channels of input, or just trigger channel plus neighbours
# bool usingAllChannels         // whether to use the sum of all channels to compute u and v (true = 1) of just the neighbours (false = 0). Deafult to 0.
# bool wAllChannels             // whether to use the sum of all channels to compute w (true = 1) of just the neighbours (false = 0). Deafult to 0.
# bool usingAllChannelsForEnergySpectra // whether to use all digitizer channels for energy spectra (1) or just neighbours (0) - default = 0
usingAllChannels  = 0
wAllChannels      = 0
usingAllChannelsForEnergySpectra = 0

### DOI CORRECTION OF ENERGY
## A DOI correction of energy is computed if the module has DOI capability. This means that the energy used to fill the chage spectrum of each crystal is corrected using the relation
## charge vs. w that is found in a scatter plot of charge and w for the events of that crystal, selecting only 511 KeV data. This compresses the photopeak and provides better energy resolution
## a scatter plot is build with such data, then a simple linear relation is found
# bool correctingForDOI         // true if the energy correction using DOI info is computed                                          - default = 0
# float peakSearchRangeMin      //lower limit for search of 511KeV peak AFTER DOI CORRECTION, in ADC ch - wide limitation to help peak search             - default = 0
# float peakSearchRangeMax      //upper limit for search of 511KeV peak AFTER DOI CORRECTION, in ADC ch - wide limitation to help peak search             - default = histo1Dmax
# float wThreshold              // Threshold for  on w plot hight to find the w plots limits. Fractional value (1 means 100%)        - default = 0.1
# double energyCorrectionMin    // once the wmin and wmax are found for each w histo, choose at which point to start and             - default = 0.25
# double energyCorrectionMax    // to stop the linear fitting(as percentage from min to max)                                         - default = 0.75
# float marginWZgraph           // distance from crystal limit for calculation of beginW and endW [mm] - default = 0.1
correctingForDOI         = 1
wThreshold               = 0.1
energyCorrectionMin      = 0.25
energyCorrectionMax      = 0.75


##############################
# Crystal Separation         #
##############################
## These values control the clustering algorithm that separates the crystals in 3D
## The algorithm works as follows (performed on each mppc data):
## it takes the 3D plot of data beloging to the current detector (it means a 3D histogram of u-v-w coordinates for all the events assigned to a specific
## detector. An event is assigned to a specific detector if the signal of that detector is the highest in the event)
## it finds the voxel with maximum amount of events in the 3D histogram
## sets a threshold equal to the numbers of events in that voxel divided by clusterLevelPrecision
## starting by that voxel, checks the 26 voxel around to see if the number of events in them is above the threshold
## for the ones above threshold, checks in the same way the 26 voxel around (skipping of course the ones already checked)
## goes on until there's no voxel above threshold left. the collection of voxels above threshold found are the first crystal volume
## then it excludes the voxel of first crystal, find the new maximum, and repeat the procedure keeping the same value of threshold.
## the procedure goes on until ncrystalsx by ncrystalsy volumes are found. If less volumes are found, the threshold is increased and the entire
## procedure is started over

## Global values, i.e. set for all the detectors
# bool apply3Dcut               // apply or not the 3D cut - default = 1 (true)
# int histo3DchannelBin         // number of bins of the 3D flood histograms, for single channels    - default = 100
# int clusterLevelPrecision     // precision of the level search when separating the cluster of 3D points - default = 10
# double clusterVolumeCut       // percentage of total non-empty bins in 3D plot. if one volume is below this percentage, the separation mask is discarded and a new one is searched for     - default = 0.001
histo3DchannelBin     = 100
clusterLevelPrecision = 10
clusterVolumeCut      = 0.001

## Specific values for detectors, if needed
## They are in the form of a comma separeted list. same position in the list corresponds to the same detector.
## The lists MUST have the same number of elements
## By default these are empty, and if left empty no specific value will be used
# std::string specificMPPCname    // labels of the MPPCs for which you want to specify a different value for the 3d parameters, separated by commas         - default = ""
# std::string specificBin         // number of bins of the 3D flood histogram for the specific channels set above, in specificMPPCname, separated by commas - default = ""
# std::string specificPrecision   // clusterLevelPrecision for the specific channels set above, in specificMPPCname, separated by commas                    - default = ""
# std::string specificCut         // clusterVolumeCut for the specific channels set above, in specificMPPCname, separated by commas                         - default = ""
# specificMPPCname   = A1  ,B1
# specificBin        = 50  ,40
# specificPrecision  = 20  ,25
# specificCut        = 0.01,0.02

##############################
# Summary Histograms         #
##############################
# double DoiResolutionVsIJmax            // max of the 2d DoiResolution values plot (starts from 0) in mm               - default = 10
# double EnergyResolutionVsIJmax         // max of the 2d EnergyResolution values plot (starts from 0)                  - default = 0.3
# double LYvsIJmax                       // max of the 2d Light Yield values plot (starts from 0)                       - default = 40000
# double PeakPositionVsIJmax             // max of the 2d PeakPosition values plot (starts from 0) in ADC channels      - default = 12000
# DoiResolutionVsIJmax       = 10
# EnergyResolutionVsIJmax    = 0.3
# LYvsIJmax                  = 40000
# PeakPositionVsIJmax        = 12000




#####################################################################################################################################################################




#################################
#                               #
# SPECIAL RUNS / ANALYSIS       #
#                               #
#################################


##############################
# DOI CALIBRATION and RES    #
##############################
### DOI CALIBRATION
## This type of run is performed in order to find the DOI calibration curve. It can be done with
## top (default, no key has to be set because it's the standard acq mode), lateral or background irradiation
# bool lateralRun                 // whether this is a lateral irradiation run or not    - default = 0
# bool backgroundRun              // whether this is a background run or not             - default = 0
# double lambda511              // Attenuation length of gammas in the crystals, in mm     - default = 12.195
lambda511                 = 12.195
lateralRun                = 0
backgroundRun             = 0
## only for backgroundRun, the user can set a low energy cut for the spectra
# float userBroadCut              // if in backgroundRun, cut to get rid of low energy events is not done on photopeak search but by user input    - default = 0.0

### DOI RESOLUTION - ALTERNATIVE COMPUTATION METHOD
##
# bool calcDoiResWithDelta            // alternative calcolation of doi res, based on deltas. only if it's usingTaggingBench      - default = 0
# std::string calcDoiFileName         // name (and path if not in this folder) of calibration_params.txt                          - default = ""
# int pointsFromDoi                   // points measured in file calcDoiFileName. this is MANDATORY if calcDoiFileName is specified!  - default = 0
calcDoiResWithDelta = 0

### DOI RESOLUTION - CALIBRATION CURVES METHOD
## In this case, the DOI RES is calculated by taking the doi calibration curve from a
## standard top (or lateral or bg) calibration run, and running modulecalibration on
## a joint dataset of all the doi tagging scan. The DOI resolution is the width of the histogram
## of DOI position calculated from DOI calibration curve for a specific w and the "real" z position
## given by the tagging
# bool calcDoiResWithCalibration            // enable this method of calculation  -default = 0
# std::string calibrationFileName           // name of the file with calibration curves, produced by modulecalibration on a standard top (or lat or bg) irradiation    - default = 0
calcDoiResWithCalibration = 0
calibrationFileName       = calibration.root


##############################
# Tagging Bench              #
##############################
### TAGGING BENCH
## This type of run is performed with an external tagging crystal, to demonstrate the DOI capability of the array
# bool usingTaggingBench          // true (1) if the input is using tagging bench, false (0) if not               - default = 0
# bool taggingForTiming           // true if tagging bench is for timing purpose                                  - default = 0
# float pedestalTag               // value of pedestal in tagging crystal, in ADC channels                        - default = 0
# bool cuttingOnTagPhotopeak      // if true, all the data of the module is considered only if the
#                                 // event is in the photopeak of the tagging crystal. This is generally true
#                                 // in tagging bench in standard use, but can be disabled                        - default = 1
# int doiColumnOffset             // for DOI output, fix the column i by adding this quantity                     - default = 0
# float taggingPosition           // position of the tagging bench in mm                                          - default = 0
# int taggingCrystalChannel       // input channel where the tagging crystal information is stored                - default = 16
# int taggingCrystalTimingChannel       // input timing channel where the tagging crystal information is stored                - default = 16
# std::string digiChannelsForDoi  // csv list of the channels illuminated by the DOI tagging setup                - default = "8,9,10,11"
# int taggingCrystalBins          // tagging crystal spectrum: number of bins                                     - default = 1200
# float taggingSpectrumMin        // tagging crystal spectrum: histogram min                                      - default = 0.0
# float taggingSpectrumMax        // tagging crystal spectrum: hitogram max                                       - default = 12000.0
# int taggingPeakMin              // min range of tagging crystal photopeak, in ADC channels, to help TSpectrum   - default = 0
# int taggingPeakMax              // max range of tagging crystal photopeak, in ADC channels, to help TSpectrum   - default = 0 (therefore will be set to taggingSpectrumMax)
# float tagCrystalPeakResolutionFWHM // FWHM energy resolution of tag phopeak (remember, not corrected for saturation) -default = 0.07
# float TaggingPhotopeakSigmasMin  // how many sigmas far from mean is the lower bound of cut on Tagging photopeak  - default = 1.5
# float TaggingPhotopeakSigmasMax  // how many sigmas far from mean is the upper bound of cut on Tagging photopeak  - default = 2.0
# float tagFitLowerFraction       // lower limit of tag photopeak, in fraction of photopeak position
# float tagFitUpperFraction       // upper limit of tag photopeak, in fraction of photopeak position
# bool tagEdgeCalculation         // whether the user wants the program to calculate the area of photopeak for
#                                 // crystals, normalized to the entries selected in the tagging photopeak. This
#                                 // is used for finding the edge of the matrix in the coordinates of tag bench   - default = 0

usingTaggingBench = 0


##############################
# TIMING ANALYSIS            #
##############################
# bool essentialOnly                // do only essential plots, to minimize computation time - default = 1 (true)
# float approximateTDCbinning       // approximate TDC binning in ps. used for all channels if the calculateTDCbinning is false, and for ch
#                                   // where there's not enough statistics for all the other channels                                     - default = 35.0
# bool  calculateTDCbinning         // whether to calculate or not the TDC binning for each channel from input file. if not, approximateTDCbinning is set to all - default = 0
# int   TDCcalculationEntries       // how many entries of the input file will be used to calc the TDC binning of the channels. default to 0 means USE WHOLE FILE  - default = 0
# int   CTRbins                     // number of bins in CTR plots.                                                                       - default = 500
# float CTRmin                      // min in CTR plots                                                                                   - default = -5e-9
# float CTRmax                      // max in CTR plots                                                                                   - default =  5e-9
# float minDeltaForFT               // min value of  [max(FineTimeX) - min(FineTimeX)] to accept the calculation of TDC binning for a channel. otherwise approximateTDCbinning is used - default = 10.0
# int DeltaTimeBins                 // Bin in the plots T_cry - T_neighbour_channel          - default = 500
# float DeltaTimeMin                // Min in the plots T_cry - T_neighbour_channel          - default = -5e-9
# float DeltaTimeMax                // Max in the plots T_cry - T_neighbour_channel          - default = 5e-9
# int WrangeBinsForTiming           // number of division of the range of w (from wmin to wmax inside the crystal) for calculation of the time correction graphs - default = 10
# bool smearTaggingTime             // whether to smear the time stamp of external tagging. ONLY FOR SIMULATIONS, where the tagging time stamp is always 0 (i.e. the gamma emission time) - default = 0
# float SigmaTimeTag                // sigma for the smearing of tagging time [ps]. it's the time resolution of an hypothetical external short crystal + fast sipm - default = 42, which corresponds to Hamamatsu MPPC + 2x2x3 m3 LSO-Ca codoped crystal
# bool timingCorrection             // perform or not the timing correction (for example, it could make no sense to perform it in polished arrays) - default = 1
# bool timingCorrectionForPolished  // produce the plots for the simple combination of timestamps that can be done for polished crystals (i.e. when DOI info is not available) - default = 1
# int TimeCorrectionFitFunction     // function to be used on time correction slice fitting. 0 = crystalball, 1 = gauss+exp
# std::string excludeChannels       //channels to exclude from time correction (will affect only polished correction, the others have to be specified in timeAnalysis). It's expressed in terms of charge digitizer channels number, so it corresponds to the value of key "digitizer" for the channel(s) that needs to be excluded - default = ""
# int neighCTRbins                  // number of bins in neighbour CTR plots - default = 500
# float neighCTRmin                 // min  of neighbour CTR plots - default = -1e-9
# float neighCTRmax                 // max of neighbour CTR plots - default = 10e-9
# bool lowStat                      // if low statistics, apply fits to slices - default 1 (true)

##############################
# SATURATION RUN             #
##############################
## SATURATION RUN
## This type of run is performed in order to find the saturation curve per each detector.
## It can be done with different sources and/or with just background irradiation
# bool saturationRun              // whether this is a saturation run or not                               - default = 0
# bool backgroundSaturationRun    // if this is a saturationRun, whether it is a background run or not     - default = 0
saturationRun             = 0
backgroundSaturationRun   = 0
# float histoSingleChargeMax         // max in the histograms of charge for saturationRun. if set to 0, it is calc from the program       - default = 0
# float histoSingleChargeBin         // binning of histograms of charge for saturationRun. if set to 0, it is calc from the program       - default = 0
# float histoSumChargeMax            // max in the sum histograms of charge for saturationRun. if set to 0, it is calc from the program   - default = 0
# float histoSumChargeBin            // binning of sum histograms of charge for saturationRun. if set to 0, it is calc from the program   - default = 0
## peak searc in saturation runs
# bool performSaturationPeakSearch   //perform of not satuartion peak search (if either saturationRun or backgroundSaturationRun are true) - default = 1
# float saturationPeakFractionLow    // lower limit for saturation peak fitting, expressed in fraction of peak position. limit will be = (peak - peak*saturationPeakFractionLow)  - default = 0.06
# float saturationPeakFractionHigh   // upper limit for saturation peak fitting, expressed in fraction of peak position. limit will be = (peak + peak*saturationPeakFractionHigh) - default = 0.06
## cvs list of specification for peaks to look for
# std::string saturationPeakEnergy   // energy of the peaks, in KeV
# std::string saturationPeakMin      // min position for peak search, in Coulomb (you need to look at the plots first)
# std::string saturationPeakMax      // max position for peak search, in Coulomb (you need to look at the plots first)


##############################
# LIGHT YIELD                #
##############################
## LIGHT YIELD COMPUTATION
# bool lightYieldComputation       //whether to perform or not the light yield calculation.                - default = 0
# double qe                     // Quantum Efficiency of the MPPC (fraction, 1 = 100%)     - default = 0.35
# double gainMPPC               // Gain of the MPPC (average gain of the N SiPMs)          - default = 1.25e6
# double sourceMeV              // Energy of gamma source in MeV                           - default = 0.511
lightYieldComputation     = 0
qe                        = 0.35
gainMPPC                  = 1.25e6
sourceMeV                 = 0.511


##############################
# SIMULATION                 #
##############################
### SIMULATION
# bool usingRealSimData           // whether the data come from a simulation or not
usingRealSimData          = 0


##############################
# MISC                       #
##############################
# bool dumpImages =        // dump images of some plots for quick check - default 0 (false)