Make your own free website on Tripod.com
/NTUPLE


Ntuple creation and related operations.

An Ntuple is a set of events, where for each event the value of a number of variables is recorded. An Ntuple can be viewed as
a table with each row corresponding to one event and each column corresponding to given variable. The interesting properties
of the data in an Ntuple can normally be expressed as distributions of Ntuple variables or as correlations between two or
more of these variables. Very often it is useful to create these distributions from a subset of the data by imposing cuts on
some of the variables.

Typically, an Ntuple is made available to PAW by opening a direct access file; this file, as been previously created with an
program using HBOOK. A storage area for an Ntuple may also be created directly using NTUPLE/CREATE; data may then
be stored in the allocated space using the NTUPLE/LOOP or NTUPLE/READ commands. Other commands merge Ntuples
into larger Ntuples, project vector functions of the Ntuple variables into histograms, and plot selected subsets of events.

 /NTUPLE/CREATE idn title nvar chrzpa nprime varlist
 

 IDN
         C
           Ntuple Identifier
 TITLE
         C
           Ntuple title D=' '
 NVAR
         I
           Number of variables D=1 R=1:512
 CHRZPA
         C
           RZ path D=' '
 NPRIME
         I
           Primary allocation D=1000
 VARLIST
         C
           Names of the NVAR variables Vararg
 

Create a Row_Wise_Ntuple. (See below how to create a Column_Wise_Ntuple). The Ntuple may be created either purely in
memory or possibly using an automatic overflow to an RZ file. Memory allocation works in the following way. If CHRZPA
= ' ', then a bank of NPRIME words is created. When the space in this bank is exhausted at filling time, a new linear
structure of length NPRIME is created and this process will be repeated should the structure become exhausted. If CHRZPA
contains the top directory name of an already existing RZ file (as declared with HISTO/FILE), then a bank of length
NPRIME is also created, but at filling time, this bank is moved to the RZ file when full, and then it is overwritten by any new
entries. The Ntuple can be filled by calling HFN from an interactively defined subroutine called by the command
NTUPLE/LOOP or by NTUPLE/READ. The number of variables per data point is given in the parameter NVAR.

To create a Column_Wise_Ntuple, create a file, eg. newnt.f with:

 
            Subroutine Newnt
      *
      *        Example of a COMIS subroutine to create a Ntuple interactively.
      *        Data is read from a text input file
      *
            character*8 mother,in1,in2
            common/ntupc/mother,in1,in2
            common/ntupr/xover
      *
            lin=41
            lout=42
            id=1
            open(unit=lin,file='datafile.dat',status='old')
            call hropen(lout,'NTUPLE','New_Ntuple.hbook','N',1024,istat)
      *
            call hbnt(id,'New Ntuple',' ')
            call hbname(id,'ntupr',xover,'XOVER')
            call hbnamc(id,'ntupc',mother,'MOTHER:c*8,in1:c*8,in2:c*8')
      *
        10  read(lin,1000,end=20,err=20)xover,mother,in1,in2
      1000  format(e15.7,2x,a,7x,a,7x,a)
            call hfnt(1)
            go to 10
      *
        20  call hrout(id,icycle,' ')
            call hrend('NTUPLE')
            close (lin)
            close (lout)
            end

and then call this routine via the CALL command:

 
      PAW > call newnt.f

 /NTUPLE/LIST
 

List all Ntuples in the Current Directory. Note that the command HISTO/LIST lists all histograms and Ntuples in the
Current Directory.

 /NTUPLE/PRINT idn
 

 IDN
      C
        Ntuple Identifier
 

Print a summary about Ntuple IDN. Number of entries, variables names and limits are listed.

 /NTUPLE/HMERGE outfile infiles
 

 OUTFILE
         C
           Output file name D=' '
 INFILES
         C
           Input file names D=' ' Vararg
 

Merge HBOOK files containing histograms and/or ntuples. Ntuples are merged and histograms with the same ID are added.
The INFILES are merged into a new file OUTFILE. If OUTFILE already exists, it is overwritten.

If there are histograms in PAW memory that have same identifiers as histograms in one of the files to be merged, then the
contents of the histograms in memory are added to those of the histograms in the file. This can be avoided by deleting the
memory histogram (using H/DEL) before issuing the HMERGE command.

