>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
UTILITIES in ElectroWeakAnalysis/Utilities:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

IMPORTANT BEFORE COMPILATION/LINK: From the 330 series on, full LHAPDF libraries are 
shipped with CMSSW. However, the default libraries used in the release are always
the "light" ones, which are very slow for PDF reweighting. In order to run fast, 
you should execute:
      1) scram setup lhapdffull
      2) touch $CMSSW_BASE/src/ElectroWeakAnalysis/Utilities/BuildFile.xml
      3) cmsenv
      4) scram b

If you prefer to use your own LHAPDF library and files, assumed to be installed 
under /usr/local, then do:
      1) Edit the file $CMSSW_BASE/config/toolbox/$SCRAM_ARCH/tools/selected/lhapdf.xml
      2.a) In that file, change the default for LHAPDF_BASE to "/usr/local"
      2.b) Change also the field "version" in order to match your insalled version
      3) scram setup lhapdf (and check that environment variables point to /usr/local/...)
      4) touch $CMSSW_BASE/src/ElectroWeakAnalysis/Utilities/BuildFile.xml
      5) cmsenv
      6) scram b

src/PdfWeightProducer.cc
===========================
- Writes into the data structure a std::vector<double> containing the LHAPDF weights 
  PDF_user(i)/PDF__in_generated_sample for each event, where 
  PDF_user(i) corresponds to the PDF set chosen by the user in the configuration file
  and i runs over the total number of members in the set. These weights can be 
  easily used later to assign systematics. Example of usage:

      # Produce PDF weights (maximum is 3)
      process.pdfWeights = cms.EDProducer("PdfWeightProducer",
            # Fix POWHEG if buggy (this PDF set will also appear on output, 
            # so only two more PDF sets can be added in PdfSetNames if not "")
            #FixPOWHEG = cms.untracked.string("cteq66.LHgrid"),
            GenTag = cms.untracked.InputTag("genParticles"),
            PdfInfoTag = cms.untracked.InputTag("generator"),
            PdfSetNames = cms.untracked.vstring(
                    "cteq66.LHgrid"
                  , "MRST2006nnlo.LHgrid"
                  , "NNPDF10_100.LHgrid"
            )
      )

- A typical application is the determination of the PDF systematics. This is 
  implemented in "src/PdfSystematicsAnalyzer.cc". This analyzer counts the 
  processed events using PDF re-weighting, and assigns systematic 
  uncertainties on the rate and on the acceptance according to the recipe 
  described in hep-ph/0605240. Usage:

      # Collect uncertainties for rate and acceptance
      process.pdfSystematics = cms.EDFilter("PdfSystematicsAnalyzer",
            SelectorPath = cms.untracked.string('pdfana'), # put here the selection path
            PdfWeightTags = cms.untracked.VInputTag(
                    "pdfWeights:cteq66"
                  , "pdfWeights:MRST2006nnlo"
                  , "pdfWeights:NNPDF10"
            )
      )
  NOTE: no underscores can be written in a CMSSW product, so NNPDF products will 
  not keep the last suffix from the original name ("_100" missing in this case).

- A test example for these utilities is "test/PdfSystematicsAnalyzer.py". There, 
  one counts re-weighted events before and after selection, which gives immediate
  access to the determination of PDF uncertainties on rate and acceptance for the 
  given process under study.


src/ISRWeightProducer.cc (IN PROGRESS)
============================
- Writes into the data structure a product containing the event weight ("double")
  to be applied to obtain an estimate of variations due to a modification of the 
  Z (or W) pt spectrum at the generator level. The input weights as a function 
  of the boson Pt are proovided via vectors in the configuration file.
  Example of usage:

      # Produce event weights according to generated boson Pt
      # Example corresponds to approximate weights to study
      # systematic effects due to ISR uncertainties (Z boson)
      process.isrWeight = cms.EDProducer("ISRWeightProducer",
            GenTag = cms.untracked.InputTag("genParticles"),
            ISRBinEdges = cms.untracked.vdouble(
                  0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.,  9.
                  , 10., 11., 12., 13., 14., 15., 16., 17., 18., 19.
                  , 20., 21., 22., 23., 24., 25., 26., 27., 28., 29.
                  , 30., 31., 32., 33., 34., 35., 36., 37., 38., 39.
                  , 40., 41., 42., 43., 44., 45., 46., 47., 48., 49.
                  , 999999.
            ),
            PtWeights = cms.untracked.vdouble(
                  0.800665, 0.822121, 0.851249, 0.868285, 0.878733
                  , 0.953853, 0.928108, 0.982021, 1.00659 , 1.00648
                  , 1.03218 , 1.04924 , 1.03621 , 1.08743 , 1.01951
                  , 1.10519 , 0.984263, 1.04853 , 1.06724 , 1.10183
                  , 1.0503  , 1.13162 , 1.03837 , 1.12936 , 0.999173
                  , 1.01453 , 1.11435 , 1.10545 , 1.07199 , 1.04542
                  , 1.00828 , 1.0822  , 1.09667 , 1.16144 , 1.13906
                  , 1.27974 , 1.14936 , 1.23235 , 1.06667 , 1.06363
                  , 1.14225 , 1.22955 , 1.12674 , 1.03944 , 1.04639
                  , 1.13667 , 1.20493 , 1.09349 , 1.2107  , 1.21073
            )
      )
     
- This weight information can be processed via the Analyzer
  "src/SimpleSystematicsAnalyzer.cc". A test example is 
  "test/SimpleSystematicsAnalyzer.py".

