SLAC	PEP-II
BABAR
SLAC<->RAL

HEPIC	E,S & H	Databases	PDG	HEP preprints
Organization	Detector	Computing	Physics	Documentation
Personnel	Glossary	Sitemap	Search	Hypernews

Workbook Home	Introduction	Account Setup	QuickTour	Packages	Modules
Event Information	Tcl Commands	Editing	Compile and Link	Run the Job	Debugging	Check this page with the W3C Validator (More checks...)
Parameters	Tcl Files	Find Data	Batch	Analysis	ROOT Tutorial	Check this page with the W3C Validator (More checks...)

Analysis in PAW

Introduction

This WorkBook chapter is designed to introduce the Fortran-based PAW analysis package. Although PAW has largely been superceded by ROOT, it is still very popular, particularly among physicists who have been using the package for many years, and also among newer workers who enjoy the quickness with which one can navigate through ntuples.

Though based on Fortran, the PAW compiler isn't as fussy about cases as Fortran, and will allow lower-case characters to be used.

Generating an HBOOK file for analysis in PAW

In the Quicktour, the output of your analysis job was a ROOT file called myHistogram.root. To obtain a HBOOK file for analysis in PAW instead, you will need to edit your snippet.tcl file to say:

set BetaMiniTuple hbook
set histFileName myHistogram.hbook

instead of "set BetaMiniTuple root" and "set histFileName myHistogram.root." As you can probably guess, with these settings your output will be written to a hbook (PAW) file called myHistogram.hbook. Now rerun your job (the commands you used in the Quicktour are shown below, for reference):

    > workdir> BetaMiniApp snippet.tcl
    > mod talk KanEventInput
    KanEventInput> input add /store/SP/R18/001237/200309/18.6.0b/SP_001237_013238
    KanEventInput> exit
    > ev beg -nev 40
    > exit

(Note that you did not have to recompile or relink, because you changed only a tcl file, not C++ code. That is one of the big advantages of using tcl files.) Now you should have a myHistogram.hbook in your workdir directory. A copy of the file myHistogram.hbook from running the code above is also available here.

The Mechanics of a PAW Session : Viewing Histograms

You can look at HBOOK histograms with PAW (Physics Analysis Workstation). In the session below we will examine the output file myHistogram.hbook that you just created. After that we will open another hbook file with some ntuples and more histograms and extend our abilities with PAW.

You can usually invoke PAW with the simple command: paw, which should get you to /cern/pro/bin/paw.

Start your paw session from your workdir, as that is where the output file from the QuickTour session will be:

   ana31/workdir> paw

The system should respond with something like

 ******************************************************
 *                                                    *
 *            W E L C O M E    to   P A W             *
 *                                                    *
 *       Version 2.11/13       6 December 1999        *
 *                                                    *
 ******************************************************
 Workstation type (?=HELP) <CR>=1 :

If the environmental variable DISPLAY is correctly defined for your session, a simple carriage-return will suffice here. If not you need to type:

    Workstation type (?=HELP) <CR>=1 : 1.aaa.bbb.ccc.ddd

where aaa.bbb.ccc.ddd is the IP address of your display.

In either event, a window called HIGSZ_01@hostname will now open and you will get some output like:

 Version 1.26/04 of HIGZ started
 pawlogon.kumac executing
 In private pawlogon.kumac.
PAW >

The file ~/.pawlogon.kumac would contain your own customization of PAW, but you don't need this file to proceed. The workdir package comes with a sample pawlogon.kumac.

