/HISTOGRAM_OPERATIONS

Histogram operations and comparisons.

/HISTOGRAM/OPERATIONS/ADD id1 id2 id3 [ c1 c2 option ]

ID1
        C
          First histogram Identifier
ID2
        C
          Second histogram Identifier
ID3
        C
          Result histogram Identifier
C1
        R
          Scale factor for ID1 D=1.
C2
        R
          Scale factor for ID2 D=1.
OPTION
        C
          Option D=' '

OPTION:

'' ''
'E'

Add histograms: ID3 = C1*ID1 + C2*ID2. Applicable to 1-Dim and 2-Dim histograms. See command HRIN to add
histograms with same IDS from different files. If option 'E' is set, error bars are calculated for ID3.

/HISTOGRAM/OPERATIONS/SUBTRACT id1 id2 id3 [ c1 c2 option ]

OPTION:

'' ''
'E'

Subtract histograms: ID3 = C1*ID1 - C2*ID2. Applicable to 1-Dim and 2-Dim histograms. If option 'E' is set, error bars
are calculated for ID3.

/HISTOGRAM/OPERATIONS/MULTIPLY id1 id2 id3 [ c1 c2 option ]

OPTION:

'' ''
'E'

Multiply histogram contents: ID3 = C1*ID1 * C2*ID2. Applicable to 1-Dim and 2-Dim histograms. If option 'E' is set, error
bars are calculated for ID3.

/HISTOGRAM/OPERATIONS/DIVIDE id1 id2 id3 [ c1 c2 option ]

OPTION:

'' ''
'E'

Divide histograms: ID3 = C1*ID1 / C2*ID2. Applicable to 1-Dim and 2-Dim histograms. If option 'E' is set, error bars are
calculated for ID3.

/HISTOGRAM/OPERATIONS/RESET id [ title ]

ID
       C
         Histogram Identifier Loop
TITLE
       C
         New title D=' '

Reset contents and errors of an histogram. Bin definition is not modified.

/HISTOGRAM/OPERATIONS/DIFF id1 id2 [ chopt ]

ID1
        C
          First Histogram Identifier
ID2
        C
          Second Histogram Identifier
CHOPT
        C
          Options D='D'

CHOPT:

'' ''
       The comparison is done only on the shape of the two histograms.
'N'
       Include also comparison of the relative normalisation of the two histograms, in addition to comparing the shapes.
       PROB is then a combined confidence level taking account of absolute contents.
'D'
       Debug printout, produces a blank line and two lines of information at each call, including the ID numbers, the
       number of events in each histogram, the PROB value, and the maximum Kolmogorov distance between the two
       histograms. For 2-Dim histograms, there are two Kolmogorov distances (see below). If 'N' is specified, there is a
       third line of output giving the PROB for shape alone, and for normalisation.
'O'
       Overflow, requests that overflow bins be taken into account.
'U'
       Underflow, requests that underflow bins be taken into account.
'L'
       Left: include x-underflows
'R'
       Right: include x-overflows
'T'
       Top: include y-overflows
'B'
       Bottom: include y-underflows
'F1'
       Histogram 1 has no error (is a function)
'F2'
       Histogram 2 has no error (is a function)

Test of compatibility for two 1-Dim histograms ID1 and ID2. A probability PROB is calculated as a number between zero
and one, where PROB near one indicates very similar histograms, and PROB near zero means that it is very unlikely that the
two arose from the same parent distribution. For two histograms sampled randomly from the same distribution, PROB will
be (approximately) uniformly distributed between 0 and 1. See discussion in HBOOK manual under 'HDIFF- Statistical
Considerations'. By default (if no options are selected with CHOPT) the comparison is done only on the shape of the two
histograms, without consideration of the difference in numbers of events, and ignoring all underflow and overflow bins.

/HISTOGRAM/OPERATIONS/SORT id [ chopt ]

ID
        C
          Histogram Identifier Loop
CHOPT
        C
          Options D='XA'

CHOPT:

'X'
       X-axis is being treated.
'Y'
       Y-axis is being treated.
'Z'
       Z-axis is being treated.
'A'
       Alphabetically.
'E'
       Reverse alphabetical order.
'D'
       By increasing channel contents.
'V'
       By decreasing channel contents.

Sort the alphanumeric labels of the histogram ID according to the value of CHOPT.

/HISTOGRAM/OPERATIONS/SMOOTH id [ option sensit smooth ]

ID
         C
           Histogram or Ntuple Identifier Minus
OPTION
         C
           Options D='2M'
SENSIT
         R
           Sensitivity parameter D=1. R=0.3:3.
