The ATLAS Level-1 Calorimeter Trigger

[Home] [Architecture] [Meetings] [Participants] [Publications] [Software] [Search]

HMINI Common Histogramming Library

T. Osborne, J.O. Petersen and D. Samyn, October 1989. Lynx/OS version by C.N.P.Gee.

This is a user's guide and a reference manual for the hmini histogram library.

Introduction to HMINI
INITIALISATION
BOOKING AND DELETING HISTOGRAMS
FILLING AND MODIFICATION OF BIN CONTENTS
ACCESS TO INFORMATION
ERROR MESSAGES
INTERNAL STRUCTURE
COMPATIBILITY WITH HBOOK
EXAMPLES AND TEST PROGRAMS
REFERENCES
ALPHABETICAL LIST OF HMINI ROUTINE NAMES

Introduction & General Features of HMINI

Initialisation
Booking and Deleting
Filling and modification of bin contents
Presentation of histograms
Access to histogram information
Error messages
Relation to HBOOK on Central Computers
Routine Types and Name Conventions

Routine Calling Sequences

INITIALISATION
- Initialisation
- Unused Space
BOOKING AND DELETING HISTOGRAMS
FILLING AND MODIFICATION OF BIN CONTENTS
PRESENTATION OF HISTOGRAMS
ACCESS TO INFORMATION
ERROR MESSAGES
INTERNAL STRUCTURE
- DIRECTORY FORMAT
- DATA FORMAT
  - One-dimension
  - Two-dimension
COMPATIBILITY WITH HBOOK
EXAMPLES AND TEST PROGRAMS Test programs
REFERENCES

Alphabetical list of HMINI Routine Names

HC1GST HC1LIN HC1LOG HC1PLO HC1PRI HC1RES HC2DOT HC2LEV HC2PLO HC2PRI HC2RES HCCCUR HCCCNT HCCDEL HCCERR HCCFRA HCCGAR HCCGD3 HCCINI HCCLMS HCCLPL HCCLPR HCCMAX HCCMIN HCCMXC HCCPAG HCCRST HCCSPA HCIDAL HCSIZE HCTYPE HI1ADD HI1AFI HI1BOO HI1DIR HI1FIL HI1GIN HI1PUT HI1SPL HI1SPR HI2ADD HI2AFI HI2BOO HI2DIR HI2FIL HI2PUT HI2SPL HI2SPR HICAGE HICAPU HR1ADD HR1AFI HR1BOO HR1DIR HR1FIL HR1PUT HR1SPL HR1SPR HR2ADD HR2AFI HR2BOO HR2DIR HR2FIL HR2GIN HR2PUT HR2SPL HR2SPR HRCAGE HRCAPU

INTRODUCTION

GENERAL FEATURES OF HMINI

HMINI is a general histogram package providing histogramming facilities typically required in the on-line computing environment of physics experiments at CERN. The package is written in portable FORTRAN and is largely computer independent (except for a few routines concerned with I/O and basic bit manipulations).

The library has been implemented on the mini-computers and micros supported by the OC group i.e. VAX, NORD and MC68000.

For graphics operations, HMINI relies on the standard CERN graphics package miniGD3

HMINI provides facilities for

histogramming of integer and real variables in one and two dimensions

fast histogram filling, array filling modification of bin contents (replace / add / zero)
(read) access to histogram directory and data information
presentation of histograms in print and plot format with a variety of format options: full and selective print or plot, graphics input, user control of output LUNs, redefinition of scaling, binning and bin resolution etc.
user specification of bin content capacity
dynamic allocation of space for bin overflows
free space recovery by garbage collection
error reporting system with user defined output device

The following sections will explain and discuss these features in more detail. Each section is an overview of one of the following chapters.

Initialisation

Two areas of memory are associated with each histogram : the directory area describes the histogram parameters (title, bin limits etc.) while the data area is used to store the bin contents. The histogram directories and data areas are allocated on two labelled common blocks, HDIR and HDAT :

COMMON / HDIR / IDIRBU (length) COMMON / HDAT / IDATBU (length)

The first histogramming call in the user's program must be an initialisation call (HCCINI) in order to specify the lengths of HDIR and HDAT. A detailed description of the histogram buffer organisation is given in chapter

Booking and Deleting

After the HMINI package has been initialised histograms may be booked. It is possible to define one and two dimensional histograms of type INTEGER and REAL; the two types refer to histograms in which the values to be histogrammed are of type integer or real respectively.

A histogram is uniquely defined by an identifier (ID) ; the histogram identifier is a user defined integer # 0 which is used in all further calls referring to the same histogram. In some calls, ID=0 means that the call refers to all defined histograms.

The maximum bin contents (the bin capacity) may be specified by the user through the parameter IMXCNT. The default value of IMXCNT is 0 which means that one computer word is used for each histogram bin. If the contents of bin overflows, additional space is allocated dynamically in the data buffer. If IMXCNT=0, the maximum bin contents on a 16 bit computer is (2**32-1).

In order to reduce memory space, other values of IMXCNT can be chosen. The number of bits allocated to a bin is the smallest integer, NBB, for which 2**NBB > IMXCNT. In addition a bin cannot cross a computer word boundary.

Thus, on a 16 bit computer the possible values of NBB are between 1 and 16 but 9 <= NBB le 15 will not give any reduction in histogram space. The most 'reasonable' values, except the default NBB=16, are NBB=4 and 8 corresponding to 8 le IMXCNT le 15 and 128 le IMXCNT le 255 respectively. On a 32-bit computer 16 bits per bin can be allocated by defining 32768 le IMXCNT le 65535 e.g. IMXCNT = 2**16-1. In general, NBB bits per bin can be allocated by specifying IMXCNT = 2**NBB-1.

If a 'reduced' bin overflows, a full computer word is used for the overflow counts. If for example a byte per bin is specified by IMXCNT, maximum bin contents are (2**8)*(2**16)-1 on a 16-bit computer.

Booked histograms may be deleted (HCCDEL); the space freed by this call may be recuperated on user request by garbage collection (HCCGAR).

Filling and modification of bin contents

In HMINI, bins are defined by bin value and not by bin number. For a one dimensional histogram any value XVAL along the X-axis defines uniquely a bin (and a bin number). Similarly in a two dimensional histogram a set of values (XVAL, YVAL) define uniquely a bin. In previous histogramming packages (ZHIST, RSXLIB) bins were referred to by bin number.

If the bin value lies outside the range of values specified at booking time for the histogram the bin is defined as an underflow or overflow bin. For 1-dimensional histograms there is one underflow and one overfiow bin. For 2-dimensional histograms there exists a set of 8 underflow/overflow bins for all combinations of underflow and overflow of X and Y values- see section 5.1.2 for definitions of these.

For the time critical filling calls an additional parameter NHIST is introduced in order to reduce the execution time. The first time a filling routine is called, the directory pointer for the histogram defined by ID is returned in NHIST. Following calls to the filling routines then use NHIST for direct fast access to the directory thereby avoiding the sequential scanning of histogram directories to find the directory corresponding to histogram ID.

The following rules apply to the use of the NHIST parameter

NHIST should be set to zero before the first filling call
NHIST is a histogram dependent variable : the user must define one NHIST variable per histogram
NHIST variables should never be changed by the user

Bin contents are in HMINI internally represented as bit strings in unsigned integer format with a maximum length of two computer words. First this implies that HMINI does not support weighted bin contents or negative bin contents. Secondly, since bin contents may exceed the maximum possible integer value (2**32-1 versus 2**15-1 on a 16 bit computer), real parameters are used to represent bin content variables in subroutine calls (e.g. PUT/GET/ADD).

Booked histograms can be filled in two ways. The simplest is to enter a single value in a histogram (single fill) but the possibility also exists to enter an array of values in one subroutine call (array fill).

Other subroutine calls are available to modify the bin contents of a histogram. The PUT calls are used to replace bin contents individually (single put) or 'globally' (array put) in other words to store an array in a histogram. In a similar way values may be ADDED to the bin contents - bin by bin (single add) or 'globally' (array add). This allows histograms to be added (or subtracted) : the bin contents of one histogram can be extracted (array get, see below) and added (array put) to another histogram.

Presentation of histograms

