THaOutput for Analysis Output

Bob Michaels, updated Nov 10, 2003

e-mail: rom@jlab.org

This file : hallaweb.jlab.org/root/output.html

FEATURES

Class THaOutput can be used to control the output of the new Root/C++ analyzer . The output is defined by an output definition file, e.g. what is specified when you do 'analyzer->SetOdefFile("output.def");' and has the following elements. Note: To get vectorized formulas and histograms you must be using version 1.1 and higher of the analyzer. To get EPICS and Scaler data you need version 1.2.

Global variables written to the tree. Can include arrays -- fixed or variable size. To see a list of variables, type 'gHaVars->Print()' at the analyzer prompt.

Blocks of variables, e.g. L.* is everything in Left Spectrometer.

Formulas involving variables. These can be vectors.

Cuts. They appear in tree as 0 (false) or 1 (true). Also can be vectors.

Histograms. These can involve variables and/or formula, as well as optional cuts. The histograms can be vectors depending on the rules for dimensionality.

EPICS data (slow controls variables recorded in datastream.)

Scalers (i.e. data from devices called scalers that count things).

SYNTAX of "output.def" FILE

To add global variables, formulas, and histograms, the
syntax of each line of "output.def" is of the form

       "keyword  rest-of-line"  

where the keywords are as follows :
(keywords are case-insensitive, the rest of the line is not)

   VARIABLE  -- indicates that a global variable is to
               be added to the tree.  The next string is
               the name of the variable.  You can see a list
               of variables by typing gHaVars->Print() at
               the analyzer's root shell prompt.
               A variable can also be an array, e.g. R.s1.lt  
               Then the values in the tree will be R.s1.lt[0], 
               R.s1.lt[1], etc, up to the array size which
               is Ndata.R.s1.lt
  
   BLOCK   --  An entire block of variables are written to the
               output.  E.g. "L.*" writes all Left HRS variables.

   FORMULA -- indicates a THaFormula to add to the output.
              The next word will be the "name" of the formula result 
              in the tree. The 3rd string is the formula to evaluate.  
              Note, it cannot have spaces in it.
              Formulas can be vectors if the arrays are fixed size.

   CUT --     Like a formula, but the data are 0 (false) or 1 (true)

   TH1F, TH2F, TH1D, TH2D  -- defines histograms (1D or 2D).
               The next word is the name of the object.
               The following string (must be in single quotes) is  
               the title of the histogram.  Next, the variables
               or formulas names that are put into the histogram 
               are listed together with bin info: nbin, xlo, xhi and if 2D
               the same bin info for y.  Optional cuts can be specified 
               at the end of the line.  See examples below.  

One can add EPICS data or SCALER data to the output with a pair of
("begin", "end") statements in the output.def file.  This adds the data 
to both the main tree as well as to new trees.  The new trees are "E" 
for epics data, and "left" or "right" for the left and right HRS scalers.

     begin epics
         #  put list of variables here
     end epics

And for the "left" spectrometer scalers (similarly for "right"):

     begin scalers left
         #  put list of variables here
     end scalers

LEARN BY EXAMPLE

# --------  Example output.def  --------------------------

# Variables appear in the tree.

variable L.s1.lt[4]
variable L.s1.rt

# The 'block' variables:  All data in Right HRS go to tree.
block R.*

# Formulas can be scalers or vectors.  
# Lt4a is a scaler.
formula Lt4a 5.*L.s1.lt[4]
# Lt4b is a vector.  Access by Lt4b[0], Lt4b[1],... 
formula Lt4b 5.*L.s1.lt
# Tsm is a vector
formula Tsm 4*L.s1.lt+2*L.s1.rt+3*L.s1.lt[4]
#   Tsm[0] = 4*L.s1.lt[0]+2*L.s1.rt[0]+3*L.s1.lt[4]
#   Tsm[1] = 4*L.s1.lt[1]+2*L.s1.rt[1]+3*L.s1.lt[4]
#   etc...

# Cuts can be defined globally and used in histograms.
# Cut C1 is a scaler.  Data is 0 or 1.
cut C1 L.s1.lt[4]>1350
# Cut C2 is a vector.  Access as C2[0], C2[1],...
cut C2 L.s1.lt>1160

# Histograms can involve formulas, variables, and cuts.
# th1f, th1d, th2f, th2d supported.
# Formulas and cuts may be global, or defined in the line.
# Histograms are vector or scalers whose dimensionality is 
# determined by the dimensionality of its components.
# 1. dim(X)>=0 && dim(Y)==0 && dim(Cut)==0  --> Data in 1 histo,
#             and if dim(X)>1 all components go into 1 histo.
# 2. dim(X)>1 && (dim(Y)>1 || dim(Cut)>1) --> vector of histos
#     appear in output, the dim's must match and the indices track.
# The "eye" variable [I] becomes an index that tracks the
# index of the accompanying variable.  L.s1.lt[I] is synonymous
# with L.s1.lt.
# Prefixes SUM:, OR:, and AND: supported.
# SUM:  the sum of variables or sum of a vector formula.
# AND:, OR:  logical "and","or" of cut conditions.

