SW-Tutorial.md

@@ -16,13 +16,17 @@ The main components of the SW are:
 
 This macro converts the binary file.dat acquired by the Digitizer into a ROOT file (the TreeWave.root). This file is a TTree containing in different branches all the samplings and the temperature of the signals divided for different crystals.
 
+For the time being `/$HOME/foot_turin/Script/PythonScript/sw_standalone/datToRoot.py` has been used. It converted the file.dat generated by `CAEN v1742/40 `and `WaveDAQ` (standalone) digitizer. 
+
+**ATTENTION:** it doesn't work with file.dat generated by the GlobalDAQ. A further file will be uploaded.
+
 ## 2. Create n-tuple
 
 The second step is: `/$HOME/foot_turin/Script/PythonScript/sw_standalone/create_ntuple.py`.
 
 This class aims at processing all events (selected by the user) of the TreeWave.root, generating the major quantities required by the analysis (amplitude, charge, baseline, fit paramters, etc.) and saving them in n-tuples in a ROOT file. 
 
-Enabling the fit analysis the processing time could be quite long (several minutes). Thus, the idea of the code is to run this class one time, generate the n-tuples of all the signals quantities and leave the histograms generation to the next step (read_ntuple.py).
+Enabling the fit analysis the processing time could be quite long (several minutes). Thus, the idea of the code is to run this class one time, generate the n-tuples of all the signals quantities and leave the histograms generation managing to the step 3.
 
 ### Class methods list
 The list of the class methods are:
@@ -45,12 +49,12 @@ The list of the class methods are:
 ### How to run
 The class can be run through the `/$HOME/foot_turin/Script/PythonScript/sw_standalone/analyze.py` script. 
 
-This script need some POSITIONAL arguments:
-- the path of the input file (TreeWave.root)
+This script need some **POSITIONAL** arguments:
+- the path of the input file (`TreeWave.root`)
 - the number of start event
 - the number of the stop event
 
-and some OPTIONAL arguments:
+and some **OPTIONAL** arguments:
 
 - the list of the channel (i.e. the crystal ID number): `[-c]`
 - the sampling rate of the digitizer: `[-d]`
@@ -60,7 +64,7 @@ and some OPTIONAL arguments:
 - keyword to set the frequency for saving PDF waveforms: `[-s]`
 - path of the ouput folder for PDF figures: `[-p]`
 
-example:
+example from terminal:
 
 `> python analyze.py TreeWave.root 0 10000 -c 0 1 2 3 4 5 6 7 8 -d 1024 -b 12 -o fout_ntuple.root -f -s 1000 -p PulseWF`
 
@@ -71,7 +75,7 @@ Once all the signals quantities are stored in n-tuples, the class `/$HOME/foot_t
 In this class the event-selection is performed. The event-selection is based on three cut levels:
 1. Baseline RMS selection: signals with a baseline RMS greater than a threshold value are rejected
 2. χ$`^2`$ selection: signals with a χ$`^2`$ greater than a threshold value are rejected
-3. Bragg Peak selection (**only for pulse shape analysis**): only the signals with an amplitude within the range of the histogram peak are selected for the pulse shape analysis
+3. Bragg Peak selection: only the signals with an amplitude within the range of the histogram peak are selected for the pulse shape analysis. **Note:** only for pulse shape analysis**.
 
 Moreover this class manages the signal corrections. Three different correction can be applied:
 1. Temperature correction
@@ -79,10 +83,10 @@ Moreover this class manages the signal corrections. Three different correction c
 3. Crystals equalization
 
 ### Campaigns
-Different campaigns allow to choose the specific events-selection and signals-correction related to test beams under study.
+Different campaigns allow to choose the specific _events-selection_ and _signals-correction_ related to test beams under study.
 
 The campaigns are located in `$HOME/foot_turin/Script/PythonScript/sw_standalone/campaign/`. Each campaign directory contains three different files:
-1. Calibration.par: it contains for each crystal the crystal equalization values. Example:
+1. `Calibration.par`: it contains for each crystal the crystal equalization values. Example:
 ```
 [bgo_eq]
 #ch: Amp, charge