Histograms may be displayed in print or plot format with a variety of options; for plotting, HMINI uses the standard CERN graphics package miniGD3 which supports TEKTRONIX devices (T4006, T4010, T4012, T4014, T4027). For HMINI running on MC68000 other options are available, see the VALETplus User's Guide for details.

On the output terminal (VDU, Tektronix, line printer) each histogram is identified by the title and identifier as defined at booking.

By default, histograms are printed or plotted with maximum output scaling i.e. the scale for bin contents spans the interval from zero to max. bin contents. This scaling may be redefined by user specified lower and upper limits (HCCMIN, HCCMAX).

For one-dimensional histograms it is possible to choose a logarithmic scale (HC1LOG, HC1LIN).

Histograms can be output in print format on an alphanumeric terminal (VDU) or a line printer. One dimensional histograms are by default printed with the bin contents scale horizontally i.e. across the paper with the scale adjusted to the paper wi The bin value axis (x-axis) is printed vertically i.e. along the paper with one bin per line (full resolution). Two dimensional histograms are by default printed so as to fit onto one page and bin contents are displayed using 10 levels i.e. with a resolution of 1/10 using the symbols .,+,2,3,4,5,6,7,8,9. These defaults can be changed by the user (HCCPAG, HC2LEV).

Histograms may be displayed in plot format on Tektronix terminals or in graphics windows on personal computers. The default terminal is T4012 with small character size but these parameters as well as the logical unit number can be redefined by the user (HCCGD3, HCCLPL). The number of histograms on the screen, by default one, may be selected by calling the routine HCCFRA. The plot resolution can be changed by rebinning (HC*RES) and in 2 dimensional histograms, where dots are used to represent bin contents, the max. # of dots/bin can be defined (HC2DOT).

After a plot the screen cursor is left in an 'undefined' state. A call to HCCCUR resets the cursor position to the lower left hand corner of the screen, which allows some text to be output together with the plot. Any other cursor manipulation or more generally any graphics operation must be done by direct calls to the miniGD3 routines.

In addition to routines for printing and plotting full histograms, there are calls which allow user selected parts of a histogram to be displayed (zooming).

The print and plot formats are described in detail in the introduction to chapter

Access to histogram information

These routines provide user access to either histogram directories or histogram data (bin contents).

The GET function calls are the inverse of the PUT subroutine calls described above; as for those, single and array GETs are available. Note that bin contents returned by the GET routines are floating point values which allows overflow bin contents to be returned correctly.

On graphics devices with input facilities bin values and contents may be retrieved by positioning the crosshair cursor at the appropriate bin.

Finally, real function calls are available to get integrated, maximum and minimum bin contents of any histogram.

Error messages

Error messages are reported on a logical unit defined by the user (HCCLMS). If the logical unit is equal to zero, error output is suppressed, but the last error and the routine in which it occurred is always available to the user via a call to HCCERR.

Relation to HBOOK on Central Computers

The histogramming requirements for online minicomputer applications can not be met with a subset of HBOOK calls. The following technical requirements lead to differences in external specifications:

HMINI separates histogram directory and data space in two common blocks in order to allow mapping of the histogram data space.
HMINI minimises execution time for integer filling. This means separate calls for integer and floating point filling, integer bin contents only and no support for weighted filling.
HMINI separates calls to one and two dimensional histograms in order to get load time modularity.
HMINI supports graphic input
Garbage collection is user controllable so that it can be done outside time critical periods.
Error conditions are optionally available to user programs and need not always be printed.

With these differences in mind HMINI has been designed to be as close as possible to HBOOK, without introducing unnecessary confusion.

This has been achieved through the following guidelines:

All HMINI names are different from HBOOK names
HMINI naming conventions are consistent and follow a set of rules similar to the ESONE CAMAC calls.
In all HMINI calls for which an equivalent HBOOK call exists the parameter passing is identical.

ROUTINE TYPES AND NAME CONVENTIONS

There are two types of calls. The INTEGER calls which refer to histograms where bin limits and values to be histogrammed are integer values and REAL calls which refer to histograms where bin limits and values to be histogrammed are floating point values.

Subroutine name conventions:

- INTEGER calls :	HI****
- REAL calls :	HR****
- common to INTEGER and REAL :	HC****
- 1-dimension calls :	H1**
- 2-dimension calls :	H2**
- common to 1 and 2-dimension :	HC**
- common to real/integer and 1/2 dimension :	HCC***

INITIALISATION

Initialisation

CALL HCCINI(NDIRLG, NDATLG)

Action Initialise the HDIR and HDAT buffer (in COMMON).

Parameters

NDIRLG: integer - # words for HDIR space
NDATLG: integer - # words for HDAT space

Remarks

For space requirements refer to chapter 9 for a complete description or sections 3.1, 3.2 for a definition of space required for a histogram

Unused Space

CALL HCCSPA(RNW, RND)

Action Unused space in HDIR and HDAT buffers is returned

Parameters

RNW: real - # words left in HDIR buffer
RND: real - # words left in HDAT buffer

BOOKING AND DELETING HISTOGRAMS

INTEGER ROUTINES

Book

CALL HI1BOO(ID, TIT, INBINS, ILOW, IUP, IMXCNT)

Action Book a 1-dimensional histogram

Parameters

ID: integer - histogram identifier
TIT: array - histogram title
INBINS: integer - number of bins
ILOW: integer - lower value of first bin
IUP: integer - upper value of last bin
IMXCNT: integer - maximum single bin contents

Special values

IMXCNT = 0 - bits/bin = computer word size

Remarks

the identifier must be unique for each histogram.
the title is an hollerith string terminated by a $ character.
if IMXCNT=0 and bins don't overflow the space required is (in words):
l2 + title length in common block HDIR

# bins + 2 in common block HDAT
if the bin width, defined as (IUP - ILOW)/INBINS, is not an integer, the upper value will be redefined internally. IUP is NOT modified.
see section 1.1.2 for a description of the parameter IMXCNT

CALL HI2BOO(ID, TIT, IXBINS, IXLOW, IXUP, IYBINS, IYLOW, IYUP, IMXCNT)

Action Book a 2-dimensional histogram

Parameters

ID: integer - histogram identifier
TIT: array - histogram title
IXBINS: integer - number of X bins
IXLOW: integer - lower value of first X bin
IXUP: integer - upper value of last X bin
IYBINS: integer - number of Y bins
IYLOW: integer - lower value of first Y bin
IYUP: integer - upper value of last Y bin
IMXCNT: integer - maximum single bin contents

Special values

IMXCNT = 0 - bits/bin = computer word size

Remarks

the identifier must be unique for each histogram.
the title is an hollerith string terminated by a $ character.
if IMXCNT=0 and bins don't overflow the space required is (in words):
16 + title length in common block HDIR
# bins + 8 in common block HDAT
if the X bin width, defined as (IXUP - IXLOW)/IXBINS, is not an integer, the upper value of last bin will be redefined internally. IXUP is NOT modified. Similarly the upper Y bin value will be recomputed if the calculated Y bin width is not an integer.
see section 1.1.2 for a description of the parameter IMXCNT

REAL ROUTINES

Book

CALL HR1BOO(ID, TIT, INBINS, RLOW, RUP, IMXCNT)

Action Book a 1-dimensional histogram

Parameters

ID: integer - histogram identifier
TIT: vector - histogram title
INBINS: integer - number of bins
RLOW: real - lower value of first bin
RUP: real - upper value of last bin
IMXCNT: integer - maximum single bin contents

Special values

IMXCNT = 0 - bits/bin = computer word size

Remarks

the identifier must be unique for each histogram.
the title is an hollerith string terminated by a $ character.
if IMXCNT=0 and bins don't overflow the space required is (in words): 15 + title length in common block HDIR # bins + 2 in common block HDAT
see section 1.1.2 for a description of the parameter IMXCNT

CALL HR2BOO(ID, TIT, IXBINS, RXLOW, RXUP, IYBINS, RYLOW, RYUP, IMXCNT)

Action Book a 2-dimensional histogram

Parameters

ID: integer - histogram identifier
TIT: vector - histogram title
IXBINS: integer - number of X bins
RXLOW: real - lower value of first X bin
RXUP: real - upper value of last X bin
IYBINS: integer - number of Y bins
RYLOW: real - lower value of first Y bin
RYUP: real - upper value of last Y bin
IMXCNT: integer - maximum single bin contents

