JSON-Matcher.md

+Using MatcherBuilder it is possible to create NoSharingMatcher/SegmentedSingleMatcher using a json file for configuration  
+__All values are given in energy (keV) and strip indexes start from 1__.
+
+Double Sided Detectors
+-----------------------
+
+Assuming a setup with two detectors A and B the most basic configuration would be
+```json
+{
+  "DSD" : {
+    "__GLOBAL__" : {
+      "tolerance" : 200
+    }
+  }
+}
+```
+where the configuration for each detector is taken from the `__GLOBAL__` definition.  
+It is also possible to add `low_cut` and `high_cut` (defaults are 0 and ∞)
+```json
+{
+  "DSD" : {
+    "__GLOBAL__" : {
+      "tolerance" : 200,
+      "low_cut" : 200,
+      "high_cut" : 10000
+    }
+  }
+}
+```
+everything above or below this threshold will be cut away.  
+
+If one need special setting this can be achieved like this: 
+```json
+{
+  "DSD" : {
+    "A" : {
+      "tolerance" : 100,
+      "low_cut" : 0,
+      "high_cut" : 20000
+    },
+    "__GLOBAL__" : {
+      "tolerance" : 200,
+      "low_cut" : 200,
+      "high_cut" : 10000
+    }
+  }
+}
+```
+These settings will be applied for both sides of the DSD.  
+
+If you need settings that differ for the two sides you can use
+```json
+{
+  "DSD" : {
+    "SU" : {
+      "front" : {
+        "disable" : [2, 3],
+        "low_cut" : [100, 200, 300, 700, 900, 600]
+      },
+      "back" : {
+        "disable" : 7,
+        "low_cut" : 200
+      }
+    },
+    "__GLOBAL__" : {
+      "tolerance" : 200,
+      "low_cut" : 200,
+      "high_cut" : 10000
+    }
+  }
+}
+```
+`disable` is used to disable strips. When specified as an array `low_cut` will set thresholds for the individual strips.
+
+To sum up:
+* `tolerance` the maximum allowed difference between front and back strips
+* `front/back` settings inside this will only be applied to this side.
+* `low_cut/high_cut` lower/higher threshold. Energies below/above this will be cut away.  
+When used inside a side this can be an array will thresholds for individual strips. The number of entries must equal number of strips
+* `disable` disable a specific strip.  
+This can _only_ be used inside `front/back`  
+Can be number or array. No restriction on number of elements in array but all elements must be valid strip numbers.
+
+Single Sided Detectors
+-----------------------
+This includes Pads, Clovers and SquareSSD.
+
+Assuming a setup with a pad _P_ and four segment clover _G_ the most simple thing would be
+```json
+{
+  "SSD" : {
+    "__GLOBAL__" : {
+    }
+  }
+}
+```
+which use the default low/high cuts of 0 and ∞. Similarly to the DSD one can change these
+```json
+{
+  "SSD" : {
+    "__GLOBAL__" : {
+      "low_cut" : 200,
+      "high_cut" : 10000
+    }
+  }
+}
+```
+The same conditions for specifying cuts as arrays applies, however these should not be nested under `front/back`.
+```json
+{
+  "SSD" : {
+    "P" : {
+      "low_cut" : [200]
+    },
+    "G" : {
+      "low_cut" : [100, 200, 300, 400],
+      "disable" : [2, 3]
+    }
+  }
+}
+```
+To sum up
+* `low_cut/high_cut` lower/higher threshold. Energies below/above this will be cut away.  
+When used inside a detector this can be an array will thresholds for individual strips. The number of entries must equal number of strips
+* `disable` disable a specific strip.  
+This can _only_ be used inside a detector  
+Can be number or array. No restriction on number of elements in array but all elements must be valid strip numbers.
+
+
+TDC options 
+---------------------------------------------------
+The object of the TDC matcher settings is to specify offsets, that will align TDC signals. 
+
+Both SSD and DSSD global object accepts:
+* `tdc_shift` A value added to all non-zero TDC values. Default is 100x2^17
+* `tdc_multiplier` All non-zero TDC values is multiplied by this. Default is 100.
+* `tdc_offset` A path to a file. This file must contain three columns; strip number, offset and standard deviation. Example: [tdc_Det1_back.dat](/uploads/1f03399f0890148b91c68b595de79f30/tdc_Det1_back.dat). Such a file must be given for each DSSD side or SSD. 
+
+Quality check of front-back matching
+-------------------------------------
+If all front and back strips have been accurately calibrated, the
+difference between matched front and back energies (FE-BE) should average to 
+zero with a small spread due to the finite experimental resolution. 
+Several automated quality checks have been built into the Sorter to 
+ensure that this is the case. Furthermore, the Sorter has an 
+algorithm to calculate improved calibration coefficients for all 
+channels. 
+
+As part of the quality check, the Sorter creates 2D histograms
+of FE-BE versus energy, which are saved along with the sorted data 
+in the output file.
+
+The quality checker is configured in the following way:
+```json
+{
+  "QC" : {
+    "max_dev" : 20,
+    "range_threshold" : 0.5,
+    "x_max" : 1E4,
+    "x_min" : 0,
+    "x_max_fit" : -1,
+    "x_min_fit" : 500,
+    "x_bins" : 100
+  }
+}
+```
+The meaning of each parameter is as follows:
+
+- x_bins: Divide the energy axis into this many bins
+- x_min, x_max: Min and max values of the energy axis (keV)
+- x_min_fit, x_max_fit: Fit range for linear fit to FE-BE (keV)
+- max_dev: Detect problem if linear fit exceeds max_dev at any point (keV)
+
+Example: [setup.zip](/uploads/b6b742a0c39fcf05454619499c01cb7d/setup.zip),
+[matcher.json](/uploads/bafc19db57b38cc85c03c09d211341e3/matcher.json),
+[82_061.root](/uploads/a3bb519de44f42bbeb6a153bebe88f34/82_061.root)
+
+Running Sorter with the command 
+```terminal
+Sorter --ignore U5,U3,U4,P2,P3,P4,P6 -s setup/setup.json -m matcher.json 82_061.root
+```
+
+produces the following output:
+```terminal
+Writing sorted output to match/82_061m.root
+Processing entry 107430 (100%)
+U2 f
+Mean offset and slope: 10.6677keV -0.000714848
+Problems detected
+Strip	Empty  Entries  Mean  Std  Range  Offset  Slope  Deviation
+------------------------------------------------------------
+  15  	                                                  X  
+  16  	                 X                  X             X  
+U2 b
+Mean offset and slope: 5.47325keV 0.00188276
+Problems detected
+Strip	Empty  Entries  Mean  Std  Range  Offset  Slope  Deviation
+------------------------------------------------------------
+  1  	                 X     X                    X     X  
+  3  	                 X     X            X       X     X  
+  6  	                 X                                X  
+  11  	                 X     X                          X  
+U6 f
+Mean offset and slope: -0.0259623keV -0.000690405
+Problems detected
+Strip	Empty  Entries  Mean  Std  Range  Offset  Slope  Deviation
+------------------------------------------------------------
+  2  	                                                  X  
+  7  	                 X                                X  
+  16  	                                    X             X  
+U6 b
+Mean offset and slope: 0.641356keV -0.00107381
+Problems detected
+Strip	Empty  Entries  Mean  Std  Range  Offset  Slope  Deviation
+------------------------------------------------------------
+  15  	  X   
+```
+
+If you add the flag `-q`, the Sorter will output files with new calibration coefficients:
+```terminal
+New calibrations saved to:
+U2.qccal
+U6.qccal
+```
+
+Add the flag `-Q` is you want to run the Sorter in quite mode (quality-check report is not printed):
+```terminal
+Writing sorted output to match/82_061m.root
+Processing entry 107430 (100%)
+Problems detected.  Re-run the Sorter without the -Q flag to obtain complete error report.
+``` 
\ No newline at end of file