By default HMERGE uses the automatic record length determination to open the input files. This works for files with a
record length smaller or equal to 8191 words. For files with a larger record length the following syntax can be use.

 
     PAW > hmerge LRECL 16384                   | New LRECL
      Next HMERGE will use LRECL = 16384
     PAW > hmerge out.hbook in1.hbook in2.hbook | Use the new LRECL

To go back to the automatic record length determination mode just do:

 
     PAW > hmerge LRECL 0
      Next HMERGE will use the auto-record length detection

All the input files should have the same record length.

 /NTUPLE/DUPLICATE id1 id2 [ newbuf title option ]
 

 ID1
         C
           Source Ntuple
 ID2
         I
           New Ntuple
 NEWBUF
         I
           Buffer size D=-1
 TITLE
         C
           Title of ID2 D=' '
 OPTION
         C
           Options D='A'
 

OPTION:

 '' ''
 'A'
       Set the Addresses of variables in common /PAWCR4,etc/.
 'M'
       Create ID2 as a Memory resident Ntuple.
 '' ''
       Copy ID1 structure in ID2. Reset addresses of variables.
 

The structure of Ntuple ID1 is duplicated in a new ntuple ID2. This command is useful when one wants to create an ntuple
with the same variables but only a subset of the events. NEWBUF is the buffer size for ID2. If NEWBUF<0 the buffer size of
ID1 is taken. If NEWBUF=0 the current buffer size is taken (10000 words for RWNs). NEWBUF>0 will be the new buffer
size. If TITLE=' ' ID2 has the same title as ID1. In case of a disk-resident ntuple (default), ID2 is created into the current
working directory which must be open in WRITE mode.

Example with a Row Wise Ntuple:

 
       Macro DUPRWN
       Close 0
       Hi/File 1 source.hbook
       Hi/File 2 new.hbook ! N
       Nt/Dup //lun1/30 2
       *
       Application Comis Quit
             Real Function Dup(dum)
             Include ?
             If (X.gt.0..Or.Y.gt.0.) call hfn(2,X)
             dup=1.
             end
       Quit
       *
       nt/loop //lun1/30 dup
       hrout 2

Note that the statement 'include ?' allows to create automatically the inlude file (comis.inc) corresponding to the ntuple
structure. The command UWFUNC is not required in this case.

Example with a Column Wise Ntuple:

 
       Macro DUPCWN
       *
       Close 0                    | Close all the currently opened file
       H/file 1 source.hbook
       Uwfunc //lun1/1 source.inc | generate source.inc
       H/file 2 new.hbook ! N     | Create a new hbook file
       Nt/Dup //lun1/1 2          | Duplicate the ntuple 1 in the ntuple 2
       *
       * Comis routine which Loop on all events of Id1 and select some events
       * to be written in the new ntuple Id2.
       *
       Application COMIS quit
             Subroutine ntdup(Id1,Id2)
             Include 'source.inc'
             Call Hnoent(Id1,Noent)
             Do Ievent=1,Noent
                Call Hgnt(Id1,Ievent,Ierr)
                If (Ierr.ne.0) Goto 20
                If (X.Gt.0..Or.Y.Gt.0.) Then
                   Call Hfnt(Id2)
                Endif
             Enddo
         20  Continue
       *
             End
       Quit
       *
       Call Ntdup(1,2)             | Execute the routine Ntdup
       Hrout 2                     | Write Id2 on disk

 /NTUPLE/RECOVER idn
 

 IDN
      I
        Ntuple Identifier
 

To recover Ntuple ID. If the job producing the Ntuple crashed or the header was not stored correctly in the file with HROUT,
RECOVER will scan the Ntuple to rebuild the header table and recompute the number of entries. The file on which the
Ntuple resides must be open in Update mode.

 /NTUPLE/SCAN idn [ uwfunc nevent ifirst option varlis ]
 

 IDN
         C
           Ntuple Identifier
 UWFUNC
         C
           User cut function D='1.'
 NEVENT
         I
           Number of events D=99999999
 IFIRST
         I
           First event D=1
 OPTION
         C
           Options D=' '
 VARLIS
         C
           Names of the NVARS variables to scan D=' ' Vararg
 