Special values

IMXCNT = 0 - bits/bin = computer word size

Remarks

the identifier must be unique for each histogram.
the title is an hollerith string terminated by a $ character.
if IMXCNT=0 and bins don't overflow the space required is (in words):
22 + title length in common block HDIR
# bins + 8 in common block HDAT
see section 1.1.2 for a description of the parameter IMXCNT

COMMON ROUTINES

Delete

CALL HCCDEL(ID)

Action Delete histogram. The space allocated to the histogram is not freed.

Parameters

ID: integer - histogram identifier (ID=0 means all)

Garbage Collection

CALL HCCGAR(IDUM)

Action Recover space allocated to deleted histograms.

Parameters

IDUM: integer - dummy parameter

Remarks

Histogram pointers NHIST must be reset to zero the user after call to HCCGAR

FILLING AND MODIFICATION OF BIN CONTENTS

INTEGER ROUTINES

Single Fill

CALL HI1FIL(ID, NHIST, IVAL)

Action Fill a 1-dimensional histogram. The contents of the bin defined by IVAL, is incremented by one.

Parameters

ID: integer - histogram identifier
NHIST: integer - histogram pointer
IVAL: integer - value to be histogrammed

Special values

NHIST must be equal to zero the first time the filling routine is called.

Remarks

the variable NHIST must not be changed by the program
NHIST is histogram dependent : the user must define one NHIST variable per histogram
the bin "defined by IVAL" is bin number NX where
ILOW+(NX-1)*IBW<=IVALIBW is the bin width which is derived from the booking parameters IBW = (IUP-ILOW)/INBINS. If IVAL = IUP, the underflow or overflow bins resp. are incremented

CALL HI2FIL(ID, NHIST, IXVAL, IYVAL)

Action Fill a 2-dimensional histogram. The contents of the bin, defined by (IXVAL, IYVAL), is incremented by one.

Parameters

ID: integer - histogram identifier
NHIST: integer - histogram pointer
IXVAL: integer - X value to be histogrammed
IYVAL: integer - Y value to be histogrammed

Special values

NHIST must be equal to zero the first time the filling routine is called.

Remarks

the bin "defined by (IXVAL, IYVAL)" is bin number (NX, NY) where
IXLOW+(NX-1)*IXBW le IXVAL IYLOW+(NY-1)*IYBW le IYVAL IXBW, IYBW are bin widths in (x, y) which are derived from the booking parameters: IXBW=(IXUP-IXLOW)/IXBINS, IYBW=(IYUP-IYLOW)/IYBINS. If IXVAL ge IXUP or IYVAL geIYUP the appropriate underflow, overflow bins are incremented

Array Fill

CALL HI1AFI(ID, NHIST, IARRV, INSIZ)

Action fill a 1-dimensional histogram.The contents of the bins, defined by the values in IARRV, are incremented by one.

Parameters

ID: integer - histogram identifier
NHIST: integer - histogram pointer
IARRV: integer - 1-dimensional array of bin values to be histogrammed
INSIZ: integer - no. of bin values

Special values: NHIST must be equal to zero the first time the filling routine is called.

Remarks

the variable NHIST must not be changed by the program
NHIST is histogram dependent : the user must define one NHIST variable per histogram
for the rules governing the filling, see HI1FIL

CALL HI2AFI(ID, NHIST, IARRV, INSIZ)

Action Fill a 2-dimensional histogram.The contents of the bins, defined by the values in IARRV, are incremented by one.

Parameters

ID: integer - histogram identifier
NHIST: integer - histogram pointer
IARRV: integer - 2-dimensional array of bin values, dimension (2, INSIZ)
INSIZ: integer - no. of bin values

Special values

NHIST must be equal to zero the first time the filling routine is called.

Remarks

the X bin value must be stored in IARRV(1, i) and the Y bin value in IARRV(2, i).
the variable NHIST must not be changed by the program
NHIST is histogram dependent : the user must define one NHIST variable per histogram
for the rules governing the filling, see HI2FIL

Single Put

CALL HI1PUT(ID, IVAL, RCON)

Action Replace in a 1-dimensional histogram. The contents of the bin, defined by IVAL, is replaced by a new contents RCON

Parameters

ID: integer - histogram identifier
IVAL: integer - bin value
RCON: real - new bin contents

Remarks

Any fractional part of RCON is ignored
if RCON is negative, an error message is given and results will be unpredictable
if IVAL is outside bin limits for histogram ID, the underflow or overflow bins will be replaced

CALL HI2PUT(ID, IXVAL, IYVAL, RCON)

Action Replace in a 2-dimensional histogram. The contents of the bin, defined by a (IXVAL, YVAL), is replaced by a new contents RCON

Parameters

ID: integer - histogram identifier
IXVAL: integer - X bin value
IYVAL: integer - Y bin value
RCON: real - new bin contents

Remarks

Any fractional part of RCON is ignored
if RCON is negative, an error message is given and results will be unpredictable
if (IXVAL, IYVAL) are outside bin limits for histogram ID, the underflow or overflow bins will be replaced

Array Put

CALL HICAPU(ID, RARRC)

Action Replace in a 1-dimensional or 2-dimensional histogram: all the bins get their contents replaced sequentially by new contents contained in array RARR

Parameters

ID: integer - histogram identifier
RARRC: real array - new bin contents; one dimensional histograms: RARRC(INBINS); two dimensional histograms: RARRC(IXBINS, IYBINS)

Remarks

Any fractional parts of array elements are ignored
the elements of RARRC should not be negative. For each element <0 an error message is produced and results will be unpredictable.
underflow and overflow bins are not replaced.

Single Add

CALL HI1ADD(ID, IVAL, RCON)

Action Add in a 1-dimensional histogram. The contents of the bin, defined by (IXVAL, IYVAL), is incremented by a value RCON

Parameters

ID: integer - histogram identifier
IVAL: integer - bin value
RCON: real - value to be added to bin contents

Remarks

RCON can be positive or negative but resulting content must not be negative. If they are, an error message will be issued and results will be unpredictable.
Any fractional part of RCON will be ignored
IVAL is outside bin limits of histogram ID, the underflow or overflow bins will be updated.

CALL HI2ADD(ID, IXVAL, IYVAL, RCON)

Action Add in a 2-dimensional histogram. The contents of the bin, defined by (IXVAL, IYVAL), is incremented by a value RCON

Parameters

ID: integer - histogram identifier
IXVAL: integer - X bin value
IYVAL: integer - Y bin value
RCON: real - value to be added to bin contents

Remarks

RCON can be positive or negative but resulting contents must not be negative. If they are, an error message will be issued and results will be unpredictable.
Any fractional part of RCON will be ignored
if (IXVAL, IYVAL) are outside bin limits of histogram ID, the underflow or overflow bins will be updated.

REAL ROUTINES

Single Fill

CALL HR1FIL(ID, NHIST, RVAL)

Action Fill a 1-dimensional histogram. The contents of the bin, defined by RVAL, is incremented by one.

Parameters

ID: integer - histogram identifier
NHIST: integer - histogram pointer
RVAL: real - value to be histogrammed

Special Values

NHIST must be equal to zero the first time the filling routine is called.

Remarks

the variable NHIST must not be changed by the program
NHIST is histogram dependent : the user must define one NHIST variable per histogram
the bin "defined by RVAL" is bin number NX where
RLOW+(NX-1)*BWleRVALBW is the bin width which is derived from the booking parameters : BW = (RUP-RLOW)/INBINS. If RVALge RUP, the underflow or overflow bins resp. are incremented

CALL HR2FIL(ID, NHIST, RXVAL, RYVAL)

Action Fill a 2-dimensional histogram. The contents of the bin, defined by (RXVAL, RYVAL), is incremented by one.

Parameters

ID: integer - histogram identifier
NHIST: integer - histogram pointer
RXVA: real - X value to be histogrammed
RYVAL: real - Y value to be histogrammed

Special values

NHIST must be equal to zero the first time the filling routine is called. Remarks

the bin "defined by (RXVAL, RYVAL)" is bin number (NX, NY) where RXLOW+(NX-1)*RXBW le RXVAL le RYVAL ge RXUP or RYVAL ge RYUP the appropriate underflow, overflow bins are incremented