@@ -93,7 +97,7 @@ The campaigns are located in `$HOME/foot_turin/Script/PythonScript/sw_standalone
 ```
 **Note:** the temperature and the range correction values are deprecated.
 
-2. InitCut.par: it contains for each run the list of the events-selection values for each crystal. The file is composed by three sections, one per events-selection types. Example:
+2. `InitCut.par`: it contains for each run the list of the events-selection values for each crystal. The file is composed by three sections, one per events-selection types. Example:
 ```
 [rms_bas]
 #run: ch0, ch1, ...
@@ -117,7 +121,7 @@ The campaigns are located in `$HOME/foot_turin/Script/PythonScript/sw_standalone
 [...]
 ```
 
-3. Configuration.par: it is a configuration file where the user can select the type of events-selction or signals-correction that wants to enable/disable. Example:
+3. `Configuration.par`: it is a configuration file where the user can select the type of events-selction or signals-correction that wants to enable/disable. Example:
 ```
 EnableCuts: rms_bas, chi2
 
@@ -135,8 +139,8 @@ The list of the class methods are:
 - `def init_data(self)`: it initialises the quantities
 - `def reset_data(self)`: it resets the quantities at each event
 - `def open_ntuple(self)`: it opens the ROOT file which contains the n-tuples
-- `def cut_init(self)`: it initialies the events-selection located in the CutInit.par
-- `def calibration_par(self)`: it initialies the signals-correction values located in the Calibration.par
+- `def cut_init(self)`: it initialies the events-selection located in the `CutInit.par`
+- `def calibration_par(self)`: it initialies the signals-correction values located in the `Calibration.par`
 - `def temperature_correction_init(self)`: it defines the function for temperature correction
 - `def temperature_correction(self, amp, charge, i, c_id)`: it performs the temperature correction
 - `def analyze_ntuple(self, ev_start, ev_stop, fout)`: main function which recalls all the previous ones
@@ -147,12 +151,12 @@ The list of the class methods are:
 
 The class can be run through the `/$HOME/foot_turin/Script/PythonScript/sw_standalone/analyze_ntuple.py` script. 
 
-This script need some POSITIONAL arguments:
+This script need some **POSITIONAL** arguments:
 - the path of the input n-tuples file
 - the number of start event
 - the number of the stop event
 
-and some OPTIONAL arguments:
+and some **OPTIONAL** arguments:
 
 - the list of the channel (i.e. the crystal ID number): `[-c]`
 - the run number, required by the events-selection: `[-r]`
@@ -160,13 +164,13 @@ and some OPTIONAL arguments:
 - the path of the output file: `[-o]`
 - keyword to trigger on a specific crystal (e.g. the central one): `[-t]`
 
-example:
+example from terminal:
 
 `> python analyze_ntuple.py fout_ntuple.root 0 10000 -c 0 1 2 3 4 5 6 7 8 -o data_analysis.root -r 0 -exp CNAO_2021_11_17 -t 4`
 
 ## 4. Energy Resolution
 
-The function in `$HOME/foot_turin/Script/PythonScript/sw_standalone/energy_resolution.py` performs the energy resolution evaluation from the Amplitude and Charge histograms created in step 3. It is called by the Jupyter Notebook script in `$HOME/foot_turin/Script/PythonScript/sw_standalone/notebook/FitCalorimeterDistribution.ipynb`
+The function in `$HOME/foot_turin/Script/PythonScript/sw_standalone/energy_resolution.py` performs the energy resolution evaluation from the Amplitude and Charge histograms created in step 3. It is called by the `Jupyter Notebook` script in `$HOME/foot_turin/Script/PythonScript/sw_standalone/notebook/FitCalorimeterDistribution.ipynb`
 
 ## 5. Other macros
 - In the directory `$HOME/foot_turin/Script/PythonScript/sw_standalone/tb_analysis` sub-directories related to specific test beams are present. Each sub-directories have a set of scripts used to perform a dedicated analysis in that specific test beam. Often same scripts are present in different test beam sub-directories but with different numbers/configuration values hard-coded. This structure has been done in order to avoid one single script with thousends line commented each related to a different test beam.