PAW offers an extensive, if primitive, online help facility. When you type "help", you get a menu of general topics.

   PAW > help
 
   From  /...
 
    1:   KUIP          Command Processor commands.
    2:   MACRO         Macro Processor commands.
    3:   VECTOR        Vector Processor commands.
    4:   HISTOGRAM     Manipulation of histograms, Ntuples.
    5:   FUNCTION      Operations with Functions. Creation and plotting.
    6:   NTUPLE        Ntuple creation and related operations.
    7:   GRAPHICS      Interface to the graphics packages HPLOT and HIGZ.
    8:   PICTURE       Creation and manipulation of HIGZ pictures.
    9:   ZEBRA         Interfaces to the ZEBRA RZ, FZ and DZ packages.
   10:   FORTRAN       Interface to MINUIT, COMIS, SIGMA and
                                                    FORTRAN Input/Output.
   11:   NETWORK       To access files on remote computers.
   12:   OBSOLETE      Obsolete commands
 
   Enter a number ('0'=Top, '\'=one level back, 'Q'=command mode):

Since we are interested in manipulating histograms, we choose topic 4:

   Enter a number ('0'=Top, '\'=one level back, 'Q'=command mode): 4
 
   Menu /HISTOGRAM 
 
    1:   /HISTOGRAM    Manipulation of histograms, Ntuples.
 
   From  /HISTOGRAM/...
 
    2: * FILE          Open an HBOOK direct access file.
    3: * LIST          List histograms and Ntuples in the current directory.
    4: * DELETE        Delete histogram/Ntuple ID in Current Directory (memory).
    5: * PLOT          Plot a single histogram or a 2-Dim projection.
    6: * ZOOM          Plot a single histogram between channels ICMIN and ICMAX.
    7: * MANY_PLOTS    Plot one or several histograms into the same plot.
    8: * PROJECT       Fill all booked projections of a 2-Dim histogram.
    9: * COPY          Copy a histogram onto another one.
   10: * FIT           Fit a user defined (and parameter dependent) function to
                       a histogram ID (1-Dim or 2-Dim) in the specified range.
   11:   2D_PLOT       Plotting of 2-Dim histograms in various formats.
   12:   CREATE        Creation ('booking') of HBOOK objects in memory.
   13:   HIO           Input/Output operations of histograms.
   14:   OPERATIONS    Histogram operations and comparisons.
   15:   GET_VECT      Fill a vector from values stored in HBOOK objects.
   16:   PUT_VECT      Replace histogram contents with values in a vector.
   17:   SET           Set histogram attributes.
 
   Keyword "HISTOGRAM" found in commands:
 
   18: * /FUNCTION/FUN1  
                       Create a one dimensional histogram and fill the bins with 
                       the values of a (single-valued) function.
   19: * /GRAPHICS/PRIMITIVES/HIST  
                       Draw an histogram defined by arrays X and Y.
   ______
    0:                 Top level menu
   Enter a number ('0'=Top, '\'=one level back, 'Q'=command mode):

Finally, we type "2" to learn about accessing the .hbook file.

The response to this comes as the output of a more for me. I think it may be different for you depending on how your PAW session is set up. If you get to the end of a listing and see "END" in reverse video (where text and background switch colors), you are probably in the more command; typing a "q" will get you back to the PAW prompt.

   Enter a number ('0'=Top, '\'=one level back, 'Q'=command mode): 2
    
   Command "/HISTOGRAM/FILE" :
    
    * HISTOGRAM/FILE LUN FNAME [ LRECL CHOPT ]
    
      LUN        I 'Logical unit number' R=0:128
      FNAME      C 'File name'
      LRECL      I 'Record length in words' D=1024
      CHOPT      C 'Options' D=' '
    
      Possible CHOPT values are:
    
      ' ' Existing file is opened (read mode only).
       N  A new file is opened.
       U  Existing file is opened to be modified.
       D  Reset lock.
    
      Open an HBOOK direct access file.  If LUN is 0 the next free
      logical unit will be used.  If LRECL is 0 the system will
      determine the correct record length of an existing file.

All this might look a little daunting, but you will only need to learn a few simple commands to start making professional-looking histograms.

Another help feature of PAW is the usage command:

   PAW > usage hist/file
 
    * HISTOGRAM/FILE LUN FNAME [ LRECL CHOPT ]

When you open a file, you use assign that file a "logical unit number". This allows you to work with multiple files within PAW.

So, to open our little .hbook file, we type the command:

   PAW > hist/file 1 myHistogram.hbook

Note also that you can abbreviate paw commands down to unambiguous strings, so

   PAW > h/fil

would also work.

Now we want to know what's in our histogram, so we study the list command:

   PAW > usage h/list

Which tells us:

    * HISTOGRAM/LIST [ CHOPT ]

So enter:

   PAW > h/list

Which gives us:

 
 ===> Directory :
          1 (1)   MC reco abs mtm difference
          2 (1)   Reco track momentum
          4 (1)   TagInspector Status
          3 (1)   Tracks per Event

(You may or may not have other histograms, depending on how far you gone in the Workbook. My version of myHistogram.hbook comes from the Quicktour stage, so only the Tracks per Event histogram is there. The left-most number is the id number of the histogram - this is what you use to identify the histogram you want to plot:

   PAW > usage h/plot

    * HISTOGRAM/PLOT [ ID CHOPT ]

So now we can plot our histo just as we did in the quicktour:

   PAW > h/pl 3

Note that if you have your HIGZ window under any other window, the image often won't appear complete, so you need to have the HIGZ window on top when you give the h/pl command.

As usual, to end the session:

   PAW > exit

This section has discussed using PAW to view the myHistogram.hbook file from the sample analysis job. More details on using PAW will be covered in the following sections of this chapter.

pawlogon.kumac - helpful commands to get the session going

As mentioned above, the pawlogon.kumac file contains commands that are executed automatically when a PAW session is started. Note that the file will only be found if the PAW session is started in the directory where the pawlogon.kumac file is sitting.

While it is not necessary to have a pawlogon.kumac, it doesn't take long until you realise it is actually rather nice to have one. A few sample commands that you might like to save directly to a pawlogon.kumac file in say, workdir, are:

* my pawlogon.kumac file
mess pawlogon.kumac executing
shell pwd
filecase KEEP
opt zfl1

These commands are:

* my pawlogon.kumac file

This is just a comment. Any lines starting with a "*" are ignored by PAW.

mess pawlogon.kumac executing

"mess" is a message - it just prints the words "pawlogon.kumac exiting" to the screen to tell you your logon kumac is being run now.

shell pwd

A "shell" command is one where the user gets access to the shell in which PAW is running and can execute normal commands. In this case, the command is to tell us the path of the directory we are in - in this example, when you start up paw it should tell you the path of your workdir.

filecase KEEP

This is a good command to keep handy. PAW doesn't know about capitals unless you execute this command. A file called MyFile.hbook would otherwise not be able to be opened in a PAW session.

opt zfl1

This very obscure command is great - it allows you to interactively save your pictures using the "picture" commands. More on that later. But it's highly recommended to have this command in your pawlogon.kumac.

kumacs I - files with multiple commands

While this section will be mostly be deferred to later in the chapter, the basic mechanism of kumacs should be mentioned here so that if you still have a PAW session open, you can make the pawlogon.kumac file above and run it without having to restart PAW.

A kumac is a text file with a bunch of PAW commands. It is common to save a frequently used collection of commands in a kumac - for example, to do a certain nice piece of presentation or, as in the case above, to set up to be able to use capitals, know which directory you're in and be able to print images directly to files.

Make sure you have saved the above 6 commands into your workdir in a file called pawlogon.kumac. You'll probably have to overwrite a very insubstantial default pawlogon.kumac that got made the first time you started PAW in workdir, but that's ok. Now start a paw session, and this time after the HIGZ_01 window has opened, a few new lines will appear in the command line window like

 pawlogon.kumac executing
/afs/slac.stanford.edu/u/br/penguin/ana31/workdir

If you are in an active PAW session, you can execute any kumac, including pawlogon.kumac by just giving the name of the file, e.g.:

exec pawlogon

where the extension is not necessary, but may also be used in the execute command.

A larger PAW file to study

A larger hbook file which can used with the commands below is available here. This is an hbook file called pawfile.hbook which is in the same directory as this WorkBook chapter.

Now start a new PAW session and open this file:

workdir> paw
PAW > h/fil 1 pawfile.hbook

use h/lis and h/pl to have a look around the histograms in the file - note that several are empty.

Several open files in PAW

You might want to have several files open at once in PAW, for example to compare different outputs. In the current session, we will see how this works by opening our myHistogram.hbook file again, but this time with a different logical unit number:

PAW > h/fil 2 myHistogram.hbook

If we now do the h/lis command, we'll see a listing of what is in the myHistogram.hbook file - PAW has changed its focus to the most recently-opened file. To change back to the file we opened with logical unit number 1, we simply do:

PAW > cd //LUN1

And now an h/lis command shows us we are back with pawfile.hbook.

The numbers in brackets after the histo id number on the listing of a hbook file are the dimension of the histos. You will see that most of the histograms are 1D, though there are a few 2-dimensional histos also. There are also two entries with (N) on them. These are ntuples and will be discussed in the next section.

Ntuples in PAW

Ntuples are basically like spreadsheets - one row for each event, one column for each type of information. A simple example to help you envisage the structure of an ntuple is as follows:

            Energy   px   py   pz
event 1     5.5      .4   .4   .34
event 2     4.5      .1  -.9   .45
event 3     1        .3   .5   -.1
event 4     9        -.4  .5   .6

This ntuple has information from 4 events, and the quantities stored are the energy and the x, y and z components of the 3-momentum.

As with normal spreadsheets, you can histogram any of these quantities, and you can also choose to view any of these quantities subject to constraints that that or any other quantity in the ntuple must satisfy.

First we want to look inside one of the ntuples. Let's look at ntuple 40, the one called "results" and see what quantities are in the columns:

PAW > nt/print 40

Here we use "nt" since we are executing an ntuple command, and we give the id number of the ntuple. The output includes:

 *     52   * R*4  *         *              * DEFAULT  * dauA3energycms
 *     53   * R*4  *         *              * DEFAULT  * dauB3energycms
 *     54   * R*4  *         *              * DEFAULT  * pi03energycms
 *     55   * R*4  *         *              * DEFAULT  * fourpimass
 *     56   * R*4  *         *              * DEFAULT  * omegaMass
 *     57   * R*4  *         *              * DEFAULT  * fourpimass2
 *     58   * R*4  *         *              * DEFAULT  * firstcombmass
 *     59   * R*4  *         *              * DEFAULT  * secondcombmass
 *     60   * R*4  *         *              * DEFAULT  * rhotagmass
 ******************************************************************
 *  Block   *  Entries  * Unpacked * Packed *   Packing Factor    *
 ******************************************************************
 * DEFAULT  *  42       * 384      * 384    *       1.000         *
 * Total    *    ---    * 384      * 384    *       1.000         *
 ******************************************************************
 * Blocks = 1            Variables = 60           Columns = 96    *
 ******************************************************************

You don't need to know much about the information here - blocks are unimportant, there are 60 variables (that's the columns in our illustration), and 96 columns (this is the number of events). Items like R*4 tell you the entries are real numbers (floats).

To view information for any variable, you need to enter the ntuple number as well as the variable name, for example:

PAW > nt/pl 40.fourpimass2

Viewing a 2-D histogram of ntuple quantities

To view a 2D histogram of, say, dauA3energycms against dauB3energycms, you can do:

PAW > nt/pl 40.dauA3energycms%dauB3energycms

In this case you'll get a fairly sparce scatter plot, but you get the point. Note that you must be plotting quantities from the same ntuple against each other.

Using cuts

It is very easy to use cuts in PAW - you just give the plot command followed by a command stating which cut you want. Some examples are:

PAW > nt/pl 40.fourpimass omegaMass.lt.40
PAW > nt/pl 40.fourpimass fourpimass.gt.1.1
PAW > nt/pl 40.fourpimass omegaMass.lt.40.and.fourpimass.gt.1.1
PAW > nt/pl 40.fourpimass fourpimass.eq.1.2

The second line illustrates that it's ok to have decimal numbers along with the dots around the logical operators, while the third line shows how to use two cuts at once. Cuts can also be applied to n-dimensional histograms.

You can also define cuts which you might use several times with the syntax, e.g.

PAW > cuts $1 omegaMass.lt.40
PAW > cuts $2 fourpimass.gt.1.1

Then you just need to give the cut number in your plot command:

PAW > nt/pl 40.fourpimass $1.and.$2

This is a very useful way to use cuts if you are making several histograms. Note that you can overwrite cut $N whenever you want.

Projecting an ntuple onto a histogram

In order to make use of PAW's histogram fitting abilities, ntuple information needs to be projected onto a histogram. The procedure to do this is as follows:

h/create/1d 100 'four [p] mass' 20 0.9 1.6
nt/proj 100 40.fourpimass
h/pl 100

The first line here creates a 1-dimensional histogram with logical unit number (LUN) 100 (just pick a number that isn't already used), gives it the title "four pi mass", with a greek letter to represent pi. This histogram has 20 bins, and a range of 0.9 to 1.6.

The second line projects the column called fourpimass of ntuple 40 onto our new histogram. Finally, the third line plots our new histogram.

You can actually just plot the ntuple column without projecting it onto a histogram, it's just that you don't get the full functionality that PAW offers for histograms. It can be useful to just quickly view the contents of a column though:

nt/plot 100 40.fourpimass

Further histogram and data manipulation

Fitting a histogram

You can either define your own fit function (beyond the scope of this WorkBook chapter) or use pre-defined fit functions provided by PAW. To give two examples:

h/fit 100 G
h/fit 100 p6

To see fitting using a Gaussian and a 6th order polynomial, respectively.

Plotting a function

There are two ways to plot a single-valued function with PAW: either using a simple function, or writing a separate fortran routine defining your function and executing that. The required syntax is:

  fun/plot ufunc xlow xup [options]

where ufunc is the name of your function - either the simple function itself or the file in which the function is defined, xlow and xup are the lower and upper ranges of the function argument, respectively, and the options available are:

C: draw a smooth curve
S: superimpose plot on top of existing picture
+: add contents of ID to last plotted histogram
L: connect the points with lines
P: draw the current marker type at each channel (bin)
*: draw a * at each channel

A simple function can be plotted, for example:

 fun/plot  sin(x)/x -100 100

Whereas a more complicated function should be first defined in a text file, for example, if we write the file FTEST.F

 FUNCTION FTEST(X)
 FTEST=SIN(X)*EXP(-0.1*X)
 END

Making sure to use capitals to keep compatible with Fortran compilers (though the PAW compiler isn't as fussy), and using for simplicity X for the argument. Now you can plot your new function with the one-line command

 FUN/PLOT FTEST.F(X) 0 50

For two-dimensional plots, type

 help fun2

to find out about the fun2 function for plotting 2d functions, and the many options for plotting as surfaces, lego plots, etc, with a range of colour options

Plotting data points

Two-dimensional data arrays can be plotted if stored in an ascii file of the form, say mydata.dat:

    VECTOR/DELETE *
    VECTOR/READ   X,Y mydata.dat
    GRAPH $VDIM(X,1) X Y

To plot 1-dimensional arrays, i.e. single lists of numbers, one method is to read in the list as a vector, then put the contents of that vector into a 1D histogram, and plot the resulting histo. To do this, you should first determine the size of the vector - either by using something like the command wc -l at the unix prompt on the data file, or by using in PAW

v/print myvect

To display the contents of the vector, and thereby find out the number of entries there are.

An example of the relevant commands in PAW to plot the list of numbers 23,24,25,45,56 stored as a single column in the file myvect.dat is:

v/read myvector myvec.dat
v/print myvector                //look at the number of entries
                                //in this case it is 5

h/cr/1D 100 'vector picture' 5 0 100  //id,name,numbins,xlow,xup
h/put_vec/contents 100 myvector //put contents of myvector into
                                //histo with id number 100
h/pl 100                        //plot as a plain histogram
h/pl 100 c s      //overlay curve thru points on same plot

The options for plotting histograms are the same as those for plotting functions.

Changing the attributes of a plot

A nice histogramming function available in PAW which should be mentioned is the many_plots function. It allows the user to plot several histograms (up to a fairly large number) on the one plot. The syntax is:

h/many_plots 1 2 45 67

Of course, a very useful thing would be to be able to plot several histos on separate boxes in the same window. This is done by invoking the zone command before plotting the images. For example:

zone 2 2
h/pl 3
h/pl 4
h/pl 9
h/pl 10

It can also be desirable to put two histos on the same plot, but with different colours:

zone 1 1
set hcol 2
h/pl 9
set hcol 3
h/pl 10 s
set hcol 1

Here the "s" tells PAW to put the histos on the same plot.

To plot a filled-in histogram, you need to use numbers like 1002:

set hcol 1002
h/pl 9 
set hcol 1

To change between log and linear axis, use:

opt liny
opt logy
opt linx
opt logx

Finally, in order to refresh the higz-window, you need type the following command at the PAW prompt (or include it in the pawlogon.kumac):
PAW > IGSET 2buf 11

Saving plots into a postscript file

Here's where you wanted to have your

opt zfl1

command in your pawlogon.kumac file. If you don't already have that line executed, enter it now. This line now makes it possible to write the output you make to a file. Anything you have made before executing this command isn't stored in the picture buffer, so can't be saved.

Having executed this command, you can save postscript or eps files with the command:

p/print myfile.ps
p/print myfile.eps

Where the extension will be recognised by PAW and you will get the filetype you expect.

To write to postscript files in any other way requires more knowledge of PAW which is beyond the scope of this chapter, but can be investigated by looking at the "file" options - namely, f/file.

PAW on Windows 95/NT and Linux

Versions of PAW for Intel based platform are available from the PAW home page.

Windows 95/NT

Download all of the binaries and libraries from the CERNLIB server.
For development purposes, you also have the option to download the complete distribution.

Windows 95 users need to define the HOME environment variable in the autoexec.bat file as follows:
set HOME=c:\tmp

Related Documents:

Latest CERNLIB version

Linux

Download all of the binaries and libraries from the CERNLIB server.
For development purposes, you also have the option to download the complete distribution.

Related documents:

Latest CERNLIB version

General Related documents:

PAW: Physics Analysis Workstation Home Page
The PAW Reference Manual online
HBOOK Reference Manual (CERN Program Library Long Writeup Y250)

Back to Workbook Front Page

Send comments to Workbook Team.

Analysis in PAW

Contents:

kumacs I - files with multiple commands