Array Fill

CALL HR1AFI(ID, NHIST, RARRV, INSIZ)

Action Fill a 1-dimensional histogram.The contents of the bins, defined by the values in RARRV, are incremented by one.

Parameters

ID: integer - histogram identifier
NHIST: integer - histogram pointer
RARRV: real - 1-dimensional array of bin values to be histogrammed
INSIZ: integer - no. of bin values

Special values

NHIST must be equal to zero the first time the filling routine is called.

Remarks

the variable NHIST must not be changed by the program
NHIST is histogram dependent : the user must define one NHIST variable per histogram
for the rules governing the filling, see HI1FIL

CALL HR2AFI(ID, NHIST, RARRV, INSIZ)

Action Fill a 2-dimensional histogram.The contents of the bins, defined by the values in RARRV, are incremented by one.

Parameters

ID: integer - histogram identifier
NHIST: integer - histogram pointer
RARRV: real - 2-dimensional array of bin values, dimension (2, INSIZ)
INSIZ: integer - no. of bin values

Special values

NHIST must be equal to zero the first time the

Remarks

the variable NHIST must not be changed by the program
NHIST is histogram dependent : the user must define one NHIST variable per histogram
for the rules governing the filling, see HI2FIL

Single Put

CALL HR1PUT(ID, RVAL, RCON)

Action Replace in a 1-dimensional histogram. The contents of the bin, defined by RVAL, is replaced by a new contents RCON

Parameters

ID: integer - histogram identifier
RVAL: real - bin value
RCON: real - new bin contents

Remarks

Any fractional part of RCON is ignored
if RCON is negative, an error message is given and results will be unpredictable
if RVAL is outside bin limits for histogram ID, the underflow or overflow bins will be replaced

CALL HR2PUT(ID, RXVAL, RYVAL, RCON)

Action Replace in a 2-dimensional histogram. The contents of the bin, defined by (RXVAL, RYVAL), is replaced by a new contents RCON

Parameters

ID: integer - histogram identifier
RXVAL: real - X bin value
RYVAL: real - Y bin value
RCON: real - new bin contents

Remarks

Any fractional part of RCON is ignored
If RCON is negative, an error message is given and results will be umpredictable
if RVAL is outside bin limits for histogram ID, the underflow or overflow bins will be replaced

Array Put

CALL HRCAPU(ID, RARRC)

Action Replace in a 1-dimensional or 2-dimensional histogram: all the bins get their contents replaced sequentially by new contents contained in array RARRC.

Parameters

ID: integer - histogram identifier
RARRC: real array - new bin contents; - one dimensional histograms : RARRC(INBINS); - two dimensional histograms : RARRC(IXBINS, IYBINS)

Remarks

Any fractional part of array elements is ignored
the elements of RARRC should not be negative. For each element <0 an error message is produced and results will be unpredictable.
underflow and overflow bins are not replaced.

Single Add

CALL HR1ADD(ID, RVAL, RCON)

Action Add in a 1-dimensional histogram. The contents of the bin, defined by RVAL, is incremented by a value RCON

Parameters

ID: integer - histogram identifier
RVAL: real - bin value
RCON: real - value to be added to bin contents

Remarks

RCON can be positive or negative but resulting contents must not be negative. If they are, an error message will be issued and results will be unpredictable.
Any fractional part of RCON will be ignored
if RVAL is outside bin limits of histogram ID, the underflow or overflow bins will be updated.

CALL HR2ADD(ID, RXVAL, RYVAL, RCON)

Action Add in a 2-dimensional histogram. The contents of the bin, defined by (RXVAL, RYVAL), is incremented by a value RCON

Parameters

ID: integer - histogram identifier
RXVAL: real - X bin value
RYVAL: real - Y bin value
RCON: real - value to be added to bin contents

Remarks

RCON can be positive or negative but resulting contents must not be negative. If they are, an error message will be issued and results will be unpredictable.
Any fractional part of RCON will be ignored
if RVAL is outside bin limits of histogram ID, the underflow or overflow bins will be updated.

COMMON ROUTINES

Reset

CALL HCCRST(ID)

Action Reset a histogram. The bin contents are reset to zero.

Parameters

ID: integer - histogram identifier (ID=0 means all)

PRESENTATION OF HISTOGRAMS

In sections 5.1 and 5.2 is given a description of the histogram print and plot output formats.

For a general overview of the histogram display facilities available in HMINI see section 1.1.4

For definition of subroutines used for histogram display see sections 5.3 to 5.5

HISTOGRAM PRINT FORMAT

Histograms can be output in print format on an alphanumeric terminal (VDU) or a line printer. The default output unit for printed histograms is the standard print logical unit for the computer. This can be changed by a call to HCCLPR. Each histogram is identified by the title and identifier as defined at booking.

Each histogram is started on a new page. The output size of histograms can be defined by a call to HCCPAG. If the number of bins in the histogram is greater than the user defined number of lines, automatic rebinning will take place. A factor R is calculated internally and every successive R bins are combined where R=1,2,5 or 10 etc.

One-dimensional histograms

One dimensional histograms are printed with the bin contents horizontally i.e. across the paper and the bin value axis vertically i.e. along the paper. For each bin the bin number, lower bin limit and bin contents are printed as well as a number of asterisks representing the bin contents. The underflow and overflow bin contents and the upper limit of the last bin are also given. Bin limits and contents are printed in real format.

The bin contents scale is adjusted to the page width. The lower limit of the scale is by default equal to 0 and the upper limit equal to the maximum bin contents. The scale limits can be redefined by calls to HCCMIN and HCCMAX.

The contents of each bin is represented by a number of asterisks followed by an X. The number of asterisks N is the nearest integer to S where

S = (bin contents - lower limit of scale) / (upper limit of scale - lower limit of scale) * page width (in characters)

Output statistics

The following statistics for the histogram are printed:

Integrated contents defined as the sum of the bin contents NOT including the underflow and overflow bins
Maximum bin contents (not including underflow or overflow bins)
Min Scale defined as lower limit of scale (0.0 is output if scaling is automatic)
Max scale defined as upper limit of scale (0.0 is output if scaling is automatic)
Log Output defined as 1 if histogram format is logarithmic, 0 otherwise
Resolution defined as R above.
Bin format defined as number of bits per bin (0 is printed if default), see section 1.1.3
Mean value defined as
M = (N1*X1+N2*X2+ -- +NI*XI+ -- +NN*XN) / NTOT

where NI is the contents of bin number I, XI is the centre value of bin number I and NTOT = N1+N2 -- NI+--+NN is the total number of entries (excluding underflow/overflow). If only a part of a histogram is output, the mean value is computed from the entries in the selected part only i.e. N = # bins in the selected part.
Sigma defined as
S = SQRT [(N1*X1**2+-- + NI*XI**2+-- + NN*XN**2)/NTOT - M**2]

with NI, XI, NTOT and M defined as above.
Entries/asterisk = # entries represented by one asterisk

Two-dimensional histograms

The Y-axis is printed vertically and the X-axis horizontally (i.e. across the paper on a line printer). The lower limit of each Y-bin is given as well as the upper limit of the last Y-bin. The X-axis is printed with + characters indicating bins no. 6,11,16,21 etc. The lower limits of every fifth bin are printed starting from the first bin i.e. the numbers printed are lower limits of bins indicated by the + characters.

Bin contents are represented by alphanumeric characters with each character representing a certain number of entries. The number of characters or levels can be changed up to a max. of 36 by calling the routine HC2LEV. The range of bin contents corresponding to one character (i.e. the number of entries per level) is given by

NPL = (upper limit of scale - lower limit of scale) / # levels

The relation between levels, characters and bin contents is given in the table below:

Level Symbol Bin contents range 1 . 0.0 <contents < 1.0*NPL 2 + 1.0*NPL <="contents" < 2.0*NPL 3 2 2.0*NPL <="contents" < 3.0*NPL 4 3 3.0*NPL <="contents" < 4.0*NPL . . . 10 9 9.0*NPL <="contents" < 10.0*NPL 11 A 10.0*NPL <="contents" < 11.0*NPL 12 B 11.0*NPL <="contents" < 12.0*NPL . . 36 Z 35.0*NPL <="contents" <="36.0*NPL" * greater than upper limit of scaling

