class TEntryList: public TNamed

TEntryList: a List of entry numbers in a TTree or TChain

There are two types of entry lists:

1. for a TTree (fBlocks data member is non-zero) Entry numbers are stored in TEntryListBlocks, which, in their turn, are stored in the TObjArray fBlocks. The range of the entry numbers is cut into intervals of kBlockSize entries (currently 64000), so that the first block contains information which entries out of the first 64000 pass the selection, the second block - which entries out of the 64000-127999 interval pass the selection, etc. Some blocks, obviously, might be empty. The internal representation of entry numbers in the blocks is described in the TEntryListBlock class description, and this representation might be changed by calling OptimizeStorage() function (when the list is filled via the Enter() function, this is done automatically, except for the last block). Individual entry lists can be merged (functions Merge() and Add()) to make an entry list for a TChain of corresponding TTrees.
   Picture Source
   
   

   {
   //=========Macro generated from canvas: c/c
   //=========  (Tue Jan 23 16:58:56 2007) by ROOT version5.15/01
      TCanvas *c = new TCanvas("c", "c",213,172,460,253);
      c->Range(0,0,1,1);
      c->SetBorderSize(2);
      c->SetFrameFillColor(0);
      
      TPaveText *pt = new TPaveText(0.00518135,0.810811,0.507772,0.989189,"br");
      pt->SetFillColor(19);
      pt->SetTextColor(4);
      TText *text = pt->AddText("TEntryList for a TTree");
      pt->Draw();
      
      pt = new TPaveText(0.0387597,0.483696,0.307494,0.657609,"br");
      pt->SetFillColor(19);
      text = pt->AddText("TEntryList");
      pt->Draw();
      
      pt = new TPaveText(0.0363636,0.107527,0.306494,0.489247,"br");
      pt->SetFillColor(19);
      pt->SetTextFont(42);
      text = pt->AddText("fBlocks");
      text = pt->AddText("fLists = 0");
      pt->Draw();
      
      pt = new TPaveText(0.338501,0.23913,0.627907,0.375,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      text = pt->AddText("Info on entries 0-63999");
      pt->Draw();
      
      pt = new TPaveText(0.643411,0.23913,0.989664,0.375,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      text = pt->AddText("entries 64000-127999");
      pt->Draw();
      
      pt = new TPaveText(0.423773,0.423913,0.870801,0.576087,"br");
      pt->SetFillColor(19);
      text = pt->AddText("TObjArray of TEntryListBlock objects");
      pt->Draw();
      TArrow *arrow = new TArrow(0.277202,0.356757,0.418605,0.505435,0.05,">");
      arrow->SetFillColor(1);
      arrow->SetFillStyle(1001);
      arrow->Draw();
      return c;
   }

2. for a TChain (fLists data member is non-zero) It contains a TList of sub-lists (TEntryList objects, corresponding to each TTree) Trees and lists are matched by the TTree name and its file name (full path). All sub-lists are returned by the GetLists() function and individual lists are returned by GetEntryList() function. Such lists are no different from the lists for TTrees, described above.
   Picture Source
   
   

   {
   //=========Macro generated from canvas: c/c
   //=========  (Mon Jan 22 19:00:21 2007) by ROOT version5.15/01
      TCanvas *c = new TCanvas("c", "c",172,104,447,249);
      c->Range(0,0,1,1);
      c->SetBorderSize(2);
      c->SetFrameFillColor(0);
      
      TPaveText *pt = new TPaveText(0.0026738,0.790055,0.417112,0.994475,"br");
      pt->SetFillColor(19);
      pt->SetTextColor(4);
      TText *text = pt->AddText("TEntryList for a TChain");
      pt->Draw();
      
      pt = new TPaveText(0.00802139,0.541436,0.294118,0.701657,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      pt->SetTextFont(42);
      text = pt->AddText("TEntryList");
      pt->Draw();
      
      pt = new TPaveText(0.0106952,0.237569,0.294118,0.546961,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      pt->SetTextFont(42);
      text = pt->AddText("fBlocks = 0");
      text = pt->AddText("fLists");
      pt->Draw();
      
      pt = new TPaveText(0.483957,0.607735,0.68984,0.773481,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      pt->SetTextFont(42);
      text = pt->AddText("TChain");
      pt->Draw();
      
      pt = new TPaveText(0.347594,0.475138,0.494652,0.596685,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      pt->SetTextFont(42);
      text = pt->AddText("TTree_1");
      pt->Draw();
      
      pt = new TPaveText(0.508021,0.475138,0.660428,0.59116,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      pt->SetTextFont(42);
      text = pt->AddText("TTree_2");
      pt->Draw();
      
      pt = new TPaveText(0.673797,0.469613,0.826203,0.59116,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      pt->SetTextFont(42);
      text = pt->AddText("TTree_3");
      pt->Draw();
      
      pt = new TPaveText(0.251337,0.0331492,0.483957,0.165746,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      text = pt->AddText("TEntryList for TTree_1");
      pt->Draw();
      
      pt = new TPaveText(0.491979,0.038674,0.729947,0.171271,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      text = pt->AddText("TEntryList for TTree_2");
      pt->Draw();
      
      pt = new TPaveText(0.737968,0.038674,0.97861,0.171271,"br");
      pt->SetBorderSize(1);
      pt->SetFillColor(19);
      text = pt->AddText("TEntryList for TTree_3");
      pt->Draw();
      
      pt = new TPaveText(0.410667,0.21978,0.816,0.395604,"br");
      pt->SetFillColor(19);
      text = pt->AddText("TList of TEntryList* objects");
      pt->Draw();
      TArrow *arrow = new TArrow(0.224,0.296703,0.4,0.296703,0.05,">");
      arrow->SetFillColor(1);
      arrow->SetFillStyle(1001);
      arrow->Draw();
      return c;
   }

Operations on entry lists

• Add() - if the lists are for the same tree, adds all the entries of the second list to the first list. If the lists are for different trees, creates a TEntryList with 2 sublists for each TTree. If the lists are for TChains, merges the ones for the same trees and adds new sublists for the TTrees that were not included in the first TEntryList
• Subtract() - if the lists are for the same TTree, removes the entries of the second list from the first list. If the lists are for TChains, loops over all sub-lists
• GetEntry(n) - returns the n-th entry number
• Next() - returns next entry number. Note, that this function is much faster than GetEntry, and it's called when GetEntry() is called for 2 or more indices in a row.

TTree::Draw() and TChain::Draw()

Use option entrylist to write the results of TTree::Draw and TChain::Draw into an entry list. Example:

     tree->Draw(">>elist", "x<0 && y>0", "entrylist");
     TEntryList *elist = (TEntryList*)gDirectory->Get("elist");

Example of Loop on TEntryList with a TChain

void loopChain() {
   TFile *fe = TFile::Open("myelist.root");
   TEntryList *myelist = (TEntryList*)fe->Get("myelist");
   TChain *ch = new TChain("ntuple");
   ch->Add("hsimple.root");
   ch->Add("hsimple2.root");
   Long64_t listEntries = myelist->GetN();
   Long64_t chainEntries = ch->GetEntries();
   Int_t treenum = 0;
   ch->SetEntryList(myelist);
   for (entry=start;entry < end;entry++) {
      entryNumber = treechain->GetEntryNumber(entry);
      if (entryNumber < 0) break;
      localEntry = fTree->LoadTree(entryNumber);
      if (localEntry < 0) break;
      // then either call branch->GetEntry(localEntry);
      // or  entryNumber->GetEntry(entryNumber);
      // In the later case the LoadTree is then somewhat redudant.
   }
 }

When using the TEntryList interface directly, you can get the 'tree number' and entry in the current tree (i.e. value similar to the return value of LoadTree) from calling TEntryList::GetEntryAndTree:

    Long64_t treeEntry = myelist->GetEntryAndTree(el,treenum);

to obtain the entry number within the chain you need to add to it the value of

treeEntry+ch->GetTreeOffset()[treenum]

such that the loop in the previous example can also be written as:

for (Long64_t el = 0; el < listEntries; el++) {
   Long64_t treeEntry = myelist->GetEntryAndTree(el,treenum);
   Long64_t chainEntry = treeEntry+ch->GetTreeOffset()[treenum];  
   printf("el=%lld, treeEntry=%lld, chainEntry=%lld, treenum=%d\n", el, treeEntry, chainEntry, treenum);
   ch->LoadTree(chainEntry); // this also returns treeEntry
   needed_branch->GetEntry(treeEntry);
}

TSelectors

To fill an TEntryList from a TSelector correctly, one must add the TEntryList object to the output list of the selector (TSelector::fOutput). This is the only way to make the sub-lists of the TEntryList switch when the current tree of the TChain is changed.

Using a TEntryList as input (TTree::SetEntryList() and TChain::SetEntryList())

while the TTree::SetEntryList() function is only setting the TTree::fEntryList data member, the same function in TChain also finds correspondance between the TTrees of this TChain and the sub-lists of this TEntryList.

TEntryList and the current directory

TEntryList objects are automatically added to the current directory (like TTrees). However, in case of a TEntryList for a chain, only the top-level entry list is added, not the sub-lists for specific trees. Placing entry lists in the current directory allows calling them as a part of a TTreeFormula expression, so if the user wants to extract a sublist from a TChain entry list via the GetEntryList() or some other function, they have to add it to the current directory to be able to use it in TTreeFormula expressions.

TEntryList and TEventList

TTree::SetEventList() and TChain::SetEventList() transform a TEventList into a TEntryList See comments to those functions for more details