SMOOTH
         R
           Smoothness parameter D=1. R=0.3:3.

OPTION:

'0'
       Replace original histogram by smoothed.
'1'
       Replace original histogram by smoothed.
'2'
       Store values of smoothed function and its parameters without replacing the original histogram (but see note below)
       - the smoothed function can be displayed at editing time - see HISTOGRAM/PLOT.
'M'
       Invoke multiquadric smoothing (see HBOOK routine HQUAD).
'Q'
       Invoke the 353QH algorithm (see HBOOK routine HSMOOF).
'S'
       Invoke spline smoothing.
'V'
       Verbose (default for all except 1-D histogram).
'N'
       Do not plot the result of the fit.
'F'
       Write Fortran77 function to HQUADF.DAT (multiquadric only)

Smooth a histogram or 'simple' ntuple. ('simple' = 1, 2, or 3 variables.)

For multiquadric smoothing, SENSIT controls the sensitivity to statistical fluctuations. SMOOTH controls the (radius of)
curvature of the multiquadric basis functions.

Notes:

1) The multiquadric basis functions are SQRT(R**2+D**2), where R is the distance from the 'centre', and D is a scale
parameter and also the curvature at the 'centre'. 'Centres' are located at points where the 2nd differential or Laplacian of
event density is statistically significant.

2) The data must be statistically independent, i.e. events (weighted or unweighted) drawn randomly from a parent probability
distribution or differential cross-section.

For spline smoothing, SENSIT and SMOOTH control the no. of knots (= 10 * SENSIT) and degree of splines (= SMOOTH
+ 2) (thus if SENSIT and SMOOTH are at their default values a 10-knot cubic spline is used).

Notes:

1) The spline option ALWAYS replaces the contents of a 2-D histogram. (Also chi-squared is unavailable in this case.)

2) Use the SPLINE command for more flexibility.

/HISTOGRAM/OPERATIONS/SPLINE id [ isel knotx kx ]

ID
        C
          Histogram Identifier
ISEL
        I
          Option flag D=2
KNOTX
        I
          Number of knots D=10
KX
        I
          Degree of the spline D=3

Smooth 1-Dim or 2-Dim histogram ID using B-splines. If ID is a 1-Dim histogram then:

ISEL = 0,1 replace original histogram by smoothed.
= 2 superimpose as a function when editing.

If ID is a 2-Dim histogram then original contents are replaced.

/HISTOGRAM/OPERATIONS/FUNCTION id ufunc

ID
        C
          Histogram Identifier
UFUNC
        C
          Name of the function

Associate the function UFUNC with the histogram ID.

Example:

HIS/OP/FUN 110 X**2
H/PL 110

/HISTOGRAM/OPERATIONS/PARAM id [ isel r2min maxpow ]

ID
          C
            Histogram Identifier
ISEL
          I
            Control word D=11
R2MIN
          R
            Min correlation coefficient D=1.
MAXPOW
          I
            Max degree of polynomials D=5 R=1:20

Perform a regression on contents of the 1-Dim histogram ID. Find the best parameterisation in terms of elementary
functions (regressors). See HBOOK guide HPARAM. Control word ISEL=1000*T +100*W +10*S +P

    S = 1 resulting parametric fit superimposed on histogram
        0 no superposition
    P = 0 minimal output: the residual sum of squares is printed
        1 normal output: in addition, the problem characteristics and
          options are printed; also the standard deviations and
          confidence intervals of the coefficients.
        2 extensive output: the results of each iteration are printed
          with the normal output.
    W = 0 weights on histogram contents are already defined via HBARX
          or HPAKE. If not they are taken to be equal to the
          square-root of the contents.
        1 weights are equal to 1.
    T = 0 monomials will be selected as the elementary functions
        1 Chebyshev polynomials with a definition region: [-1,1]
        2 Legendre polynomials with a definition region: [-1,1]
        3 shifted Chebyshev polynomials with a definition region: [0,1]
        4 Laguerre polynomials with a definition region: [0,+infinite]
        5 Hermite polynomials with a definition region: [-inf,+inf]

The FORTRAN code of the parameterisation is written onto the file FPARAM.DAT.

/HISTOGRAM/OPERATIONS/HSETPR param value

PARAM
        C
          Parameter name D='FEPS'
VALUE
        R
          Parameter value D=0.001

Set various parameters for command PARAM.
================================================================================

/HISTOGRAM_HIO

Input/Output operations of histograms.

/HISTOGRAM/HIO/HRIN id [ icycle iofset ]

ID
        C
          Histogram Identifier Loop
ICYCLE
        I
          Cycle number D=999