Any cell with zero contents is left blank. Any contents greater than the upper limit for scaling is represented by an asterisk.

Output statistics

Statistics printed are:

No. of levels
Bin format defined as number of bits per bin (0 is printed if default) see section 1.1.4
Min Scale defined as lower limit of scale (0.0 is output if scaling is automatic)
Max scale defined as upper limit of scale (0.0 is output if scaling is automatic)
Total - total number of histogram entries (including underflow/overflow)
Entries/level = NPL as defined above
Underflow/Overflow entries are represented in a table

HISTOGRAM PLOT FORMAT

Histograms may be displayed in plot format on Tektronix terminals or, in case of HMINI running on MC68000, also on PCs. The default terminal is T4012 with small character size but these parameters as well as the logical unit number can be redefined by the user (HCCGD3, HCCLPL). The number of histograms on the screen, by default one, may be selected by calling the routine HCCFRA. The plot resolution can be changed by rebinning (HC*RES). Each histogram is identified by the title and identifier as defined at booking. Every histogram is surrounded by a rectangular box.

One-dimensional histograms

The bin contents axis is vertical and is labelled with tick marks and numbers defining the bin contents scale. If the max. bin contents exceeds 1000, a scale factor of format 10**N is indicated at the upper end of the axis. The bin value axis is horizontal and is in a similar way labelled with a (variable) number of tick marks and numeric values.

For integer histograms these values are in the range -999 to 999, and for real histograms in the ranges -9.99 to -.1 or .1 to 9.99. If the user defined histogram limits fall outside these intervals, a scale factor of format 10**N is indicated at the right end of the x-axis.

The histogram contour is drawn as a full line.

Output Statistics

Below the histogram the following statistics are output:

M Mean value defined as
(N1*X1+N2*X2+ -- +NI*XI+ -- +NN*XN) / NTOT

where NI is the contents of bin number I, XI is the centre value of bin number I and NTOT = N1+N2 -- NI+--+NN is the total number of entries (excluding underflow/overflow). If only a part of a histogram is output, the mean value is computed from the entries in the selected part only i.e. N = # bins in the selected part.
S Sigma defined as
SQRT [(N1*X1**2+-- + NI*XI**2+-- + NN*XN**2)/NTOT - M**2]

with NI, XI, NTOT and M defined above.
U underflow - No. of entries in underflow bin
O overflow - No. of entries in overflow bin
C Integrated contents - Total number of entries not including underflow/overflow
MX - maximum bin contents

Two-dimensional histograms

The Y and X axes are now both representing bin values and are labelled in a way similar to the bin value axis in one dimensional histograms.

Bin contents are represented by dots (= little crosses), the number of dots being proportional to the number of entries per bin : a densely populated area of the x-y plane has a high dot density. The maximum number of dots per bin can be changed by calling HC2DOT.

Below the plot the following statistics are output

C Integrated contents - number of entries not including underflow/overflow
U/O no. of entries in all underflow/overflow bins
MX maximum bin contents

GENERAL EDITING

Scaling

CALL HCCMAX(ID, RMX)

Action Overruling the automatic maximum used for output scaling. If HCCMAX is not - called, the upper limit of scale is automatically the maximum bin contents.

Parameters

ID: integer - histogram identifier (ID=0 means all)
RMX: real - upper limit of scale for all subsequent output

Special values RMX=0.0 resets subsequent outputs for automatic calculation of upper limit for scaling.

CALL HCCMIN(ID, RMN)

Action Overruling the automatic zero lower limit for output scaling. If HCCMIN is not called, the lower limit of scale is automatically zero.

Parameters

ID: integer - histogram identifier (ID=0 means all)
RMN: real - lower limit of scale for all subsequent output

Special values RMN=0.0 resets subsequent outputs for automatic zero lower limit for scaling.

Linear, Logarithmic Scale

CALL HC1LOG(ID)

Action Logarithmic presentation of subsequent outputs. If HC1LOG is not called, output is in linear presentation.

Parameters

ID: integer - histogram identifier (ID=0 means all)

CALL HC1LIN(ID)

Action Linear presentation of subsequent outputs.

Parameters

ID: integer - histogram identifier (ID=0 means all)

PRINT

Note that parameters set in the routines HCCLPR, HCCPAG, HC2LEV apply to all histograms output after the call and are in effect until another call to the same routine resets them.

Output Unit

CALL HCCLPR(LU)

Action Set logical unit for print output.

Parameters

LU: integer - logical unit

Remarks

Defaults: NORD = 1, VAX = 6, MC68000 = 6

Page Size

CALL HCCPAG(ICOLUM, ILINES)

Action Defines maximum histogram size on print output

Parameters

ICOLUM: integer - # characters per line
ILINES: integer - # lines per histogram

Remarks

Defaults:
- ICOLUM = 72 (narrow paper width)
- ILINES = (no. of bins + constant) for 1-D histogram
- ILINES = 50 for 2-D histogram (normal output page length)

If the number of bins is too large to fit into the histogram size the contents of every R bins are combined where R=2,5 or 10 and histograms are output with a reduced number of output bins. The most suitable value for R is calculated internally.

Levels

CALL HC2LEV(NBL)

Action Sets the number of levels to be used in printing a 2 dimensional histogram.

Parameters

NBL: integer - # of levels

Remarks

Default value = 10 using symbols .,+,1,2....9
Maximum value = 36 using symbols .,+,1,2...9, A,B...Z
Any value of NBL greater than 36 will be converted to 36

Full Print

CALL HC1PRI(ID)

Action Print a 1-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)

CALL HC2PRI(ID)

Action Print a 2-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)

Selective Print

CALL HI1SPR(ID, IFIRST, ILAST)

Action Print part of a 1-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)
IFIRST: integer - bin value defining first bin to be displayed
ILAST: integer - bin value defining last bin to be displayed

Remarks

for bin definitions, see HI1FIL

CALL HR1SPR(ID, RFIRST, RLAST)

Action Print part of a 1-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)
RFIRST: real - bin value defining first bin to be displayed
RLAST: real - bin value defining last bin to be displayed

Remarks

for bin definitions, see HR1FIL

CALL HI2SPR(ID, IXFRST, IXLAST, IYFRST, IYLAST)

Action Print part of a 2-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)
IXFRST: integer - bin value defining first X bin to be displayed
IXLAST: integer - bin value defining last X bin to be displayed
IYFRST: integer - bin value defining first Y bin to be displayed
IYLAST: integer - bin value defining last Y bin to be displayed

Remarks

for bin definitions, see HI2FIL

CALL HR2SPR(ID, RXFRST, RXLAST, RYFRST, RYLAST)

Action Print part of a 2-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)
RXFRST: real - bin value defining first X bin to be displayed
RXLAST: real - bin value defining last X bin to be displayed
RYFRST: real - bin value defining first Y bin to be displayed
RYLAST: real - bin value defining last Y bin to be displayed

Remarks

for bin definitions, see HR2FIL

PLOT

Note that parameters set in the routines HCCLPL, HCCGD3, HCCFRA, HC1RES, HC2RES, HC2DOT apply to all histograms output after the call and are in effect until another call to the same routine resets them.

Output Unit

CALL HCCLPL(LU)

Action Set logical unit for plot output.

Parameters

LU: integer - logical unit

Remarks

Defaults: NORD = 1, VAX = 6, MC68000 = 6

Plotting Device Type

CALL HCCGD3(IDEV, ICHAR, IDUM)

Action Sets the device type and character size of plot terminal.

Parameters

IDEV: integer - device type, with one of the following values:; 4006 (Tektronix); 4010 (Tektronix); 4012 (Tektronix) DEFAULT; 4014; 4027; 68 output on personal computer (MAC, IBM PC, VAX station); 69 output on colour monitor (Eltec); 70 output on both
ICHAR: integer - character size; 1 = small DEFAULT; 2 = medium; 3 = large
IDUM: integer - dummy argument

Remarks

If call to HCCGD3 is made it must take place AFTER call to HCCINI but BEFORE call to HCCLPL
This must not contradict any calls directly to MINI-GD3 that specify that specify the same parameters. If a call to mini-GD3 specifying these parameters has been made this call to HCCGD3 must also be made otherwise HMINI defaults will be in effect.
The possible values of ICHAR obviously depend on available character sizes on plotting terminal being used.
The device types 68, 69, 70 are available on VALETplus.