TH1F  rv1n  'L-arm vdc hits on V1'  L.vdc.v1.nhit  10 0 10
th1f  rv1w  'L-arm vdc wiremap on V1'  L.vdc.v1.wire  200 0 400
TH1F  rv1z  'L-arm vdc TDC on V1'  L.vdc.v1.rawtime  200 0 2500
TH1d  hLt4  'Lt4a formula' Lt4a 100 0 9000
th1d  hLta  'Lt4b formula' Lt4b 100 0 9000
TH1F  Lt4c0 'Lt4 from var, no cut' L.s1.lt[4] 100 -1 2000
TH1F  Lt4c1 'Lt4 from var, cut' L.s1.lt[4] 100 -1 2000 L.s1.lt[4]>1300.
TH1F  Lt4c2 'Lt4 from var, cut C1' L.s1.lt[4] 100 -1 2000 C1
TH1F  Lt4c3 'Lt4 from formula, cut C1' Lt4a 100 -1 9000 C1
TH1F  Lts1 'L.s1.rt (all elements)' L.s1.rt 100 -1 2000
# Since Lt4b and C2 are vectors, get histograms Ltv0, Ltv1, ... Ltv5
TH1F  Ltv  'Vector formula, cut C2' Lt4b 100 -1 20000 C2
# The "eye" variable as R. Feuerbach requested
TH2F  a1eye 'Eye test 1' [I] L.s1.lt 14 0 7 100 0 2000
TH2F  a2eye 'Eye test 2' [i] L.s1.lt[I] 14 0 7 100 0 2000  # same as above
TH2F  a3eye 'Eye test 3' [I] Lt4b 14 0 7 100 0 9000
TH2F  a4eye 'Eye test 4' [I] Lt4b 14 0 7 100 0 9000 L.s1.lt>1300
TH2F  a5eye 'Eye test 5' [I] Lt4b 14 0 7 100 0 9000 C2
# Prefixes (SUM:  OR:  AND:)
TH1F  Lsum1 'Test of sum 1' SUM:L.s1.lt 100 0 15000 
TH2f  Lsum2 'Test of sum 2' SUM:L.s1.rt SUM:L.s1.rt 100 0 15000 100 0 2000
TH1F  Lor1  'Test of or 1' L.s1.lt[4] 100 0 2000 OR:L.s1.lt>1000
TH1F  Lor2  'Test of or 2' L.s1.lt 100 0 2000 OR:L.s1.lt>1000
TH1F  Land1 'Test of and 1' L.s1.lt 100 0 2000 AND:L.s1.lt<1200


# --------------------------------------------------
# For reference, here is a collection of things that do NOT work.
# Cannot define formula in terms of variable sized arrays.
# Exception: 'formula Lv1w L.vdc.v1.wire' results in Lv1w[0], Lv1w[1]...
# formula Lw2 L.vdc.v1.wire[2]     # error
# formula Lw3 3*L.vdc.v1.wire      # error
# A cut defined by a formula does NOT work. Perhaps in future.
# cut C4 Lta>1160
# Cannot use prefix like SUM: inside a formula.
# TH1F Lnot 'Invalid test1' 3*SUM:L.s1.lt 100 0 20000
# If Lta is a formula, then cut = Lta>1160 is illegal.
# Must instead write the formula explicitly.
# TH1F  Lte  'Lta vector formula, cut 3' Lta 100 -1 2000 Lta>1160


# --------------------------------------------------
# EPICS data to appear in regular event tree ("T") and
# a new EPICS tree ("E").  The E tree is only filled
# on EPICS events.  The E tree also has a timestamp.
# Access via T->Draw("hac_bcm_average")
# and E->Draw("hac_bcm_average")
# and E->Draw("hac_bcm_average:timestamp")
# Notice that slia:DataValid appears in the
# tree as slia_DataValid (i.e. ":" is replaced
# by "_").  This replacement makes TTree::Draw
# work properly. Note also, the value of 
# slia_DataValid is 71 if slia:DataValid
# was "Yes" (case senstive!), 422 if "No" and 
# 0 otherwise.  

begin epics
   hac_bcm_average
   IPM1H04A.XPOS
   IPM1H04A.YPOS
   IPM1H04B.XPOS
   IPM1H04B.YPOS
   slia:DataValid  Yes=71 No=422
end epics

# Rules about EPICS variable assignment:
# You can now do things like this in
# the output definition file

begin epics
   FB_A:use_RF 'RF On'=14 'RF Off'=52
   slia:DataValid  Yes=1 No=0  
end epics

# The rule is that everything between single
# quotes is EPICS data (string type) which, 
# if found in the datastream, gets assigned 
# the numerical value after the equal sign.  
# So, if the string "RF On" is found, you get
# 14 in the tree.  The strings with white space
# must contain single quotes.  The other strings
# could contain single quotes, but it is not
# necessary (e.g. slia:DataValid 'Yes'=1).