src/WeakEffectsWeightProducer.cc
====================================
- Writes into the data structure a product containing the event weight ("double") 
to take into account Weak effects in Drell-Yan production when using PYTHIA. It 
corrects two weak effects: a) effects included in rhof_effective, b) Sudakov-terms 
relevant at very high invariant mass.
  Example of usage:
      process.weakWeight = cms.EDProducer("WeakEffectsWeightProducer",
            GenParticlesTag = cms.untracked.InputTag("genParticles"),
            RhoParameter = cms.untracked.double(1.004)
      )

src/FSRWeightProducer.cc (IN PROGRESS)
======================================
- Writes into the data structure a product containing the event weight ("double")
  for estimating uncertainties due to missing final state QED radiation terms in 
  PYTHIA for W->l nu and Z->ll. It produces the procuct of two factor:
      a) Factor to go from soft-collinear approach to exact O(alpha) 
         (from hep-ph/0303260, only sizable for W, and small in general)
      b) Factor to recover missing NLO QED terms 
         (using alpha(pt**2) instead of alpha(0))
  Example of usage:

      process.fsrWeight = cms.EDProducer("FSRWeightProducer",
            GenTag = cms.untracked.InputTag("genParticles"),
      )

- This weight information can be processed via the Analyzer
  "src/SimpleSystematicsAnalyzer.cc". A test example is 
  "test/SimpleSystematicsAnalyzer.py".


src/ISRGammaWeightProducer.cc (IN PROGRESS)
===========================================
- Writes into the data structure a product containing the event weight ("double")
  for estimating uncertainties due to missing initial state QED radiation terms in 
  PYTHIA for W->l nu and Z->ll. It assumes PYTHIA6 as input. The logic is taken 
  from hep-ph/9812455, which is the one used for QCD matrix-element reweighting
  in W/Z inclusive production. PYTHIA8 should already include this QED ISR 
  reweighting.
  Example of usage:

      process.isrGammaWeight = cms.EDProducer("ISRGammaWeightProducer",
            GenTag = cms.untracked.InputTag("genParticles"),
      )

- This weight information can be processed via the Analyzer
  "src/SimpleSystematicsAnalyzer.cc". A test example is 
  "test/SimpleSystematicsAnalyzer.py".

src/DistortedMuonProducer.cc
============================

- Writes into the data structure a new reco::Muon collection distorted by
  smearing and efficiency effects. This new collection can be easily used as 
  a realistic Monte Carlo prediction for the latest steps of the analysis. 
  The input distortions are provided as a function of pseudorapidity via 
  vectors in the configuration file. To include momentum distortions properly, 
  we perform a previous matching between reconstructed and generated muons 
  using standard CMSSW matching utilities.  

- An example showing how to use this code is given in "test/distortedMuons.py". The 
  relevant lines in the configuration file are:

      process.genMatchMap = cms.EDFilter("MCTruthDeltaRMatcherNew",
        src = cms.InputTag("muons"),
        matched = cms.InputTag("genParticles"),
        distMin = cms.double(0.15),
        matchPDGId = cms.vint32(13)
      )   

      process.distortedMuons = cms.EDFilter("DistortedMuonProducer",
        MuonTag = cms.untracked.InputTag("muons"),
        GenMatchTag = cms.untracked.InputTag("genMatchMap"),
        EtaBinEdges = cms.untracked.vdouble(-2.1,2.1), # one more entry than next vectors
        ShiftOnOneOverPt = cms.untracked.vdouble(1.e-4), #in [1/GeV]
        RelativeShiftOnPt = cms.untracked.vdouble(0.),
        UncertaintyOnOneOverPt = cms.untracked.vdouble(2.e-4), #in [1/GeV]
        RelativeUncertaintyOnPt = cms.untracked.vdouble(1.e-3),
        EfficiencyRatioOverMC = cms.untracked.vdouble(0.99)
      )

src/DistortedMuonProducerFromDB.cc (under development)
==================================

- Writes into the data structure a new reco::Muon collection distorted by
  scale and smearing effects. This new collection can be easily used as a 
  realistic Monte Carlo prediction for the latest steps of the analysis. 
  We perform a previous matching between reconstructed and generated muons 
  using standard CMSSW matching utilities. The input distortions are taken 
  from the database. Efficiency effects may be added in the future.

- An example showing how to use this code is given in "test/distortedMuonsFromDB.py". 
  The relevant lines in the configuration file, in addition to the specific 
  PoolDBESSources, are:

      process.distortedMuons = cms.EDFilter("DistortedMuonProducerFromDB",
        MuonTag = cms.untracked.InputTag("muons"),
        GenMatchTag = cms.untracked.InputTag("genMatchMap"),
        DBScaleLabel = cms.untracked.string(''),
        DBDataResolutionLabel = cms.untracked.string('MuScleFit_Resol_OctoberExercise_EWK_InnerTrack_WithLabel'),
        DBMCResolutionLabel = cms.untracked.string('MuScleFit_Resol_OctoberExercise_SherpaIdealMC_WithLabel'),
      )

src/DistortedMETProducer.cc
===========================

- Writes into the data structure a new reco::MET collection after distortion.
  This new collection can be easily used as a realistic Monte Carlo 
  prediction for (muon-uncorrected) MET at the latest steps of the analysis. 
  At present, only the simplest possibility of scaling MET and sum(ET) by 
  a global scale factor is implemented, and no matching with GenMET has been 
  tried yet. Example of usage:

      process.distortedMET = cms.EDFilter("DistortedMETProducer",
        MetTag = cms.untracked.InputTag("met"),
        MetScaleShift = cms.untracked.double(0.1)
      )

- A simple example showing how to use this code is given in "test/distortedMET.py".