OPTION:

 '' ''
 '' ''
       Alphanumeric output of the Ntuple.
 'S'
       Graphical scan (spider plot).
 'S2'
       Graphical scan (segments plot).
 'A'
       Used with 'S' it displays the average spider.
 

Scan the entries of an Ntuple subject to user cuts. Scan the variables for NEVENT events starting at IFIRST, requiring that
the events satisfy cut UWFUNC. In the case of Alphanumeric output Up to 10 variables may be scanned, the default is to
scan the first 10 variables.

When the option S (Spider plot) is specified, each event is presented in a graphical form (R versus PHI plot) to give a multi
dimensional view of the event. Each variable is represented on a separate axis with a scale ranging from the minimum to the
maximum value of the variable. A line joins all the current points on every axis where each point corresponds to the current
value of the variable. When the HCOL parameter is specified (eg SET HCOL 1002) a fill area is drawn. When the additional
option A is specified, a spider plot of the average value for each variable is also drawn. When the option S2 (Segment plot) is
specified, wedges are drawn along each axis instead of the line joining the points.

NB : a minimum of three variables in VARLIS is required for any graphical plot.

VARLIS may contain a list of the original variables, expressions of the original variables or/and ranges of variables. A range
can be given in the following form:

 
    :          means all variables (default).
    var1:var2  means from variable var1 to variable var2 included.
    var1:      means from variable var1 to the last.
    :var2      means from variable 1 to variable var2

For example, if IDN=30 has the 3 variables X,Y,Z,U,V,W one can do:

 
    PAW > scan 30
    PAW > scan 30 option=s
          each event is drawn as a spider plot.
    PAW > scan 30 option=sa
          each event is drawn as a spider plot and the average spider
          plot is also drawn.
    PAW > set 2BUF 1
    PAW > scan 30 option=s2
    More...? ( <CR>/N/G ) G
          answering 'G' with double buffer on, create a graphical
          animation of the ntuple content.
    PAW > scan 30 option=s  X:Z W
    PAW > scan 30 varlis=X:Z W
    PAW > scan 30 z>10
    PAW > scan 30 z>10 ! ! ! z abs(x) y+z x func.for
          where func.for is a COMIS function returning an expression
          of the original variables. This function func.for may be
          generated automatically by the PAW command:
    PAW > uwfunc 30 func.for

Note that IFIRST and NEVENT parameters are not meaningful in case of CHAINs.

 /NTUPLE/LOOP idn uwfunc [ nevent ifirst ]
 

 IDN
         C
           Identifier of Ntuple
 UWFUNC
         C
           Selection function or cut identifier D='1.'
 NEVENT
         I
           Number of events D=99999999
 IFIRST
         I
           First event D=1
 

Invoke the selection function UWFUNC for each event starting at event IFIRST. In UWFUNC, the user can fill one or
several histograms previously booked. The loop will be terminated if UWFUNC returns a negative value. For more
information about UWFUNC, see command NTUPLE/PLOT.

The ntuple identifier IDN, is an integer in this command. It make no sense to have an expression like 10.x.

Note that IFIRST and NEVENT parameters are not meaningful in case of CHAINs.

 /NTUPLE/GCUT cid idn [ uwfunc nevent ifirst nupd option idh wkid ]
 

 CID
         C
           Cut Identifier
 IDN
         C
           Ntuple Identifier
 UWFUNC
         C
           Selection function D='1.'
 NEVENT
         I
           Number of events D=99999999
 IFIRST
         I
           First event D=1
 NUPD
         I
           Frequency to update histogram D=100000000
 OPTION
         C
           Options D=' '
 IDH
         I
           Identifier of histogram to fill D=1000000
 WKID
         I
           Workstation identifier D=1
 

