class HParticleEvtChara: public HReconstructor

_HADES_CLASS_DESCRIPTION 
*-- AUTHOR : B. Kardan  28.08.2019
*-- VERSION : 0.73

 HParticleEvtChara

 Purpose: EventCharacterization
 - Centrality from Hit(TOF,RPC,FW) and Track Estimators in Data/Sim
 - QVector and Phi (Reaction Plane Estimate) from FW
 - Event-weight for downscaled Events PT2


 Usage:

  - input files can be found at : example /cvmfs/hades.gsi.de/param/eventchara

  - to define the ParameterFile where Classes and Estimators are stored use
    setParameterFile("/cvmfs/hades.gsi.de/param/eventchara/ParameterFile.root")

  - to print the definition of estimator & class use
    printCentralityClass(HParticleEvtChara::kTOFRPC, HParticleEvtChara::k10);

  - to get the CentralityClass of an event (with estimator and class definition) use
    getCentralityClass(HParticleEvtChara::kTOFRPC, HParticleEvtChara::k10);

  - to get the CentralityPercentile of an event (only estimator is needed) use
    getCentralityPercentile(HParticleEvtChara::kTOFRPC);

  - to get the EventWeight to re-weight downscaled events use
    getEventWeight();

  - to get the EventPlane with ReCentering use
    getEventPlane(HParticleEvtChara::kDefault);


   Estimators:
    TOFRPC                   - (default) TOF and RPC hit multiplicity in time-window
    TOF                      - TOF hit multiplicity in time-window
    RPC                      - RPC hit multiplicity in time-window
    TOFRPCtot                - total TOF and RPC hit multiplicity in event-window
    SelectedParticleCand     - selected Particle multiplicity
    PrimaryParticleCand      - primary Particle multiplicity
    SelectedParticleCandCorr - selected Particle multiplicity corrected by the
                               running mean and scaled with the reference mean
                               (selTrack * referenceMean/<selTrack>)
    SelectedParticleCandSecCorr
                              - selected Particle multiplicity corrected by the
                               running mean and scaled with the reference mean
                               (selTrack * referenceMean/<selTrack>)
    SelectedParticleCandNorm - selected Particle multiplicity normalized by
                               the running mean (selTrack/<selTrack>)
    FWSumChargeSpec          - sum of charge (dE/dx in a.u.) of Spectator in
                               FW acceptance with beta~0.9
    FWSumChargeZ             - sum of charge (int Z up till charge-state 14
                               with individuel fixed cuts in dE/dx each FW-cell)
                               of Spectator in FW acceptance with beta~0.9

   Classes:
    2                   - 2% classes
    5                   - 5% classes
    10                  - (default) 10% classes
    13                  - 13% classes
    15                  - 15% classes
    20                  - 20% classes
    FOPI                - FOPI centrality classes

  EventPlaneCorrection:
    kNoCorrection            - EP only selection of spectator candidates in FW,
                               no Correction
    kSmear                   - smearing of x and y of each FW hit inside cell size
    kShiftFW                 - global shift x and y with the centre of gravity and
                               scale x and y with the sigma of the distribution of
                               all FW hits in all events (per class/day)
    kWeightCharge            - weigthing with charge-state up to 14 with individuel
                               fixed timing- and dE/dx-cuts each FW-cell
    kReCentering             - re-centering of QVector with <Qx> and <Qy> (calc. evt-by-evt)
                               (only first harmonic correction)
    kScaling                 - scaling of QVector with the sigma of Qx and Qy (calc. evt-by-evt)
    kRotation                - rotation of EP via residual Fourier harmonics up to 8 cos and sin terms
                               after FWshift and FWscaling

    kDefault                 - recommended option (kShiftFW|kWeightCharge|kRotation)

 quick how-To:
  - for an example see demo-macro:
       /scripts/batch/GE/loopDST/loopDST.C

  1. include header-file
      #include "HParticleEvtChara.h"

  2. if you use Hloop check that following catagories are loaded:

   HParticleEvtInfo
   HParticleCand
   HWallHit

       if(!loop.setInput("-*,+HParticleEvtInfo, +HParticleCand, +HWallHit")){
           cout<<"READBACK: ERROR : cannot read input !"<<endl;
       }

  3. before eventLoop:

       HParticleEvtChara evtChara;
       TString ParameterfileCVMFS = "/lustre/nyx/hades/user/bkardan/param/centrality_epcorr_apr12_gen8_2019_02_pass30.root";

       //due to the overlap of day126  there is dedidacate param-file for the reverse-field runs
       if(isRevFieldDATA)   ParameterfileCVMFS = "/lustre/nyx/hades/user/bkardan/param/centrality_epcorr_apr12_gen8_revfield_2019_02_pass29.root";

       //if you need centrality-values for sim UrQMD gen8a you find them here
       //due missing primary light nuclei in UrQMD... there is no correction on the FW-EventPlane in this version!
       if(isSimulation)   ParameterfileCVMFS = "/lustre/nyx/hades/user/bkardan/param/centrality_epcorr_sim_au1230au_gen8a_UrQMD_minbias_2019_04_pass0.root";
       //if(isSimulation) ParameterfileCVMFS = "/lustre/nyx/hades/user/bkardan/param/centrality_epcorr_sim_au1230au_gen9vertex_UrQMD_minbias_2019_04_pass0.root";

       if(!evtChara.setParameterFile(ParameterfileCVMFS)){
           cout << "Parameterfile not found !!! " << endl;return kFALSE;
       }

       if(!evtChara.init()) {
           cout << "HParticleEvtChara not init!!! " << endl;return kFALSE;
       }

       Int_t eCentEst   = HParticleEvtChara::kTOFRPC;
       Int_t eCentClass = HParticleEvtChara::k10;
       Int_t eEPcorr    = HParticleEvtChara::kDefault;
       cout << "\t selected EPcorrection method is:  "  << evtChara.getStringEventPlaneCorrection(eEPcorr) << endl;


       evtChara.printCentralityClass(eCentEst, eCentClass);

  4. inside event-loop:

        Float_t  event_weight = evtChara.getEventWeight();   // event_weight dependent if PT2(down-scaled) or PT3

        Int_t   CentralityClassTOFRPC = evtChara.getCentralityClass(eCentEst, eCentClass);
        // 10% Centrality-Classes:       1(0-10%) - 5(40-50%) ... 0:Overflow max:Underflow

        Float_t CentralityTOFRPC      = evtChara.getCentralityPercentile(eCentClass);
        // CentralityPercentile:         0 - 100% percentile of the total cross section
        //                                   101% Over-,Underflow or Outlier Events

        Float_t EventPlane            = evtChara.getEventPlane(eEPcorr);
        //EventPlane:                   0 - 2pi (in rad)  re-centered & scaled EP
        //                             -1   no EP could be reconstructed

        //for EP-resolution use the sub-event:
        Float_t EventPlaneA            = evtChara.getEventPlane(eEPcorr,1);
        Float_t EventPlaneB            = evtChara.getEventPlane(eEPcorr,2);

        //check if the EP(and subEvent EP) could be reconstructed, most of the case less than 4 Hits in FW
        if(EventPlane  == -1)  continue;
        if(EventPlaneA  == -1 || EventPlaneB  == -1 ) continue;

        check if you have any further selections on FW-hit multiplicites in you own code,
        this will bias the result!

  5. to calculate the EP-resolution one option is the following:
     (Ollitrault method.  - approximation valid for high chi-values)
     inside event-loop fill the difference of the two sub-event EP
     into a histogramm for each centrality class:

          Float_t deltaPhiAB =  TMath::Abs(TVector2::Phi_mpi_pi(EventPlaneA-EventPlaneB));
          h->Fill(deltaPhiAB);

     after your event-analysis you can finalize your results by calculating the EP-resolution for each centrality class
     by the ratio of event N(pi/2 < deltaEP_AB < pi)/N(0 < deltaEP_AB < pi):

         Int_t i90        = h->FindBin(0.5*TMath::Pi());
         Int_t i180       = h->FindBin(TMath::Pi());
         Double_t ratio   = h->Integral(i90,i180) /h->Integral(1,i180);
         Double_t dChi    = sqrt(-2.*TMath::Log(2.*ratio));
         Double_t dEPres1 = HParticleEvtChara::ComputeResolution( dChi );    // for first harmonic
         Double_t dEPres2 = HParticleEvtChara::ComputeResolution( dChi , 2); // for second ...

  6. the second option will be described here soon here ;)
     (Voloshin method - precise iterative resolution search)
     inside event-loop fill the Cosine of the difference of the two sub-event EP
     into a histogramm for each centrality class:

         Float_t CosDeltaPhiAB =  TMath::Cos(EventPlaneA-EventPlaneB);
         h2->Fill(CosDeltaPhiAB);

     after your event-analysis you can finalize your results by calculating the EP-resolution for each centrality class
     by the mean-value:

         Double_t MeanCosDeltaPhiAB  = h2->GetMean();        //< cos n delta_phi>;
         Double_t dV = TMath::Sqrt(MeanCosDeltaPhiAB);
         Double_t dChi = FindXi(dV,1e-6, 1);                 // for first harmonic
         Double_t dEPres1 = HParticleEvtChara::ComputeResolution( dChi );    // for first harmonic
         Double_t dEPres2 = HParticleEvtChara::ComputeResolution( dChi , 2); // for second ...
         dV = ComputeResolution( TMath::Sqrt2()*dChi , 1);
         printf("An estimate of the event plane resolution first order is: %f\n", dV );


  7. to correct your flow-values use 1./dEPres1

  8. test your macro with data and if you real have the right parameterfile
      with right values for centrality and EPcorections, check the output of

        evtChara.printCentralityClass(eCentEst, eCentClass);

  9. and now happy plotting ;)


 Change History:

 19.02.2019  release of 0.7
 24.04.2019  implementation of useFWCut() and check if FWcut hist are loaded
 04.06.2019  fix of embeded-sim into data and removed of high-momentum condition