class HPidTrackSorter: public TNamed

_HADES_CLASS_DESCRIPTION



 HPidTrackSorter

 This Class loops over the HPidTRackCand category and
 analyze the objects. Purpose of the procedure is to categorize
 the objects in the case of multiple usage of the single detector
 hits (RICH, InnerMDC, OuterMDC, META) as Double_t hit and to provide
 a hint which of the candidates is the best with respect to certain
 criteria (described by the bit flags below). If a HPidTrackCand
 object has been marked before by an other task with HPidTrackCand::kIsUsed it
 will be ignored by the sort process and stay unchanged. For the description
 of the differnt set/get functions of the HPidTrackCand objects see the
 documentation.
 To use HPidTrackSorter without changing the flags of the HPidTrackCand objects
 (non persitent way inside a macro or reconstructor) one can call the
 backupFlags() function before and modification of the flags and
 restore the flags by calling restoreFlags() after the privat work has been
 done.

 For debugging purpose one cand set screen printouts to check the sorting
 (setDebug() + setPrintLevel(Int_t level)(level = 1-3)).

 The analysis of the HPidTrackCand objects is done in several steps:

 1. Create the HPidTrackSorter object and call the HPidTrackSorter::Init()
    To initialze the sorter object with category pointers etc ...
 2. The internal structures are filled per event from the HPidTrackCand
    category by calling the
    Int_t HPidTrackSorter::fill(Bool_t (*function)(HPidTrackCand* ))
    function which expects a function pointer to a function taking an
    HPidTrackCand pointer as argument and returning a Bool_t if the conditions on
    the HPidTrackCand object are fullfilled (like for example in
    Bool_t HPidTrackSorter::selectHadrons(HPidTrackCand* pcand). For objects
    failing the test the kIsRejected bit is set. The user can provide
    his own selection functions to replace the build in selectLeptons(.....)
    and selectHadrons(....) select functions.
    The function pointer can be a pointer to a global function or member function
    of an Object for example:

    Bool_t select(HPidTrackCand* cand){             // global function
             if ( put all selection criteria here ) return kTRUE;
             else                                   return kFALSE;
    } or

    static Bool_t dummy::select(HPidTrackCand* cand){ // member function of object dummy
                                                      // needs to be declared static !
             if ( put all selection criteria here ) return kTRUE;
             else                                   return kFALSE;
    }
    would be called in the code like

    dummy d;
    HPidTrackCand* p= new HPidTrackCand() // just to get an object
    HPidTrackSorter sorter;               // create the sorter object
    // now we have 3 possibilities to call the
    // test function
    1. sorter.fill(select)        // global function
    2. sorter.fill(dummy::select) // member function of object dummy (static call without object creation)
    3. sorter.fill(d.select)      // member function of real object dummy
 3. For all accepted objects the quality criteria and Double_t hit flags are
    evaluated in within the selected sample and flagged to the HPidTrackCand objects.
    The objects which fullfill the given minimum criteria the kIsAcceptedXXX bit is
    flagged. For the RICH, InnerMDC, OuterMDC and META the kIsDoubleHitXXX bit are set
    if the same detector hit index has been used more than once in the sample.
 4. With the call of
    Int_t HPidTrackSorter::selectBest(HPidTrackSorter::ESwitch byQuality, Int_t byParticle)
    the final selection on the objects is performed. The by the fill() procedure
    selected objects are sorted by the selected quality criteria. Starting from the
    best object one goes down the list and marks all objects with the kIsUsed and
    kIsBestXXX bit if they do not reuse an already used detector hit index
    (Double_t hit rejection).
    For leptons the kIsLepton bit is flagged in addition. Individual detector hits
    can be ignored in the selection procedure with the setIgnoreXXX(kTRUE) functions
    (by default all hits are taken into account).
    HPidTrackSorter::ESwitch byQuality can be used as quality criteria switch for

          kIsBestHitRich          (by number of pads)
          kIsBestHitInnerMdc      (by chi2, non fitted segments last)
	    kIsBestHitOuterMdc      (by chi2, non fitted segments last)
	    kIsBestHitMeta          (by metamatch quality)
          kIsBestRKMeta           (by RK metamatch quality)
          kIsBestRKRICH           (by RK RICH match quality)
          kIsBestRK               (by RK chi2, none fitted outer segments with lower priority)
          kIsBestSPLINE           (by chi2)
          kIsBestKICK             (by pull)
          kIsBestRKRKMETA         (by RK chi2 * RK META match quality)
          kIsBestRKRKRICH         (by RK chi2 * RK RICH match quality)
          kIsBestRKMETAQA         (by RK chi2 * META match quality)

 5. The scheme allows for multiple selection following each other as
    the already used objects are excluded from the next steps (for example first
    select leptons and in the second iteration hadrons). The detector hit indicies
    of the previous selection of kIsUsed marked objects are added to list of used
    indicies by default not allowing to use a detector hit twice. To skip that
    memory one can set setIgnorePreviousIndex(kTRUE).
 6. After the analysis call HPidTrackSorter::finalize(). After the selection
    the user has to take into account only HPidTrackCand objects which  have
    been flagged with kIsUsed. The objects slected by the Lepton selection will
    be marked in addition with kIsLepton to identify them easily.
 7. For lepton selections the internal selectLepton() function cand be manipulated.
    With setRICHMatching(HPidTrackSorter::EMatch ,Float_t window) the matching between
    inner MDC and RICH hit can be selected (default: HPidTrackSorter::kUseRKRICHWindow,4 degree ).

    A selection of unique lepton and hadron tracks could look like
    the following example :

 void myMacro(Int_t nEvents,TString inputDir, TString inFile)
 {
    Hades* myHades = new Hades;
    gHades->setQuietMode(2);

    HRootSource* source = new HRootSource();
    source->setDirectory(((Text_t *)inputDir.Data()));
    source->addFile((Text_t *)inFile.Data());

    myHades->setDataSource(source);

    if(!myHades->init()){
	cout<<"Hades Init() failed!"<<endl;
	exit(1);
    }


    //------------------------------------------------------------------------
    // get category ointers and iterators
    HCategory* pidCat  = (HCategory*)gHades->getCurrentEvent()->getCategory(catPidTrackCand);
    HIterator* iter    = NULL;
    if(pidCat)
    {
         iter = (HIterator *)pidCat->MakeIterator("native");
    } else {
        cout<<"Category Pointer is NULL!"<<endl;
	exit(1);
    }
    //------------------------------------------------------------------------


    //--------------------------CONFIGURATION---------------------------------------------------
    //At begin of the program (outside the event loop)
    HPidTrackSorter sorter;
    //sorter.setOutputFile("testpidcleaner.root");                  // for debug ntuple output
    //sorter.setDebug();                                            // for debug
    //sorter.setPrintLevel(3);                                      // max prints
    //sorter.setRICHMatching(HPidTrackSorter::kUseRKRICHWindow,4.); // select matching RICH-MDC for selectLeptons() function
    //sorter.setIgnoreInnerMDC();                                   // do not reject Double_t inner MDC hits
    //sorter.setIgnoreOuterMDC();                                   // do not reject Double_t outer MDC hits
    //sorter.setIgnoreMETA();                                       // do not reject Double_t META hits
    //sorter.setIgnorePreviousIndex();                              // do not reject indices from previous selctions
    sorter.init();                                                  // get catgegory pointers etc...



    //------------------------------------------------------------------------
    // Event loop
    for(Int_t i = 1;i < nEvents; i ++)
    {
        //----------break if last event is reached-------------
        if(!gHades->eventLoop(1)) break;

        //------------------------------------------------------------------------
        // run your selection and set all flags

        // if you do not want to modify the flags
        // for the following tasks etc (needs call of
        // restoreFlags() at the end of the eventloop)
        //sorter.backupFlags();

        sorter.resetFlags(kTRUE,kTRUE,kTRUE,kTRUE);     // reset all flags for flags (0-28) ,reject,used,lepton
        Int_t nCandLep     = sorter.fill(HPidTrackSorter::selectLeptons);   // fill only good leptons
        Int_t nCandLepBest = sorter.selectBest(HPidTrackSorter::kIsBestRKRKMETA,HPidTrackSorter::kIsLepton);
        Int_t nCandHad     = sorter.fill(HPidTrackSorter::selectHadrons);   // fill only good hadrons (already marked good leptons will be skipped)
        Int_t nCandHadBest = sorter.selectBest(HPidTrackSorter::kIsBestRKRKMETA,HPidTrackSorter::kIsHadron);
        //------------------------------------------------------------------------

        //------------------------------------------------------------------------
        // analylize marked tracks (kIsUsed) ....
    	  iter->Reset();
        HPidTrackCand* pcand;
        while((pcand = (HPidTrackCandSim*)iter->Next()) != NULL)
	  {
           // accept only objects marked as good
	     if(!pcand->isFlagBit(HPidTrackCand::kIsUsed) ) continue;

           // do other selection......
        }
        //------------------------------------------------------------------------

        // if you do not want to modify the flags
        // for the following tasks etc (needs call of
        // backupFlags() at the beginning of the eventloop)
        // sorter.restoreFlags();


        //------------------------------------------------------------------------
        // celan vectors and index arrays
        sorter.cleanUp();
        //------------------------------------------------------------------------
    }
    //------------------------------------------------------------------------
    //At the end of program
    sorter.finalize();
 }