OPTION:

 '' ''
 'C'
        Draw a smooth curve.
 'S'
        Superimpose plot on top of existing picture.
 '+'
        Add contents of IDN to last plotted ntuple.
 'B'
        Bar chart format.
 'L'
        Connect channels contents by a line.
 'P'
        Draw the current polymarker at each channel or cell.
 '*'
        Draw a * at each channel.
 'U'
        Update channels modified since last call.
 'E'
        Compute (HBARX) and draw error bars with current marker.
 'A'
        Axis labels and tick marks are not drawn.
 '' ''
        Draw the ntuple as an histogram.
 'PROF'
        Fill a Profile histogram (mean option).
 'PROFS'
        Fill a Profile histogram (spread option).
 'PROFI'
        Fill a Profile histogram (integer spread option).
 

Define a graphical cut on a one or two dimensional plot. First Project and plot an Ntuple as a (1-Dim or 2-Dim) histogram
with automatic binning (ID=1000000), possibly using a selection algorithm. See NTUPLE/PLOT for full details on what
expressions can be plotted and which options can be given. Then the graphical cut is defined using the mouse.

 /NTUPLE/PROJECT idh idn [ uwfunc nevent ifirst ]
 

 IDH
         C
           Identifier of histogram to fill
 IDN
         C
           Identifier of Ntuple
 UWFUNC
         C
           Selection function or cut identifier D='1.'
 NEVENT
         I
           Number of events D=99999999
 IFIRST
         I
           First event D=1
 

Project an Ntuple onto a 1-Dim or 2-Dim histogram, possibly using a selection function or predefined cuts. IDN may be
given as IDN or IDN.X , IDN.Y%X (Y%X means variable Y of Ntuple IDN versus variable X). For more information about
UWFUNC, see command NTUPLE/PLOT. The histogram IDH is not reset before filling. This allows several PROJECTs
from different Ntuples.

Note that IFIRST and NEVENT parameters are not meaningful in case of CHAINs.

 /NTUPLE/READ idn fname [ format opt nevent match ]
 

 IDN
         C
           Ntuple Identifier
 FNAME
         C
           File name
 FORMAT
         C
           Format D='*'
 OPT
         C
           Options D=' '
 NEVENT
         I
           Number of events D=1000000
 MATCH
         C
           Matching pattern D=' '
 

Read Ntuple values from the alphanumeric file FNAME with the format specifications in FORMAT.

This command works for row wise Ntuple only.

Before executing this command, the Ntuple IDN must have been created with the command Ntuple/Create.

MATCH is used to specify a pattern string, restricting the Ntuple filling only to the records in the file which verify the
pattern. The possible patterns are:

 
     /string/      match a string (starting in column 1)
    -/string/      do not match a string (starting in column 1)
     /string/(n)   match a string, starting in column n
     /string/(*)   match a string, starting at any column

Example:

 
       H/del *
       Appl Data ntmatch.dat
        101. 201. 301.   C
        102. 202. 302.
        103. 203. 303.   C
        104. 204. 304.   C
        105. 205. 305.
        106. 206. 306.
        107. 207. 307.
        108. 208. 308.
        109. 209. 309.
       ntmatch.dat
       Nt/Create 4 'Test of Match' 3 ! ! Xmatch Ymatch Zmatch
       Nt/Read 4 ntmatch.dat ! ! ! -/C/(*)
       Nt/SCAN 4

In this macro all the lines with a C at the end are not read.

 /NTUPLE/PLOT idn [ uwfunc nevent ifirst nupd option idh ]
 

 IDN
         C
           Ntuple Identifier
 UWFUNC
         C
           Selection function D='1.'
 NEVENT
         I
           Number of events D=99999999
 IFIRST
         I
           First event D=1
 NUPD
         I
           Frequency to update histogram D=100000000
 OPTION
         C
           Options D=' '
 IDH
         I
           Identifier of histogram to fill D=1000000
 

OPTION:

 '' ''
 'C'
        Draw a smooth curve (1D plots).
 'S'
        Superimpose plot on top of existing picture.
 '+'
        Add contents of IDN to last plotted ntuple (1D plots).
 'B'
        Bar chart format (1D plots).
 'L'
        Connect channels contents by a line (1D, 2D and 3D plots).
 'P'
        Draw the current polymarker at each channel or cell (1D plots).
 '*'
        Draw a * at each channel (1D plots).
 'U'
        Update channels modified since last call (1D plots).
 'E'
        Compute (HBARX) and draw error bars with current marker.
 'A'
        Axis labels and tick marks are not drawn.
 '' ''
        Draw the ntuple as an histogram.
 'N'
        Don't draw anything, but fill the 1D or 2D histogram IDH
 'G'
        Draw a gouraud shaded surface (3D plots).
 'PROF'
        Fill a Profile histogram (mean option).
 'PROFS'
        Fill a Profile histogram (spread option).
 'PROFI'
        Fill a Profile histogram (integer spread option).
 

