Hall A Analyzer

h1. Configuring Analysis Output

Bob Michaels

e-mail:    rom@jlab.org

h2. 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 formul40.65a, 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).

h2. SYNTAX   of "output.def"   FILE

To add global variables, formulas, and histograms, the

syntax of each line of "output.def" is of the form

<pre>

keyword  rest-of-line

</pre> 

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  40.65

               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 epics40.65

         #  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

h2. LEARN   BY   EXAMPLE

<pre>

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

# Variables appear in the tree.

variable L.s1.lt[4]

variable L.s1.rt40.65

# 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

</pre>

h2. EXPECTED   RESULTS

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

|\3=.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) |