IOFSET
        I
          Offset D=0

Read histogram/Ntuple ID from the current directory on direct access file to memory. An identical histogram is created but
with an ID equal to that of the original histogram plus the offset IOFSET. Identifier may be '0' or '*' (for all histograms). If
ICYCLE > 1000 and ID=0 read all histograms in all subdirectories as well. If IOFSET = 99999 then the contents of
histogram ID on the disk file are added to the current histogram in memory if it exists. For example to add all histograms
from FILE1 and FILE2 in memory, the sequence of commands can be:

    PAW > Histo/File 1 FILE1
    PAW > Hrin 0
    PAW > Histo/File 2 FILE2
    PAW > Hrin 0 ! 99999

/HISTOGRAM/HIO/HROUT id [ chopt ]

ID
        C
          Histogram Identifier Loop
CHOPT
        C
          Options D=' '

CHOPT:

'' ''
Write histo/Ntuple ID from memory to current directory.
'T'
Writes all histograms in subdirectories as well.

Write histo/Ntuple ID from memory to current directory. Identifier may be '0' or '*' (for all histograms).

/HISTOGRAM/HIO/HSCRATCH id

ID
C
Histogram Identifier Loop

Delete histogram ID in Current Directory on disk. If ID='0' or '*' delete all histograms. To delete histograms in memory use
command HISTO/DELETE.

/HISTOGRAM/HIO/HFETCH id fname

ID
        C
          Histogram Identifier
FNAME
        C
          File name

Fetch histogram ID from file FNAME. FNAME has been created by the old version of HBOOK3 (Unformatted).

/HISTOGRAM/HIO/HREAD id fname

ID
        C
          Histogram Identifier
FNAME
        C
          File name

Read histogram ID from file FNAME. FNAME has been created by the old version of HBOOK3 (Formatted).

/HISTOGRAM/HIO/PRINT id [ chopt ]

ID
        C
          Histogram Identifier Loop
CHOPT
        C
          Options D=' '

CHOPT:

'' ''
Print histograms.
'S'
Only statistics (Number of entries, mean, RMS, underflow, overflow) are printed.

Print histograms (line-printer format) on screen. The command OUTPUT_LP may be used to change the output file.

/HISTOGRAM/HIO/DUMP id

ID
C
Histogram Identifier Loop

Dump the histogram ZEBRA data structure on the terminal.

/HISTOGRAM/HIO/OUTPUT_LP [ lun fname ]

LUN
        I
          Logical unit number D=6
FNAME
        C
          File name D=' '

Change the HBOOK 'line printer' file name. If FNAME=' ' then OUTPUT is appended to an already opened file on unit
LUN. If LUN is negative, the file is closed and subsequent output is directed to unit 6.

/HISTOGRAM/HIO/GLOBAL_SECT gname

GNAME
C
Global section name D=' '

Map the global section GNAME. The current directory is changed to //GNAME. This command doesn't work on HPUX.

/HISTOGRAM/HIO/GRESET id

ID
C
Histogram Identifier

Reset histogram ID in the global section.
========================================================================

/HISTOGRAM_GET_VECT

Fill a vector from values stored in HBOOK objects.

/HISTOGRAM/GET_VECT/CONTENTS id vname

ID
        C
          Histogram Identifier
VNAME
        C
          Vector name

Get contents of histogram ID into vector VNAME.

/HISTOGRAM/GET_VECT/ERRORS id vname

ID
        C
          Histogram Identifier
VNAME
        C
          Vector name

Get errors of histogram ID into vector VNAME.

/HISTOGRAM/GET_VECT/FUNCTION id vname

ID
        C
          Histogram Identifier
VNAME
        C
          Vector name

Get function associated to histogram ID into vector VNAME.

/HISTOGRAM/GET_VECT/ABSCISSA id vname

ID
        C
          Histogram Identifier
VNAME
        C
          Vector name

Get values of center of bins abscissa into vector VNAME.

/HISTOGRAM/GET_VECT/REBIN id x y ex ey [ n ifirst ilast chopt ]

ID
        C
          Histogram Identifier
X
        C
          Name of vector X
Y
        C
          Name of vector Y
EX
        C
          Name of vector EX
EY
        C
          Name of vector EY
N
        I
          Number of elements to fill D=100
IFIRST
        I
          First bin D=1
ILAST
        I
          Last bin D=100
CHOPT
        C
          Option D=' '

CHOPT:

'N'
Do not normalize values in Y