Project and plot an Ntuple as a (1-Dim or 2-Dim) histogram with automatic binning (ID=1000000), possibly using a
selection algorithm. See parameter CHOPT in command HISTO/PLOT to have more details on the possible OPTION. IDN
may be given as:

 
             IDN.X
             IDN.Y%X
             IDN.Y%X%Z
             IDN.Y%X%Z%T
             IDN.expression1
             IDN.expression1%expression2
             IDN.expression1%expression2%expression3
             IDN.expression1%expression2%expression3%expression4

Y%X means a scatter-plot Y(I) versus X(I) where I is the event number. In this example, X and Y are the names of the
variables 1 and 2 respectively.

expression1 is any numerical expression of the Ntuple variables. It may include a call to a COMIS function.

Y%X%Z means a 3D scatter-plot Z(I) versus Y(I) versus X(I) where I is the event number. If option "G" is given, three
Gouraud shaded surfaces are drawn. The green one is the average.

Y%X%Z%T means a 3D scatter-plot Z(I) versus Y(I) versus X(I) where I is the event number. T is mapped on the color
map.

UWFUNC may have the following forms:

 
    1- UWFUNC='0' or missing (only IDN given). No selection is applied.
    2- UWFUNC is a CUT or combination of valid CUTS created by the
       command NTUPLE/CUTS. Ex:
              UWFUNC=$1            means use cut $1
              UWFUNC=$1.AND.$2
              UWFUNC=.NOT.($1.AND.$2)
              UWFUNC=($1.OR.$2).AND.$3
    3- UWFUNC is a FORTRAN expression
       Ex:    X>3.14.AND.(Y<Z+3.15)
    4- UWFUNC is a variable name or an arithmetic expression
       Ex:   NT/PLOT 30.X Y  weight of each event is variable Y
             NT/PLOT 30.X X**2+Y**2
    5- UWFUNC is the name of a selection function in a text file with
       the name UWFUNC.F, UWFUNC.FTN, UWFUNC.FOR, UWFUNC FORTRAN
       (Unix, Apollo, VAX, IBM).

The command UWFUNC may be used to generate automatically this function. For example if IDN=30 is an Ntuple with 3
variables per event and 10000 events, then

 
      NTUPLE/PLOT 30.X select.f

will process the 10000 events of the Ntuple IDN=30. For each event, the function SELECT is called. It returns the weight of
the event. Example:

 
       FUNCTION SELECT(X)
       DIMENSION X(3)
       IF(X(1)**1+X(2)**2.LT.1.5)THEN
          SELECT=0.
       ELSE
          SELECT=1.
       ENDIF
       END

The file select.f can be edited from PAW using the command EDIT. Note that if the suffix (.F, .FTN, .FORTRAN or .FOR)
is omitted, then COMIS will start from the precompiled version in memory and not from the file. Results of a selection can be
saved in a MASK (See NTUPLE/MASK). Example:

 
      NT/PLOT 30.X Z<0.4>>MNAME(4)

means mark bit 4 in mask MNAME for all events satisfying the condition Z<0.4

A MASK may also be given as input to a selection expression. Example:

 
      NT/PLOT 30.X MNAME(4).and.Z<0.4

means all events satisfying bit 4 of MNAME AND Z<0.4

It is possible to plot expressions of the original variables. Examples:

 
      NT/PLOT 30.SIN(X)%SQRT(Y**2+Z**2)  Z<0.4

plots a scatter-plot of variable U versus V for all events satisfying the condition Z<0.4. U and V are defined as being
U=SIN(X) and V=SQRT(X**2+Y**2).

 
      NT/PLOT 30.func.f(X)%(SIN(Y)+3.)  Z<0.2.and.TEST.FTN>6

