| Attachment 2: |
IntroToAnitaData.txt
An Introduction to ANITA Data
Overview:
- Anita data structures
- ROOT structures
- Using ANITA data via ROOT
- The AnitaTools software suite
ANITA Data Structures
ANITA post-flight data processing
"raw" file structures are formatted into ROOT
- header (RawAnitaHeader.h)
- information about the event
- time stamps, trigger type, trigger masks, etc
- calibrated event (CalibratedAnitaEvent.h)
- time-calibrated voltage/timestamp waveforms
- 48 antennas * 2 pols + 12 clocks = 108 channels
- gps (Adu5Pat.h)
- lat, lon, altitude, heading, (pitch & roll too, but not very good, at least for ANITA-3)
- other housekeeping data (temps, voltages, etc.)
ROOT structures
ROOT is a predominant utility in particle physics, and handles large amounts of data well
How to learn ROOT
Web search: specify a ROOT class name (eg TTree) or say CERN ROOT when you search
this will take you to Root-talk and other resources
ROOT class documentation - very useful once you get used to it
ROOT is NOT a relational database, but its functions usually suffice for us
TTree is the structure for representing data:
does not much resemble a physical tree
contains "entries" ~analagous to: rows in a table
records in a file
"branch": corresponds roughly to: column in a table
field in a record definition
"leaf": specific value for a branch in a particuilar entry
Histograms are the predominant data structure for analysis
TH1I (a 1-D histogram with integer bin content (e.g., a counter))
TH1F (a 1-D histogram with float bin content (e.g., a weighted count))
available up to 3D (e.g., TH3F)
Draw() method offers many options; see THistPainter
(stuff is generally well documented but can be hard to find)
Combine histograms using Add/Subtract/Mult/Divide (e.g., efficiency = acceptances / total counts)
TGraph and TGraph2D also available
I usually try a histogram first
TFile is the file interface
can contain ROOT objects including TTree, histograms, canvases, etc.
Managing TFiles is tricky when opening multiple files and saving output to files
ANITA files/trees
headFile<runNumber>.root headTree event headers
calEventFile<runNumber>.root eventTree calibrated events
gpsEvent<runNumber>.root adu5PatTree event-specific GPS
Reading data from a tree
TFile* myFile = new TFile("headFile342.root"); // Open the file that contains the tree
myFile->ls() // list the contents of the file
TTree* headTree = (TTree*)myFile->Get("headTree"); // get the tree from the file
headTree->Print(); // list the tree's structure
RawAnitaHeader* myHeader = 0; // set up a variable to receive the header data
headTree->SetBranchAddress("header", &myHeader); // tell ROOT where to store this branch when an entry is read
Iterate through a tree and populate a histogram
TH1I* myHist = new TH1I("name", "title", #bins, low, hi);
for (int e=0; e<headTree->GetEntries(); ++e) {
headTree->GetEntry(e);
myHist->Fill(myHeader->triggerTime);
}
Also consider:
TTree::BuildIndex(eventNumber); // you can have two keys if you want, but not more
myTree->GetEntryWithIndex(eventNumber); // get the entry for this exact event number
int myTree->GetEntryNumberWithIndex(...) // get the entry NUMBER for this EXACT key value (then feed it to GetEntry())
int myTree->GetEntryNumberWithBestIndex(...) // get the entry NUMBER with the CLOSEST key value to this key
headTree->AddFriend(otherTree) // when I get an entry from headTree, the corresponding entry is gotten from the friend tree
Displaying a histogram
TCanvas* is the main display container
consists of one or more TPad objects
TCanvas::Divide(c,r) partitions it into columns, rows
TCanvas* myCanv = new TCanvas(name, title, horzSize, vertSize); // instantiate, name must be unique
myCanv->cd(); // select the canvas for display
myHist->Draw(); // Draw the histogram
TChain
TChain allows you to combine multiple trees of the same name and structure (e.g. muptiple run numbers)
TChain* myChain = new TChain("treeName");
myChain->Add(filename) // add the tree called "treeName", contained in the file, to the chain
// if file does not exist, or does not contain the tree, you get a warning
then access the TChain "just like" a TTree.
myChain-<GetEntry(e) etc.
Notes on the indexing of histogram bins:
an overall bin number exists, but is not very useful unless you just want to iterate through all bins
dimension-specific bin numbers: contained in TAxis objects of the hist e.g., myHist->GetYaxis()->GetNBins())
bin 0 = underflow
bin 1 = "first" bin
bin axis->GetNBins() is "last" bin
bin axis->GetNBins()+1 is "last" bin
Projection methods allow you to take a "slice" from a 2D or 3D histogram
TBrowser
allows you to browse and open files without declaring variables for them
You can define histograms using existing or derived values in the tree, and apply cuts
good for exploring, not so much for final plots
right-click on your tree and open a "TTreeViewer"
more flexible options for plotting, than in TBrowser
AnitaTools (edited by Cosmin Deaconu, Univ Chicago)
on GitHub (see Anita ELOG 672)
to find stuff, go into buildAnita/components subfolder of your AnitaTools instance
search the file browser or grep at terminal
the "autobuilder" will wipe out ans rebuild your instance, after you make changes, do make/make install instead of autobuilder
RawAnitaHeader header
CalibratedAnitaEvent event
Adu5Pat gps
UsefulAnitaEvent use this to access event data
UsefulAnitaEvent* myEvent = new UsefulAnitaEvent(calEvent);
UsefulAdu5Pat use this to access gps data
UsefulAdu5Pat* myGps = new UsefulAdu5Pat(rawGps)
AnalysisWaveform: class that allows FD and TD access / changes to waveform
AnitaEventSummary: event features, HAS-A list of AnalysisWaveform's
FilteredAnitaEvent: built around (inherits from?) UsefulAnitaEvent : event waveforms are filtered upon instantiation
FilteredAnitaEvent HAS-A array of AnalysisWaveform's
FilteredEvent* filteredEvent = new FilteredAnitaEvent(event, strategy, gps, header)
WaveformInfo: class containing waveform features
Analyzer: "crank-turner" for analyzing a single event
AnalysisConfig: analysis parameters (e.g., normalization type)
Analyzer HAS-A AnalysisConfig
AnalysisConfig* cfg = new AnalysisConfig(); // instantiate an AnalysisConfig
cfg->normalization_option = normalizationStandard; // set normalization type
cfg->td_pad_factor = timeDomainPadFactor; // set padding factor
bool iActive = true; // enable verbose output
Analyzer* analyzer = new Analyzer(cfg, iActive); // instantiate my analyzer
AnitaEventSummary* eventSummary = new AnitaEventSummary();
analyzer->analyze(filteredEvent, eventSummary); // turn the analysis crank and put results in eventSummary
Correlator: does the correlation calculations and sky maps (Analyzer HAS-A Correlator)
analyzer->GetCorrelator()->GetCorrelation() // (this syntax is probably wrong)
FilterStrategy: just a list of filter operations
FilterOperation: abstract class to in which filter is implemented (waveforms can be filtered differently)
extend this class and implement method Process(FilteredAnitaEvent*)
UniformFilterOperation: abstract class to in which filter is implemented (if all waveforms to be filtered the same)
extend this class and implement method ProcessOne(AnalysisWaveform*)
AnitaGeomTool: payload geometry stuff
must have your AnitaTools lib and include dirs in your include/lib paths
#include the required headers and compile with -lAnitaEvent, -lAnitaAnalysis, etc.
|