====== How to run MadWeight ======

In order to have MadWeight on the machine just check out it via bazaar (bazaar is installed on our tier 3).
This is the development branch, the most up to date. 

<code>
bzr branch lp:~maddevelopers/madgraph5/madweight_mc_perm 
</code>

Once MadWeight is on the working machine, the first step is to calculate the matrix elements for the process to consider: the hypothesis HP.
It is possible to it by launching MadGraph and defining the hypothesis process.

<code>
cd madweight_mc_perm
./bin/mdg5                                                         # launching MadGraph
generate p p > t h b~ j $$ w+ w-, h > b b~ , t > b l+ vl           # generating the process
add process p p > t~ h b j $$ w+ w-, h > b b~ , t~ > b~ l- vl~     # adding the complementary channel
output madweight tHbb_HP                                           # saving the output in the tHbb folder (tHbb_HP folder will be automatically created)
</code>


Madweight requires as input an **LHCO file** and a **set of datacards**.



 ===== LHCO files =====

A **LHCO** file is a text file collecting basic info on all the events of the sample. 
  * It stores info about the type of particles in the event (muon, electron, jet, met) and relative pt, eta, phi, btag, ect.
  * More info about the structure of LHCO files can be found at: http://madgraph.phys.ucl.ac.be/Manual/lhco.html

__**LHE to LHCO**__: lhco files can be converted from LHE files. To do this a script is available from MadGraph website. Download it in the working directory:

<code>
wget https://cp3.irmp.ucl.ac.be/projects/madgraph/raw-attachment/wiki/MadWeightTool/lhe2lhco.py.txt 
mv lhe2lhco.py.txt lhe2lhco.py
</code>

__**EDM LHE to LHCO**__: lhco files can converted also from EDM LHE files using a standard tool provided within the CMS framework (ExternalLHEAsciiDumper). Copy it and change the name of the input file: 
  * [[http://cmssw.cvs.cern.ch/cgi-bin/cmssw.cgi/CMSSW/GeneratorInterface/LHEInterface/test/testExternalLHEAsciiDumper_cfg.py?revision=1.2&view=markup]] 


__**ROOT to LHCO**__: To convert root files to LHCO files a standard tool does not exist, because it depends on the structure of the user root file. A root/lhco converter script to convert tH analysis root ntuples in lhco file is going to be implemented and it will be posted here as soon as it will be ready.
 

 ===== Datacards =====

Datacards are stored in the sundirectory Cards of the created folder tHbb_HP.
The datacards to customize are three: param_card.dat, run_card.dat and Madweight_card.dat

  * __**param_card.dat**__: In this datacard it is stored the model, to change it, just replace existing values of particles mass, width, couplings. For instance, in the case of tH analysis, the Higgs boson mass has to be set to 125 and the Higgs-top coupling to -173.
  *  __**run_card.dat**__: Information about colliding particles are stored here, proton-proton collisions are considered. The value of per-beam-energy has to be changed, default is 8 teV per beam. 
  *  __**Madweight_card.dat**__: This is the Madweight configuration card. The first thing to change is the name of the job that is going to be submitted. Among the other parameters to set there are the number of events and the parameter of interest. Example: if the mass of the Higgs is the parameter of interests of the specific analysis, then it has to be specified in the following way:
<code>
 11   mass  # The parameter of interest
 12   25    # Id of the particle for wich the parameter must be changed
 13   115   # Different values of the parameter for which a scan will be performed
 13   125
 13   130
</code>




 ===== Producing weights =====

In order to apply the matrix element method to a sample S under the hypothesis HP, Madweight has to be run using the LHCO file relative to the sample S and the datacards related to the hypothesis HP. 
  * Copy the .lhco file in the Events folder with name ''input.lhco'':
<code>
cd tHbb_HP 
cp $MYSAMPLE_PATH/MySample.lhco Events/input.lhco
</code>
  * Set the transfer function (TF), choosing it among those available:
<code>
./bin/mw_options
define_transfer_fct
Please choose your transfer_function between
 0 / dbl_gauss_pt_jet
 1 / uniform
 2 / jet_gaussian
 3 / user
 4 / single_gaussian
 5 / gauss_on_leptons
 6 / all_delta
 [dbl_gauss_pt_jet, uniform, jet_gaussian, user, single_gaussian, gauss_on_leptons, all_delta, 0, 1, ... ][60s to answer]
</code>

  * It is possible to define a custom transfer function. Instructions will come soon. 
  * Now that everything has been set launch MadWeight to compute the probabilities for each events:
<code>
./bin/madweight.py
</code>
At this point MadWeight propose to check the datacards, change again transfer function if desired or specify another lhco file. If everything has been already set properly before, then just type 0 to go ahead.


In order to apply the MEM over different samples, but under the same hypothesis, follow the next steps:

  * run_card.dat and param_card.dat have to remain unchanged once the hypothesis is defined. 
  * The parameter ''name'' in Madweight_card.dat has to be changed. A new subdirectory **name** will be created in the Events folder each time MW is run. Results will be stored there. It is very important to change this value because otherwise the previous results will be overwritten.
  * Also the lhco file has to be updated each time MadWeight has to be run over a new sample: the lhco file related to the specific sample must be placed in the Events directory and named ''input.lhco'' as usual.



 ===== Results =====

Results will be collecting in the file weights.out in the Events/name/ folder.