plots a scatter-plot of variable U versus V for all events satisfying the condition (Z<0.2 and the result of the COMIS function
test.f >6). U and V are defined as being U=(Result of the COMIS function func.f), V=(SIN(Y)+3.)

The default identifier of the histogram being filled is IDH=1000000. At the next invocation of this command, it will be
overwritten.

If either NEVENT or IFIRST or NUPD are negative, then the identifier of the histogram being filled will be taken as
IDH=-NEVENT or IDH=-IFIRST or IDH=-NUPD. This facility is kept for backward compatibility but it is stongly
recommended to use the parameter IDH instead.

IDH may have been created with H/CREATE. Before filling IDH, the contents of IDH are reset if IDH already exists. Use
NTUPLE/PROJECT to cumulate several passes into IDH. By default IDH value is 1000000. This means that the histogram
binning will be computed automatically. In particular the minimal and maximal value of the histogramed quantity has to be
computed which implies to do an extra pass on the ntuple data. IDH not equal to 1000000 is a convenient way to force user
binning.

Every NUPD events, the current status of the histogram is displayed.

Note that IFIRST and NEVENT parameters are meaningless in case of CHAINs.

 /NTUPLE/CHAIN [ cname entry ]
 

 CNAME
        C
          Chain Name D=' '
 ENTRY
        C
          Chain Member(s) | -P Path D=' ' Vararg
 

Using the chain command one can build logical Ntuples of unlimited size. The chain command creates an Ntuple chain
CNAME and add member(s) ENTRY. If the chain already exists the member is simply added. More than one member may
be specified at a time. A chain can contain three different type of members: files, logical units and other chains. The member
type is deduced from the format of the member. Entries containing the characters . / : ; $ are considered to be files, entries like
//LUN4 are assumed to be logical units and all other type of entries are chains. Chain names must be unique. After a chain
has been defined it can be traversed, by all Ntuple commands (NT/PLOT, NT/PROJ, NT/LOOP), by changing the current
working directory to the chain: CD //CNAME. A member may be deleted from a chain by preceding it by a - sign. A
complete chain can be deleted by preceding the chain name by a -. All chains can be deleted by giving a - as chain name. Not
specifying any parameters results in the listing of all defined chains. A chain tree will be printed by appending a > character
to the chain name. The path of all chain members, from chain CNAME downwards, can be changed by specifying a chain
path. This is done by giving a chain name followed by the -P option and a path specification. The chain path will be
pre-pended to the member names. Chains down the tree can override a path specified higher up in the tree.

Examples of chain (Ntuple tree) definition:

 
    CHAIN   Year93  Jan Feb March April May ...
    CHAIN   Jan     Week1 Week2 Week3 Week4
    CHAIN   Week1   file1.hbook file2.hbook ...
    CHAIN   Week2   file3.hbook file4.hbook ...

 
    CD //Jan
    NT/PLOT 10.e     ; loop over all files in chains Week1, Week2, Week3, ...
    CD //Year93      ; loop over all files in chains Jan, Feb, March, ...
    CHAIN Year93 -P /user/delphi   ; all files from chain Year93 downward will
                                     be changed to /user/delphi/file1.hbook,
   ...

 
    CHAIN Year93>    ; print the chain tree Year93
    CHAIN -Feb       ; delete chain Feb
    CHAIN Jan -file3.hbook   ; delete file3.hbook from chain Jan

Note that IFIRST and NEVENT parameters are not meaningful in case of CHAINs.

 /NTUPLE/CUTS cutid [ option fname wkid ]
 

 CUTID
        C
          Cut identifier
 OPTION
        C
          Options D='P' Minus
 FNAME
        C
          File name D=' '
 WKID
        I
          Workstation identifier D=1
 

OPTION:

 'P'
       Print definition of cut CUTID.
 '-'
       Reset cut CUTID.
 'R'
       Read definition of cut CUTID from file FNAME.
 'W'
       Write definition of cut CUTID on file FNAME (text file).
 'D'
       Draw cut contour.
 

Define the CUTID with the format $nn. nn is an integer between 1 and 99. This cut can then be used in subsequent
commands NTUPLE/PLOT, PROJECT.

 
    OPTION='expression'