The specified channels of the 1-Dim histogram ID are cumulated (rebinned) into new bins. The final contents of the new bin
is the average of the original bins by default. If the option N is given, the final contents of the new bin is the sum of the
original bins. Get contents and errors into vectors, grouping bins. Bin width and centers are also extracted. Allow to combine
2, 3 or more bins into one. Example:

PAW > REBIN 110 X Y EX EY 25 11 85

will group by 3 channels 11 to 85 and return new abscissa, contents and errors. Errors in X are equal to 1.5*BINWIDTH.

PAW > REBIN ID X Y EX EY

is a convenient way to return in one call abscissa, contents and errors for 1-Dim histogram. In this case the errors in X are
equal to 0.5*BINWIDTH.

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

/HISTOGRAM_PUT_VECT

Replace histogram contents with values in a vector.

/HISTOGRAM/PUT_VECT/CONTENTS id vname

ID
        C
          Histogram Identifier
VNAME
        C
          Vector name

Replace contents of histogram with values of vector VNAME.

/HISTOGRAM/PUT_VECT/ERRORS id vname

ID
        C
          Histogram Identifier
VNAME
        C
          Vector name

Replace errors of histogram with values of vector VNAME.
======================================================================

/HISTOGRAM_SET

Set histogram attributes.

/HISTOGRAM/SET/MAXIMUM id vmax

ID
       C
         Histogram Identifier Loop
VMAX
       R
         Maximum value

Set the maximum value on the Y axis. To select again an automatic scale, just set VMAX equal to the minimum. Example:

PAW > MIN id 0
PAW > MAX id 0

Reset the default scaling.

/HISTOGRAM/SET/MINIMUM id vmin

ID
      C
        Histogram Identifier Loop
VMIN
      R
        Minimum value

Set the minimum value on the Y axis. To select again an automatic scale, just set VMIN equal to the maximum. Example:

PAW > MIN id 0
PAW > MAX id 0

Reset the default scaling.

/HISTOGRAM/SET/NORMALIZE_FACTOR id [ xnorm ]

ID
        C
          Histogram Identifier
XNORM
        R
          Normalisation factor D=1

Set the contents/errors normalisation factor. Only valid for histograms (1-Dim). (does not change contents, only
presentation).

/HISTOGRAM/SET/SCALE_FACTOR_2D id [ xscale ]

ID
         C
           Histogram Identifier
XSCALE
         R
           Scale factor D=0

Set the scale factor for histograms (2-Dim).

/HISTOGRAM/SET/IDOPT id option

ID
        C
          Histogram Identifier
OPTION
        C
          Options

OPTION:

'SETD*'
        Set all options to the default values
'SHOW'
        Print all the options currently set
'BLAC'
        1 Dim histogram printed with X characters
'CONT*'
        1 Dim histogram is printed with the contour option
'STAR'
        1 Dim histogram is printed with a * at the Y value
'SCAT*'
        Print a 2 Dim histogram as a scatter-plot
'TABL'
        Print a 2 Dim histogram as a table
'PROE*'
        Plot errors as the error on mean of bin in Y for profile histograms
'PROS'
        Plot errors as the Spread of each bin in Y for profile histograms
'STAT'
        Mean value and RMS computed at filling time
'NSTA*'
        Mean value and RMS computed from bin contents only
'ERRO'
        Errors bars printed as SQRT(contents)
'NERR*'
        Do not print print error bars
'INTE'
        Print the values of integrated contents bin by bin
'NINT*'
        Do not print integrated contents
'LOGY'
        1 Dim histogram is printed in Log scale in Y
'LINY*'
        1 Dim histogram is printed in linear scale in Y
'PCHA*'
        Print channel numbers
'NPCH'
        Do not print channel numbers
'PCON*'
        Print bin contents
'NPCO'
        Do not print bin contents
'PLOW*'
        Print values of low edge of the bins
'NPLO'
        Do not print the low edge
'PERR'
        Print the values of the errors for each bin
'NPER*'
        Do not print the values of the errors
'PFUN'
        Print the values of the associated function bin by bin
'NPFU*'
        Do not print the values of the associated function
'PHIS*'
        Print the histogram profile
'NPHI'
        Do not print the histogram profile
'PSTA*'
        Print the values of statistics (entries,mean,RMS,etc.)
'NPST'
        Do not print values of statistics
'ROTA'
        Print histogram rotated by 90 degrees
'NROT*'
        Print histogram vertically
'1EVL'
        Force an integer value for the steps in the Y axis
'AEVL*'
        Steps for the Y axis are automatically computed
'2PAG'
        Histogram is printed over two pages
'1PAG*'
        Histogram is printed in one single page
'AUTO*'
        Automatic scaling

Set options for histogram ID. (* means default).