Ntuple creation and related operations.
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:
1000 format(e15.7,2x,a,7x,a,7x,a)
and then call this routine via the CALL command:
List all Ntuples in the Current Directory. Note that the command HISTO/LIST lists all histograms and Ntuples in the Current Directory.
Print a summary about Ntuple IDN. Number of entries, variables names and limits are listed.
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.
Note that if there is a histogram in PAW memory that has the same identifier as a histogram in one of the files to be merged, then the contents of the histogram in memory are added to those of the histogram in the file. This can be avoided by deleting the memory histogram (using H/DEL) before issuing the HMERGE command.
OPTION:
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:
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:
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.
OPTION:
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:
For example, if IDN=30 has the 3 variables X,Y,Z,U,V,W one can do:
Note that IFIRST and NEVENT parameters are not meaningful in case of CHAINs.
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.
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.
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.
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:
Example:
In this macro all the lines with a C at the end are not read.
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.
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. Expression 1 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 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.
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
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:
The file SELECT.FOR (VAX), SELECT.FTN (Apollo) or SELECT FORTRAN (IBM) can be edited from PAW using the command EDIT. Note that if the suffix (.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).
A MASK may also be given as input to a selection expression.
It is possible to plot expressions of the original variables.
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. 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. Note that 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.
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.
Note that IFIRST and NEVENT parameters are not meaningful in case of CHAINs.
OPTION:
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.
Note that CUTID=$0 means all cuts.
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:
The Global title font (SET GFON) with precision 1 is used to draw the text.
CHOPT:
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 Ntuple ID=30 has variable names [X,Y,Z,ETOT,EMISS,etc] then:
NTUPLE/UWFUNC 30 SELECT.FOR will generate the file SELECT.FOR with:
Then using the command EDIT one can modify this file which could then look something like (IDNEVT is the event number):
If in a subsequent command NTUPLE/PLOT, the selection function SELECT is used, then:
NTUPLE/UWFUNC 30 SELECT.INC will generate an include file. This include file may be referenced in a selection function in the following way:
Note that the command UWFUNC is not required if the SELECT function has the following form:
In this case (thanks to the statement 'include ?') the include file will be generated automatically with the name 'comis.inc'.
CHOPT:
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.FORTRAN or xtoxsi.for,xtoxsi.ftn. This file contains a Fortran function which computes the new variables. These new variables can be visualized in PAW with for example:
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.
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.
Set debug options for the Query Processor