allows to define the cut CUTID. For example the command:

 
    PAW > CUTS $1 X<0.8.and.Y<SQRT(X)

defines the cut $1. Note that CUTID=$0 means all cuts.

 /NTUPLE/CSELECT [ chopt csize ]
 

 CHOPT
        C
          Options D='N'
 CSIZE
        R
          Comment size D=0.28
 

CHOPT:

 '' ''
       Comment is left adjusted to the current zone
 'R'
       Comment is right adjusted to the current zone
 'C'
       Comment is centered to the current zone
 'B'
       Comment is drawn below the top zone line
 'N'
       All subsequent NTUPLE/PLOT commands will print the selection mechanism with the options specified in
       CHOPT.
 

To write selection mechanism as a comment on the picture. By default, the comment is drawn left justified above the top
zone line. Example:

 
    CSEL          All coming NT/PLOT commands will draw a comment
                  of size CSIZE=0.28cm Left justified.
    CSEL NRB 0.4  All coming NT/PLOT commands will draw a comment
                  of size 0.4 cm Right justified Below the top line.
    CSEL  CB      Draw previous selection mechanism Centered Below
                  the top zone line.

The Global title font (SET GFON) with precision 1 is used to draw the text.

 /NTUPLE/UWFUNC idn fname [ chopt ]
 

 IDN
        C
          Ntuple Identifier
 FNAME
        C
          File name
 CHOPT
        C
          Options D=' '
 

CHOPT:

 '' ''
       Generate the FORTRAN skeleton of a selection function.
 'E'
       Present the selection function in the local editor.
 'P'
       Code to print events is generated (Row Wise Ntuples only).
 'T'
       Names of the Ntuple variables are generated in DATA statements (Row Wise Ntuples only).
 

To generate the FORTRAN skeleton of a selection function or the INCLUDE file with the columns declaration.

A FORTRAN function is generated if the FNAME is of the form, xxx.f, xxx.for, xxx.fortran. Otherwise an INCLUDE file is
generated. Example: If the Row Wise Ntuple ID=30 has variable names [X,Y,Z] then:

 
      NTUPLE/UWFUNC 30 SELECT.FOR

will generate the file SELECT.FOR with:

 
            REAL FUNCTION SELECT()
            REAL
           +X       ,Y       ,Z
      *
            LOGICAL         CHAIN
            CHARACTER*128   CFILE
      *
            COMMON /PAWCHN/ CHAIN, NCHEVT, ICHEVT
            COMMON /PAWCHC/ CFILE
      *
            COMMON/PAWIDN/IDNEVT,OBS(13),
           +X       ,Y       ,Z
      *
            SELECT=1.
            END

Then using the command EDIT one can modify this file which could then look something like (IDNEVT is the event
number):

 
            REAL FUNCTION SELECT()
            REAL
           +X       ,Y       ,Z
      *
            LOGICAL         CHAIN
            CHARACTER*128   CFILE
      *
            COMMON /PAWCHN/ CHAIN, NCHEVT, ICHEVT
            COMMON /PAWCHC/ CFILE
      *
            COMMON/PAWIDN/IDNEVT,OBS(13),
           +X       ,Y       ,Z
      *
            IF(X**2+Y**2.GT.Z**2)THEN
               SELECT=1.
            ELSE
               SELECT=0.
            ENDIF
            END

 
      NTUPLE/UWFUNC 30 SELECT.INC

will generate an include file. This include file may be referenced in a selection function in the following way:

 
            FUNCTION SELECT()
            include 'select.inc'
      *
            SELECT=1.
            IF(X.LE.Y)SELECT=0.
            END

Note that the command UWFUNC is not required if the SELECT function has the following form:

 
            FUNCTION SELECT()
            include ?
      *
            SELECT=1.
            IF(X.LE.Y)SELECT=0.
            END

In this case (thanks to the statement 'include ?') the include file will be generated automatically with the name 'comis.inc'.