Frame

CALL HCCFRA(NBX, NBY, NACTP)

Action Divides the screen into NBX*NBY frames and selects one frame for the next display.

Parameters

NBX: integer - # of pictures along X - default 1
NBY: integer - # of pictures along Y - default 1
NACTP: integer - frame number (default = 1)

Remarks

The frame number is defined as increasing by 1 horizontally i.e. if NBX=3 and NBY=2 then values of NACTP on screen are as follows: 1 2 3 4 5 6
this format only works correctly when small character size has been selected.

Output Resolution for Plots

CALL HC1RES(NRES)

Action Sets number of bins grouped together in one output bin for 1-dimensional histogram plot.

Parameters

NRES: integer - # bins/output bin - default 1

CALL HC2RES(XRES, YRES)

Action Sets number of bins per grouped together in one output bin for 2-dimensional histogram

Parameters

XRES: integer - # bins/output bin along X - default 1
YRES: integer - # bins/output bin along Y - default 1

Number of Dots- 2-dimensional Histogram

CALL HC2DOT(NBD)

Action Sets the maximum number of dots per bin for the plot drawn (2-dimensional histogram).

Parameters

NBD: integer - # of dots per bin - default 10

Setting Cursor Position

CALL HCCCUR

Action Sets the cursor at the bottom left hand corner of the screen. This is useful for writing a line of text after a plot.

Full Plot

CALL HC1PLO(ID)

Action Plot a 1-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)

CALL HC2PLO(id)

Action Plot a 2-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)

Selective Plot

CALL HI1SPL(ID, IFIRST, ILAST)

Action Plot part of a 1-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)
IFIRST: integer - bin value defining first bin to be displayed
ILAST: integer - bin value defining last bin to be displayed

Remarks

for bin definitions, see HI1FIL

CALL HR1SPL(ID, RFIRST, RLAST)

Action Plot part of a 1-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)
RFIRST: real - bin value defining first bin to be displayed
RLAST: real - bin value defining last bin to be displayed

Remarks

for bin definitions, see HR1FIL

CALL HI2SPL(ID, IXFRST, IXLAST, IYFRST, IYLAST)

Action Plot part of a 2-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)
IXFRST: integer - bin value defining first X bin to be displayed
IXLAST: integer - bin value defining last X bin to be displayed
IYFRST: integer - bin value defining first Y bin to be displayed
IYLAST: integer - bin value defining last Y bin to be displayed

Remarks

for bin definitions, see HI2FIL

CALL HR2SPL(ID, RXFRST, RXLAST, RYFRST, RYLAST)

Action Plot part of a 2-dimensional histogram.

Parameters

ID: integer - histogram identifier (ID=0 means all)
RXFRST: real - bin value defining first X bin to be displayed
RXLAST: real - bin value defining last X bin to be displayed
RYFRST: real - bin value defining first Y bin to be displayed
RYLAST: real - bin value defining last Y bin to be displayed

Remarks

for bin definitions, see HR2FIL

ACCESS TO INFORMATION

INTEGER HISTOGRAMS

Directory Information

CALL HI1DIR(ID, TIT, INBINS, ILOW, IUP, INBWT, NHIST)

Action Get directory of 1-dimensional histogram

Parameters

ID: integer - histogram identifier

Values returned TITarray - histogram title INBINSinteger - number of bins ILOWinteger - lower value of first bin IUPinteger - upper value of last bin INBWTinteger - number of machine words of title NHISTinteger - histogram directory pointer CALL HI2DIR(ID, TIT, IXBINS, IXLOW, IXUP, IYBINS, IYLOW, IYUP, INBWT, NHIST)

Action Get directory of 2-dimensional histogram

Parameters

ID: integer - histogram identifier
Values returned
TIT: array - histogram title
IXBINS: integer - number of X bins
IYBINS: integer - number of Y bins
IXLOW: integer - lower value of first X bin
IXUP: integer - upper value of last X bin
IYLOW: integer - lower value of first Y bin
IYUP: integer - upper value of last Y bin
INBWT: integer - number of machine words of title
NHIST: integer - histogram directory pointer

Single Get

RCON=HI1GET(ID, IVAL)

Action Get from a 1-dimensional histogram. The contents of the bin, defined by IVAL, is returned in RCON.

Parameters

ID: integer - histogram identifier
IVAL: integer - bin value
RCON: real - bin contents returned by the function

Remarks:

If IVAL is outside histogram limits underflow or overflow values will be returned

RCON=HI2GET(ID, IXVAL, IYVAL)

Action Get from a 2-dimensional histogram. The contents of the bin, defined by (IXVAL, IYVAL), is returned in RCON.

Parameters

ID: integer - histogram identifier
IXVAL: integer - X bin value
IYVAL: integer - Y bin value
RCON: real - bin contents returned by the function

Remarks

If IXVAL or IYVAL are outside histogram limits underflow or overflow values will be returned

Array Get

CALL HICAGE(ID, RARRC)

Action Get from a 1 or 2-dimensional histogram. The contents of all the bins are returned in array RARRC.

Parameters

ID: integer - histogram identifier
RARRC: real array - bin contents returned in RARRC(INBINS) or RARRC(IXBINS, IYBINS)

Graphic Get

These routines only work with T4010, T4012, T4014 or T4027 graphics terminals or with personal computers (MAC, IBM PC, VAX station) controlling a VALET.

The bin contents and value are returned under the assumption that the cursor points to the last histogram displayed when the histogram has been plotted by a call to HC*PLO(ID) routine where ID is not equal to zero. Calling the graphic get routines activates the cursor. Hitting a character (not carriage return) enters the cursor coordinates. These routines only work when there is ONE histogram per frame. There should be NO input/output on the plot terminal between the call to HC*PLO and the call to H**GIN. This includes calls to HCCCUR. The bin contents and values returned by these functions are independent of any change in output resolution made by call to HC*RES routines.

RCON=HI1GIN(IVAL, CHAR, IRES)

Action Graphic get of bin value and bin contents from a 1-dimensional histogram: the contents and bin value indicated by the crosshair cursor, character entered and bin resolution is returned.

Parameters

RCON: real - bin contents returned by the function
IVAL: integer - bin value
CHAR: integer - character entered - right justified (LSB) (hollerith)
IRES: integer - bin resolution (normally 1 unless HC1RES has been called)

RCON=HI2GIN(IXVAL, IYVAL, CHAR, IXRES, IYRES)

Action Graphic get of X and Y bin values and bin contents from a 2-dimensional histogram: the contents and x.y bin values of the bin indicated by the crosshair cursor, character entered and bin resolutions are returned.

Parameters

RCON: real - bin contents returned by the function
IXVAL: integer - X bin value
IYVAL: integer - Y bin value
CHAR: integer - character entered, right justified (LSB) -(hollerith)
IXRES: integer - bin resolution in X (normally 1 unless HC2RES has been called)
IYRES: integer - bin resolution in Y (normally 1 unless HC2RES has been called)

REAL HISTOGRAMS

Directory Information

CALL HR1DIR(ID, TIT, INBINS, RLOW, RUP, INBWT, NHIST)

Action Get directory of 1-dimensional histogram

Parameters

ID: integer - histogram identifier

Values returned

TIT: array - histogram title
INBINS: integer - number of bins
RLOW: real - lower value of first bin
RUP: real - upper value of last bin
INBWT: integer - number of machine words of title
NHIST: integer - histogram directory pointer

CALL HR2DIR(ID, TIT, IXBINS, RXLOW, RXUP, IYBINS, RYLOW, RYUP, INBWT, NHIST)

Action Get directory of 2-dimensional histogram

Parameters

ID: integer - histogram identifier

Values returned

TIT: array - histogram title
IXBINS: integer - number of X bins
IYBINS: integer - number of Y bins
RXLOW: real - lower value of first X bin
RXUP: real - upper value of last X bin
RYLOW: real - lower value of first Y bin
RYUP: real - upper value of last Y bin
INBWT: integer - number of machine words of title
NHIST: integer - histogram directory pointer

Single Get

RCON=HR1GET(ID, RVAL)

Action Get from a 1-dimensional histogram. The contents of the bin, defined by RVAL, is returned in RCON.

Parameters