# Examples of *GOOD* syntax:

begin epics
   hac_bcm_average
   IPM1H04A.XPOS
   FB_A:use_RF 'RF On'=14 'RF Off'=52
   slia:DataValid  Yes=1 No=0 
   hla:DataValid   Fred=2 'No'=22 Yes==452
end epics 

# Examples of *BAD* syntax:

begin epics
   Joe Momma    # erroneous space
   FB_A:use_RF 'RF On=14  # missing a quote
   slia:DataValid  Yes = 1 # erroneous space 
   hla:DataValid   Fred= 2 # erroneous space 
end epics 




# --------------------------------------------------
# Scalers to appear in the regular event tree ("T") and
# new scaler trees, one for each bank.
# Banks are "right", "left" (and perhaps 3rd arm).
# Access to data:
# T->Draw("right_bcm_u1"), right->Draw("bcm_u1")  for R-arm
# T->Draw("left_bcm_u1"), left->Draw("bcm_u1")  for L-arm
# "default" and "default_helicity" cause a list
# of normalization scalers to appear.  Examples:
# T->Draw("right_trigger_1")  from default list
# T->Draw("right_P_trigger_1") helicity plus ("P")
# T->Draw("right_M_trigger_1") helicity minus ("M")
# also right->Draw("trigger_1"), etc. appear.
# Implictly the values are RATES (Hz) unless one
# specifies the "counts" flag.
# "myclk 8 7"  is a rate from slot 8 chan 7 and
# appears as T->Draw("myclk").
# "myclkc 8 7 counts" are raw counts, slot 8, chan 7.

begin scalers right
   default      # this expands to "trigger_1", "bcm_u1", etc...
   default_helicity   # expands to "P_trigger_1", "M_trigger_1" ...
   mypulser 7 3
   myclk 8 7    
   myclkc 8 7 counts
end scalers

begin scalers left
   default
   default_helicity
   mypulser 4 3
   myclk 4 7
   myclkc 4 7 counts
end scalers

EXPECTED RESULTS

Below is a table showing examples of lines in the output definition file (output.def) and the corresponding expected output.

Behavior of Output
            output.def line                   Example How to Access                Comments

VARIABLE L.s1.lt[4]    T->Draw("L.s1.lt[4]")

VARIABLE L.s1.rt    Tree has L.s1.lt[i], i = 0,1,...Ndata.L.s1.lt    Array

   BLOCK R.*    T->Draw("R.s1.lt[0]"), etc.    All variables in Right (R) HRS.

FORMULA Lt4a 5*L.s1.lt[4] T->Draw("Lt4a") Scaler Formula

FORMULA Lt4b 5*L.s1.lt Tree has Lt4b[i], i = 0,1,...Ndata.Lt4b Vector Formula

CUT C1 L.s1.lt[4]>1350 T->Draw("C1") Scaler Cut

CUT C2 L.s1.lt>1350 Tree has C2[i], i = 0,1,...Ndata.C2 Vector Cut

TH1F rs 'Scint' R.s1.lt 100 0 2000 rs->Draw() Histogram (all elements of R.s1.lt[] in 1 histo)

TH1F rs4 'Scint' R.s1.lt[4] 100 0 2000 R.s1.lt[4]>500 rs4->Draw() Cut R.s1.lt[4]>500 is optional

TH1F rv 'Scint' R.s1.lt 200 0 2000 R.s1.lt>500 rv0->Draw(), rv1->Draw, ... rv5->Draw() Vector Histogram (size 6)

output.def line	Example How to Access	Comments
VARIABLE L.s1.lt[4]	T->Draw("L.s1.lt[4]")
VARIABLE L.s1.rt	Tree has L.s1.lt[i], i = 0,1,...Ndata.L.s1.lt	Array
BLOCK R.*	T->Draw("R.s1.lt[0]"), etc.	All variables in Right (R) HRS.
FORMULA Lt4a 5*L.s1.lt[4]	T->Draw("Lt4a")	Scaler Formula
FORMULA Lt4b 5*L.s1.lt	Tree has Lt4b[i], i = 0,1,...Ndata.Lt4b	Vector Formula
CUT C1 L.s1.lt[4]>1350	T->Draw("C1")	Scaler Cut
CUT C2 L.s1.lt>1350	Tree has C2[i], i = 0,1,...Ndata.C2	Vector Cut
TH1F rs 'Scint' R.s1.lt 100 0 2000	rs->Draw()	Histogram (all elements of R.s1.lt[] in 1 histo)
TH1F rs4 'Scint' R.s1.lt[4] 100 0 2000 R.s1.lt[4]>500	rs4->Draw()	Cut R.s1.lt[4]>500 is optional
TH1F rv 'Scint' R.s1.lt 200 0 2000 R.s1.lt>500	rv0->Draw(), rv1->Draw, ... rv5->Draw()	Vector Histogram (size 6)