It is possible to add input parameters to the SELECT function and to use them in the function's body.

 /NTUPLE/LINTRA idn [ chopt nevent ifirst nvars varlis ]
 

 IDN
         C
           Ntuple Identifier
 CHOPT
         C
           Options D=' '
 NEVENT
         I
           Number of events D=99999999
 IFIRST
         I
           First event D=1
 NVARS
         I
           Number of the most significant variables D=20 R=0:20
 VARLIS
         C
           Names of the NVARS most significant variables
 

CHOPT:

 'N'
       The variables are normalized. This option is useful in the case the ranges of variables are very different
 'P'
       Print more results about the analysis
 

Data reduction on Ntuple. The method used is the PRINCIPAL COMPONENTS ANALYSIS. The Principal Components
Analysis method consists in applying a linear transformation to the original variables of a ntuple. This transformation is
described by an orthogonal matrix and is equivalent to a rotation of the original space to a new set of coordinates vectors,
which hopefully provide easier identification and dimensionality reduction. This matrix is real positive definite and symmetric
and has all its eigenvalues greater than zero. Among the family of all complete orthonormal bases, the basis formed by the
eigenvectors of the covariance matrix and belonging to the largest eigenvalues corresponds to the most significant features for
the description of the original ntuple.

Reduction of the variables for NEVENT events starting at IFIRST The default is to take all the 20 first variables.

This command creates a file: xtoxsi.f, XTOXSI.FORTRAN, xtoxsi.for or xtoxsi.ftn. This file contains a Fortran function
which computes the new variables. These new variables can be visualized in PAW with for example:

 
    PAW > Ntuple/plot id.xtoxsi.ftn(1)
    PAW > Ntuple/plot id.xtoxsi.ftn(1)%xtoxsi.ftn(3)

 /NTUPLE/VMEM [ mxsize ]
 

 MXSIZE
        I
          Maximum size of dynamic memory buffer in MBytes D=-1 R=-2:128
 

Change or show the size of the dynamic memory buffer used to store Ntuple columns during Ntuple analysis. The default is
10 MB. Giving a value of 0 turns the buffer facility off. The upper limit is 128 MB, but be sure you have enough swap space
and realize that when the buffer is swapped to disk you loose part of the benefit of the buffer facility (which is to reduce the
number of disk accesses). Omitting the argument or specifying -1 will show you the current upper limit and used and free
space. Giving -2 shows which columns are currently stored in memory.

 /NTUPLE/DUMP idn [ uwfunc nevent ifirst filename sep1 sep2 ]
 

 IDN
           C
             Ntuple Identifier
 UWFUNC
           C
             Selection function D='1.'
 NEVENT
           I
             Number of events D=99999999
 IFIRST
           I
             First event D=1
 FILENAME
           C
             Output filename D=' '
 SEP1
           C
             Value separator D=','
 SEP2
           C
             Expression separator (on output) D='%'
 

For the selected events the values of the expressions are printed to the screen (by default) or to a specified file. If the
expression is non scalar (e.g. vector) the elements of the vector are sepatated by a ',' (changed with SEP1). The values of the
expressions are separated by a '%' (changed with SEP2). The output of the DUMP command is meant for consumption by
other computer programs, for easy inspection of an ntuple the NTUPLE/SCAN command might be more suitable.

 /NTUPLE/FLAGS_QP [ option value ]
 

 OPTION
        C
          Option name
 VALUE
        I
          Option value
 

Set debug options for the Query Processor

=================================================================

/NTUPLE_MASK


 /NTUPLE/MASK/FILE fname [ chopt ]
 

 FNAME
        C
          File name
 CHOPT
        C
          Options D='R'
 

CHOPT:

 'R'
       Existing file is opened (read mode only).
 'N'
       A new file is opened.
 'U'
       Existing file is opened to be modified.
 

Open a MASK file.

 /NTUPLE/MASK/CLOSE mname
 

 MNAME
         C
          Mask name
 

Close a MASK file.

 /NTUPLE/MASK/LIST [ mname ]
 

 MNAME
         C
          Mask name D='*'
 

List the MASK files currently open.

 /NTUPLE/MASK/RESET mname ibit
 

 MNAME
         C
          Mask name
 IBIT
         I
          Number of bit to reset D=1 R=1:32
 

Reset on bit in a mask file.