********************************************
**           TemplateBuilder              **
**                                        **
**       README version 13/04/14          **
**                                        **
********************************************

Contact: sauvan[AT]llr.in2p3.fr

This tool is able to build templates from events stored in a TTree. 2D and 3D templates (TH2F & TH3F) can be built.
Templates are defined by the user in a JSON file (JavaScript Object Notation). It is parsed by the tool and templates are built according to the specifications.

----------------------
1) Running the program
----------------------
The program needs ROOT in order to compile and run. So please make sure that ROOT is correctly setup in your environment.

Compilation:
> make

Clean area (if necessary):
> make clean

Run with:
> ./buildTemplate.exe run/my-template-definition.json

The run/ directory is intended to store the template definitions. There are two example files already in this directory: run/templates2DExample.json and run/templates3DExample.json.
The syntax of these definition files is detailed in the next section.

------------------
2) Template syntax
------------------
2)-1- General
-------------
NB: The JSON syntax is used. More details can be found on the web. Only the specific syntax is detailed here.

The file starts and ends with brackets {} surrounding the parameters. Lines starting with // are comments.
Several objects/variables are defined, at different levels. Top level ones are:
- inputDirectory: location of input trees
- outputFile    : output file containing the templates
- templates     : a list of template definitions

Then for each template in the list several variables can be defined:
- name                 : the name of the template (don't use the same name for several templates)
- files                : the list of input tree files in the directory defined by 'inputDirectory'
- tree                 : the name of the tree in the files
- trees                : list of input files and trees together (to be used instead of 'file' + 'tree' if different tree names are used)
- variables            : template variables, 2 for 2D, 3 for 3D. The names correspond to those in the tree.
- weight               : if events are weighted. This is the weight to be applied when filling templates. The name corresponds to the tree variable.
- conserveSumOfWeights : tell if the events sum of weights has to be used to normalize the template (true or false (default) ). If false, the template is normalized to 1. In any case, a scaling factor can always be applied at the end (see "rescale" postprocessing).
- selection            : to apply an event selection. The variables used in the formula should be in the tree.
- assertion            : to define an assertion. If it fails the program will stop.
- filloverflows        : if set to true overflows will be filled in boundary bins. Otherwise they are discarded. Default is false.
- binning              : the binning of the template
- postprocessing       : to modify the templates after it is filled. For instance smoothing, mirroring, etc. can be applied.


2)-2- Input files and trees definition
------------------------
There are two ways to define input files and trees.

- If the tree name is the same in all input files, use keywords 'files' and 'tree':
	"files":[
		"HZZ4lTree_powheg15jhuGenV3H126_withDisc_new_noProt.root",
		"HZZ4lTree_powheg15jhuGenV3PseHH126_withDisc_new_noProt.root"
		],
	"tree":"SelectedTree"

- If tree names are different, use keyword 'trees', each string should be of the form "fileName:treeName":
	"trees":[
		"HZZ4lTree_powheg15jhuGenV3H126_withDisc_new_noProt.root:SelecteTree_1",
		"HZZ4lTree_powheg15jhuGenV3PseHH126_withDisc_new_noProt.root:SelectedTree_2"
		]



2)-3- Binning definition
------------------------
Two types of binning can be define:
- fixed   : fixed size bins (standard ROOT binning)
- adaptive: adaptive binning built with an iterative procedure based on the densities of events in the region of interest

The fixed size bins are defined with the keyword 'bins', the value is a list [nbinsx, xmin, xmax, nbinsy, ymin, ymax], or [nbinsx, xmin, xmax, nbinsy, ymin, ymax, nbinsz, zmin, zmax] for 3D.
For adaptive binning the 'bins' keyword is used to specify the underlying binning (constraining the adaptive bins), and 'entriesperbin' specify the minimum number of events per bin (default is 200) used in the iterative procedure.

Example:
"binning":{
	"type":"adaptive",
	"bins":[100,0.,1.,100,-0.5,0.5],
	"entriesperbin":200
},

2)-4- Postprocessing
--------------------
A few postprocessing have been implemented for the moment:
- smooth     : smoothing the template with k5b or variable Gaussian kernel
- mirror     : mirroring or anti-mirroring
- floor      : flooring
- rescale    : rescaling template
- reweight   : reweigting template based on the 1D projections in order to match the raw 1D distributions. This is intended for residual corrections after the smoothing has been applied.

The syntax to use is:
"postprocessing":[
	{"type":"smooth", "key":value, ...}
]
For each postprocessing parameters can be given with the form "key":value. The following parameters are possible:
- smooth:
 -> kernel        : "k5b" or "adaptive", default="adaptive"
	"adaptive" uses a Gaussian kernel with variable width, the width being determined from the adaptive binning
	"k5b" is only possible for 2D templates 
 -> entriesperbin : integer, default=200 
	This is the number of entries per adaptive bin used to derive the Gaussian widths. Larger number means wider kernel. If the adaptive binning has been chosen in the "binning" definition, this parameter will not be taken into account and the widths will be taken from the already computed adaptive binning.

- mirror:
 -> axis         : 0, 1 or 2, default=1 (Y-axis) 
	Axis along which the mirror is applied (X=0,Y=1,Z=2)
 -> antisymmetric: true or false, default=false 
	To choose between symmetry and antisymmetry

- floor:
 -> no parameter

- rescale:
 -> factor: float, default=1 
	Factor used to rescale the template

- reweight:
 -> axes     : list of integer (0,1 or 2), default=empty list
	Specifies the axes along which the reweighting will be performed
 -> rebinning: list of lists of bin boundaries, default=empty list
	Index 0 corresponds to x-axis, index 1 to y-axis, and index 2 to z-axis.
	It may be impossible to use these raw distributions as reference because of statistical fluctuations. Therefore they can be rebined, the binning being specified here. In order to retrieve the granularity of the raw distribution, the rebinned distribution is then interpolated and used as a reference for the reweighting.
	If no binning is specified, it is determined automatically by iteratively merging neighbor bins with non significant deviations. The reference distribution is then obtained by smoothing the raw distribution using bin size information. 
	The automatic procedure is prefered.


Example:
"postprocessing":[
	{"type":"smooth", "kernel":"adaptive", "entriesperbin":200},
	{"type":"reweight", "axes":[0,1,2]},
	{"type":"mirror", "axis":1},
	{"type":"floor"}
]
will smooth the template with a variable Gaussian kernel, reweight it along each dimension to match the 1D distributions, mirror the second axis, and add a floor.

2)-5- Template sums
-------------------
Templates can also be produced from already created templates, by using the keyword 'templatesum'. 
It will make a linear combination of templates. A list of input templates with a multiplicative factor for each of them should be given:
[{"name":"templateName", "factor":1.},{...},...]
The keyword "name" corresponds to the name of an existing template.
The keyword "factor" corresponds to the factor to be applied to the template. It is a floating point. All the templates in the list will be added with the given factor. 

Example:
"templatesum":[
	{"name":"a","factor":1.},
	{"name":"b","factor":-1.},
	{"name":"c","factor":-1.}
],
will create a template a - b - c