ID: integer - histogram identifier
RVAL: real - bin value
RCON: real - bin contents returned by the function

Remarks

If RVAL is outside histogram limits underflow/overflow values will be returned

RCON=HR2GET(ID, RXVAL, RYVAL)

Action Get from a 2-dimensional histogram. The contents of the bin, defined by RXVAL, RYVAL, is returned in RCON.

Parameters

ID: integer - histogram identifier
RXVAL: real - X bin value
RYVAL: real - Y bin value
RCON: real - bin contents returned by the function

Remarks

If RXVAL or RYVAL are outside histogram limits underflow/overflow values will be returned

Array Get

CALL HRCAGE(ID, RARRC)

Action Get from a 1 or 2-dimensional histogram. The contents of all the bins are returned in array RARRC.

Parameters

ID: integer - histogram identifier
RARRC: real array - bin contents returned in RARRC(INBINS) or RARRC(IXBINS, IYBINS)

Graphic Get

These routines only work with T4010, T4012, T4014 or T4027 graphics terminals or with personal computers (MAC, IBM PC, VAX station) controlling a VALET.

RCON=HR1GIN(RVAL, CHAR, IRES)

Action Graphic get of bin value and bin contents from a 1-dimensional histogram: the contents and the value of the bin indicated by the crosshair cursor, character entered and bin resolution are returned.

Parameters

RCON: real - bin contents returned by the function
RVAL: real - bin value
CHAR: integer - character entered - right justified (LSB) (hollerith)
IRES: integer - bin resolution (normally 1 unless HC1RES been called)

RCON=HR2GIN(RXVAL, RYVAL, CHAR, IXRES, IYRES)

Action Graphic get of X and Y bin values and bin contents from a 2-dimensional histogram: the contents and bin values of the bin indicated by the crosshair cursor, character entered and bin resolutions are returned.

Parameters

RCON: real - bin contents returned by the function
RXVAL: real - X bin value
RYVAL: real - Y bin value
CHAR: integer - character entered - right justified (LSB) (hollerith)
IXRES: integer - bin resolution in X (normally 1 unless HC2RES has been called)
IYRES: integer - bin resolution in Y (normally 1 unless HC2RES has been called)

COMMON ROUTINES

Type of Histogram

CALL HCTYPE(ID, IT)

Action The histogram type is returned

Parameters

ID: integer - histogram identifier
IT: integer - histogram type

Size of Histogram

CALL HCSIZE(ID, ISIZE)

Action # bins of histogram is returned

Parameters

ID: integer - histogram identifier
ISIZE: integer - # X bins * # Y bins, where # Y bins = 1 if one dimensional

Existence of histogram

IEX = HCEXIS(ID)

Action Checks if histogram exists

Parameters

ID: integer - histogram identifier
IEX: integer - = 1 if histogram exists , = 0 otherwise

IDs and Types of existing Histograms

CALL HCIDAL(IDVECT, TPVECT, N)

Action Return identifiers, types and number of existing histograms

Parameters

IDVECT: integer array - array of IDs, dimension > # of existing histograms
TPVECT: integer array - array of TYPES
N: integer - # booked histograms

Remarks

arrays must be dimensioned to accomodate the maximum possible number of histograms

Histogram Statistics

CALL HC1GST(ID, RMEAN, RSIG, RMAX)

Action Extract statistics for a one-dimensional histogram

Parameters

ID: integer - histogram identifier
RMEAN: real - mean value
RSIG: real - root mean square (sigma)
RMAX: realmax. bin contents

Integrated Contents

RCON=HCCCNT(ID)

Action The integrated contents of a histogram is returned.

Parameters

ID: integer - histogram identifier
RCON: real - integrated contents returned by the function (not including under/overflow)

Maximum and Minimum Bin Contents

RCONMX=HCCMXC(ID)

Action The maximum bin contents of a histogram is returned.

Parameters

ID: integer - histogram identifier
RCONMX: real - maximum contents returned by the function (not including underflow/overflow bins)

RCONMN=HCCMNC(ID)

Action The minimum bin contents of a histogram is returned.

Parameters

ID: integer - histogram identifier
RCONMN: real - minimum contents returned by the function (not including underflow/overflow bins)

ERROR MESSAGES

OUTPUT UNIT FOR ERROR MESSAGES

CALL HCCLMS(LU)

Action Set logical unit for error messages output.

Parameters

LU: integer - logical unit

Special values

LU = 0 - suppress error messages output

Defaults NORD = 1 PDP = 5 VAX = 6

ERROR RETURN

IERR=HCCERR(ERR)

Action The value of the last error and the routine name are returned.

Parameters

IERR: integer - last error number
ERR: array - 3-word integer array in which the routine name is returned

Remarks

HCCERR is an integer function although the name does not follow the normal convention

ERROR CODES AND MEANINGS

111: reference to a non existing histogram
112: histogram already booked
114: illegal parameter (outside allowed bounds); in HCCINI NDIRLG; in H**BOO IMXCNT; in H**FIL ID and NHIST incompatible; Histogram pointer NHIST pointing to histogram area of different ID
116: Negative bin contents
216: title error ($ character is missing)
811: not enough space in HDIR or HDAT area
813: initialisation not done - see HCCINI

INTERNAL STRUCTURE

MEMORY

The HDIR labelled common is used to store the histogram directories. The OPTIONS AREA is used to store dynamic histogram options (maximum and minimum scale, ...). The histogram bins and bin overflows are stored in the HDAT labelled common.

In the common HDIR a working space is reserved by the package for internal parameters storage:

HDIR working space : 70 words

DIR LIST is the header of the created histograms list.

DEL LIST is the header of the deleted histograms list.

DIRECTORY FORMAT

One-dimension

Space requirements:

INTEGER directory: 12 words + TITLE length (in words)

REAL directory : 15 words + TITLE length (in words)

NOTES:

TYPE is the histogram directory type :
In case of REAL directory, the inverse of the bin width is stored.

Two-dimension

2 Space requirements:

INTEGER directory: 16 words + TITLE length (in words)

REAL directory : 22 words + TITLE length (in words)

NOTES:

TYPE is the histogram directory type :
in case of REAL directory, the inverse of the bin width is stored.

OPTION FORMAT

OVERFLOW AREA

Each time a bin contents overflows, two words are added to the overflow list of that histogram:

word 1 : bin number
word 2 : overflow value

The overflow value is incremented by one for each overflow of the concerned bin. The bin contents is then reset to zero.

DATA FORMAT

One-dimension

Space requirements:

N words if INB = 0 (N+(J-1))/J words if INB > 0 where N = # bins + 2 and J = word size/INB and INB = # bits per bin

Two-dimension

Space requirements:

N words if INB = 0 (N+(J-1))/J words if INB > 0 where N = # bins + 8 and J = word size/INB and INB = # bits per bin

COMPATIBILITY WITH HBOOK

        HMINI Routine   HBOOK Routine   Function          

	HI1BOO		HBOOK1		book
	HR1BOO		HBOOK1		book
	HI2BOO		HBOOK2		book
	HR2BOO		HBOOK2		book
	HI1FIL				single fill
	HR1FIL				single fill
	HI2FIL				single fill
	HR2FIL				single fill
	HI1AFI				array fill
	HR1AFI				array fill
	HI2AFI				array fill
	HR2AFI				array fill
	HI1PUT				single put
	HR1PUT				single put
	HI2PUT				single put
	HR2PUT				single put
	HICAPU		HPAK		array put
	HRCAPU		HPAK		array put
	HI1ADD		HFF1		single add
	HR1ADD		HFF1		single add
	HI2ADD		HFF2		single add
	HR2ADD		HFF2		single add
	HI1GET		HX		single get
	HR1GET		HX		single get
	HI2GET		HXY		single get
	HR2GET		HXY		single get
	HICAGE		HUNPAK		array get
	HRCAGE		HUNPAK		array get
	HI1GIN				graphic get
	HR1GIN				graphic get
	HI2GIN				graphic get
	HR2GIN				graphic get
	HC1PRI		HPHIST		print
	HC2PRI		HPSCAT		print
	HI1SPR				selective print
	HR1SPR				selective print
	HI2SPR				selective print
	HR2SPR				selective print
	HC1PLO		HPLOT		plot
	HC2PLO		HPLOT		plot
	HI1SPL				selective plot
	HR1SPL				selective plot
	HI2SPL				selective plot
	HR2SPL				selective plot
	HI1DIR		HGIVE		directory
	HR1DIR		HGIVE		directory
	HI2DIR		HGIVE		directory
	HR2DIR		HGIVE		directory
	HCCINI				initialisation
	HCCERR				error return
	HCCRST		HRESET		reset
	HCCDEL		HDELET		delete
	HCCGAR				garbage collection
	HCCCNT		HSUM		integrated contents
	HCCCUR				cursor position set
	HCCMXC		HMAX		maximum bin contents
	HCCMNC		HMIN		minimum bin contents
	HCCMAX		HMAXIM		scaling
	HCCMIN		HMINIM		scaling
	HC1LOG				logarithmic
	HC1LIN				linear
	HCCPAG		HPAGSZ		paper size
	HCCLPR		HOUTPU		print logical unit
	HCCLPL		HPLINT		plot logical unit
	HCCLMS				error messages logical unit
	HC2LEV				levels
	HCCGD3				plotting output device
	HC2DOT				number of dots
	HCCFRA				frame
	HC1RES		HBIGBI		output resolution
	HC2RES				output resolution

EXAMPLES AND TEST PROGRAMS

This chapter describes some example and test programs for HMINI with print and plot output.

Example with print output

A 1D integer and a 2D real histogram are booked.

The 1D histogram is filled with a spectrum representing a step function while the 2D histogram is filled, using a put routine, with a distribution corresponding to the function f(x, y) = x+y-1. The histograms are displayed in print format on the default print logical unit (6 on VAX, 1 on NORD). Space statistics and error messages appear on LUN 6.

PROGRAM TEST1 INTEGER HCCERR, ERR(3) COMMON/HDIR/IDIRBU(200) COMMON/HDAT/IDATBU(1200) C ALLOCATE SPACE FOR HISTOGRAMS CALL HCCINI(200,1200) IF(HCCERR(ERR).GT.0)GO TO 100 C NOTE THAT DEFAULT LOGICAL UNITS ARE USED C BOOK 1 DIMENSIONAL INTEGER HISTOGRAM WITH 100 BINS OF WIDTH 1 CALL HI1BOO(1,12HEXAMPLE ONE$,100,1,101,0) IF(HCCERR(ERR).GT.0)GO TO 100 C BOOK 2-DIMENSIONAL REAL HISTOGRAM WITH 20 X-BINS AND 50 Y-BINS CALL HR2BOO(2,12HEXAMPLE TWO$,20,1.0,21.0,50,0.0,50.0,0) IF(HCCERR(ERR).GT.0)GO TO 100 C SEE HOW MUCH SPACE LEFT CALL HCCSPA(RW, RD) WRITE(6,60)RW, RD 60 FORMAT(' NO. OF DIRECTORY, DATA WORDS LEFT',2F10.2) NHIST1=0 NHIST2=0 DO 10 I=1,100 IVAL=I DO 10 J=1, I C FILLING OF HISTOGRAM 1 CALL HI1FIL(1, NHIST1, IVAL) 10 CONTINUE DO 11 I=1,20 RI=FLOAT(I) DO 11 J=1,50 RJ=FLOAT(J-1) RCON=FLOAT(J+I) C FILLING OF HISTOGRAM 2 USING PUT ROUTINE CALL HR2PUT(2, RI, RJ, RCON) 11 CONTINUE C PRINTOUT OF HISTOGRAMS 1 AND 2 CALL HC1PRI(1) CALL HC2PRI(2) C CHANGE NO. OF LEVELS FOR GREATER RESOLUTION IN 2-D HISTOGRAM CALL HC2LEV(36) CALL HC2PRI(2) STOP 100 IERR=HCCERR(ERR) WRITE(6,50)IERR, ERR 50 FORMAT(' ERROR NUMBER ', I5,' IN ROUTINE ',3A2) END

Example with plot output

A 1D real histogram is booked and filled, using array fill, with a spectrum corresponding to a step function. A 2D integer histogram is booked and filled, using a real put routine, with a distribution representing the function f(x, y) = -4*X**2 - Y**2+400. The histograms are output in plot format, using small characters, on plot logical unit no. 6, which is assumed to be a Tektronix 4012.

User input for page control is on LUN 5 and possible error messages are written to LUN no. 6.

PROGRAM TEST2 INTEGER HCCERR, ERR(3) COMMON/HDIR/IDIR(200) COMMON/HDAT/IDAT(500) DIMENSION DVAL(1300) C INITIALISE HMINI CALL HCCINI(200,500) IF(HCCERR(ERR).GT.0)GO TO 100 C SET TERMINAL TYPE (T4012, SMALL CHAR'S ACTUALLY=DEFAULT !) CALL HCCGD3(4012,1, IDUM) IF(HCCERR(ERR).GT.0)GO TO 100 C SET PLOT UNIT CALL HCCLPL(6) C ONE-DIM REAL HISTOGRAM, 50 BINS , WIDTH 1 CALL HR1BOO(1,12HEXAMPLE ONE$,50,1.0,51.0,0) IF(HCCERR(ERR).GT.0)GO TO 100 C TWO-DIM INTEGER HISTOGRAM, 10 X BINS AND 20 Y-BINS CALL HI2BOO(2,12HEXAMPLE TWO$,10,-10,10,20,-20,20,0) IF(HCCERR(ERR).GT.0)GO TO 100 NHIST1=0 NHIST2=0 JJ=0 DO 10 I=1,50 RVAL=FLOAT(I) DO 10 J=1, I C DVAL CONTAINS N'TH BIN VALUE N TIMES JJ=JJ+1 DVAL(JJ)=RVAL+0.5 10 CONTINUE C FILL HISTOGRAM ONE USING ARRAY FILL CALL HR1AFI(1, NHIST1, DVAL, JJ) C FILL HISTOGRAM TWO USING PUT C DEFINE PARABOLOID WITH MAX 400 IN (X, Y)=(0,0) DO 11 I=-9,9,2 DO 11 J=-19,19,2 RCON = -4*I*I - J*J +400 C MAKE SURE RCON >0 !! IF(RCON.LT.0.5)RCON=0.5 CALL HI2PUT(2, I,J, RCON) 11 CONTINUE C NOW PLOT CALL HC1PLO(1) C SET CURSOR AT BOTTOM LEFT CORNER CALL HCCCUR WRITE(6,50) 50 FORMAT(' STEP FUNCTION, 1 CLEAR PAGE, THEN TYPE ANY NUMBER, RETURN TO CONTINUE'/) READ(5,*)IDUM CALL HC2PLO(2) CALL HCCCUR WRITE(6,60) 60 FORMAT(' PARABOLOID WITH MAX 400 IN (0,0), 1 CLEAR PAGE, THEN TYPE ANY NUMBER, RETURN TO CONTINUE'/) READ(5,*)IDUM C CHANGE MAX NO OF DOTS CALL HC2DOT(20) CALL HC2PLO(2) CALL HCCCUR WRITE(6,70) 70 FORMAT(' SAME WITH DOUBLE DOT DENSITY') STOP 100 IERR=HCCERR(ERR) WRITE(6,110)IERR, ERR 110 FORMAT(' ERROR NO ', I5,' IN ROUTINE ',3A2) END

Test programs

HMINI Test programs

In addition to the examples there exist two test programs. The TESTPRINT program calls almost all of the HMINI routines related to booking, filling and printing of histograms. The histograms are output in print format on the default print unit and each histogram has a short explanatory text that allows to check the correctness of the print output.

The TESTPLOT program produces a subset of the histograms in TESTPRINT and outputs these in Plot format. In addition graphics input is tested. Each histogram has one line of text which gives a reference to one of the histograms in TESTPRINT. In other words, the plots produced by TESTPLOT should be checked quantitatively by comparing to the printed histograms. INDEX HISTOGRAMMING CALLS INDEX

REFERENCES

R. Nierhaus
miniGD3, Introductory Guide for Users

This page was last updated on 16 December, 2013
Comments and requests for clarification may be sent to
E-mail:
Telephone:

The ATLAS Level-1 Calorimeter Trigger

HMINI Common Histogramming Library

Routine Calling Sequences

OPTION FORMAT