Workbook for SLD Offline Users - Writing Code: Making Histograms from Prepmort

As you found out when you learned how to make histograms from IDA, SLD uses a histogramming package called Handypak. To make histograms directly from Prepmort, you just write your Prepmort to make direct calls to Handypak routines.

Users familiar with HBOOK will find Handypak calls not too different. You basically make one call to "book" a histogram (that is, to define the histogram) and then make subsequent calls to accumulate data into the histogram.

We will show you a simple example of making a histogram from Prepmort, then we will show you some other Handypak routines that you can call from Prepmort, and finally we will give you a few special warnings about how to write your calls so that they will work correctly on the Alpha.

When you want to do complicated things with Handypak, you will need to refer to a copy of the real Handypak manual. The manual is available from SLAC Publications as SLAC Report 234. The title is "Handypak, a Histogram and Display Package" by Adam Boyarski. Look for Release 6.5 or later, revised in September 1988. You can probably do simple calls without the manual just by studying other people's code in DUCS. But the manual is extremely well written and lists more features than we can cover in this Workbook.

A Simple Example of Making a Histogram from Prepmort

The following piece of code defines a one dimensional histogram and a two dimensional histogram. It then accumulates some data into them.

  "&COMMON /JAZELL/"

   POINTER F_PHCHRG --> PHCHRG,
           P_PHCHRG --> PHCHRG;

   INTEGER JZBLOC;

   REAL*4 PT;

   LOGICAL FIRST / .TRUE. /;

   IF FIRST
   [
     $CALL JZBLOC( 'PHCHRG', F_PHCHRG ) ERROR RETURN;
     FIRST = .FALSE.;
     CALL HDEF1(101,'R*4',40,0.,10.,' Transverse Momentum (PT)@');
     CALL HDEF2(102,'R*4',40,40.,0.,-2.,50.,2.,' PT versus Tan(lambda)@');
   ] 

   BANKLOOP F_PHCHRG, P_PHCHRG
   [
     PT = 1./ P_PHCHRG%(HLXPAR(2));
     CALL HCUM1(101,PT,1.0);
     CALL HCUM2(102,PT,P_PHCHRG%(HLXPAR(3)),1.0);
   ]

In the section on using Jazelle from Prepmort, you already saw most of what is in this piece of code. An IF FIRST... block is used to do some initial setup, then a BANKLOOP is used to loop over all of the PHCHRG banks in the current event.

The only new things to learn are the CALL HDEF lines and the CALL HCUM lines. The 1 or 2 in HDEF1, HDEF2, HCUM1 and HCUM2 refer to whether the histogram is 1 dimensional or 2 dimensional.

The arguments of HDEF1 are as follows:

101 was our histogram ID. It can be either a four digit integer or a four character string. If it is a string, it should be enclosed in quote marks, for example CALL HCUM1('XV02'....
'R*4' was our "mode of storage." It depends on what kind of variable you are going to histogram.
- Use 'R*4' for REAL*4 variables.
- Use 'I*4' for INTEGER*4 variables.
For other "mode of storage" choices, see the Handypak manual.
40 was our number of bins
0. was the lower limit
10. was the upper limit
Transverse Momentum (PT) was the title.
Notice that the last character in the title string is @. This character is not actually part of the title but is used by Handypak to find the length of the string. It must be included or the title will come out wrong.

The arguments of HDEF2 are the same as for HDEF1 except that:

after you specify the number of bins for the horizontal axis, you specify the number of bins for the vertical axis,
after you specify the number of lower limit for the horizontal axis, you specify the lower limit for the vertical axis,
after you specify the number of upper limit for the horizontal axis, you specify the upper limit for the vertical axis,

The arguments of HCUM1 are as follows:

101 was our histogram ID. It needs to match the one that was in our HDEF1.
PT was the variable to accumulate into the histogram.
1.0 was the weighting factor to use for this accumulation. In our example, we weight all entries the same. But you have the option of varying the weighting factor from one entry to another.

The arguments of HCUM2 are the same as for HCUM1 except that after you specify the variable for the horizontal axis, you specify the variable for the vertical axis.

If you were to include the above example into a piece of your Prepmort and then call this Prepmort from IDA, you would have two new histograms, numbered 101 and 102, that you could HOUT. The next section of this Workbook will teach you how to compile your Prepmort and call it from IDA. But first we will mention a few more important points about Handypak and a few more Handypak routines that you might want to call from Prepmort.

Setting Mode of Storage

Match Mode of Storage to Data Type

The main thing to remember about choosing your "Mode of Storage" in Handypak is that it should match the type of variable that you are accumulating into the histogram.

If you are accumulating Real numbers, use a Real mode of storage. If you are accumulating Integers, use an Integer mode of storage.

If necessary, you can use the Fortran functions INT and FLOAT to convert the variable accordingly.

For example, if histogram number 35 is using 'R*4' mode of storage and the variable ADC is an integer, you could have:

     CALL HCUM1(35,FLOAT(ADC),1.0);

Getting Scatterplots

For two dimensional histograms, you can also add a fourth character, S, at the end of the mode of storage. This turns on the scatterplot storage feature.

For example, you could have:

   CALL HDEF2('VEDS','I*4S',101,100,0.,0.,.01,.2,'E Vs S-C in VXSMRD@');

The reason Handypak has you set this as part of the mode of storage is that, to create a scatterplot, Handypak needs to store every point's exact coordinates while, to create any other kind of plot, Handypak just needs to store accumulated sums.

Character Strings in Handypak Calls: the %REF Construction

Because Handypak was initially written before there were character strings in Fortran, it is sometimes necessary to take special care in how you send it character strings.

When you call any Handypak routines from Prepmort except for the HDEF and HCUM routines, you need to send character strings a special way.

Enclose the character strings in the construction %REF( ... ).

For example:

     CALL HOUT(101,%REF('POSTSCR'));

The string we are sending is 'POSTSCR', the way we send it to Handypak is %REF('POSTSCR').

The reason that the first two Handypak calls you learned, HDEF and HCUM, do not require this construction is that the Prepmort pre-compiler adds this for you. This was done just for those two routines because for many users those are the only Handypak routines they call.

You will see a lot of code in DUCS that does not contain this %REF structure. It is code that was written before we began using Alphas. The VAX computers allowed us to leave out the %REF. But this was not standard Fortran and the Alphas do not allow it.

You should put the %REF structure around all Handypak calls other than calls to HDEF1, HDEF2, HCUM1 and HCUM2. Your Handypak calls will then work on both the Alpha and the VAX.

CALL HOUT:To Output a Histogram

The histograms that you create from Prepmort can be outputted using the IDA HOUT command that you learned in the Workbook section: IDA Continued. But you also have the option of doing the output from Prepmort. To do this, you call the Handypak routine HOUT.

For example, to output the two histograms that we created above,

     CALL HOUT(101,%REF('POSTSCR'));
     CALL HOUT(102,%REF('POSTSCR'));

This would output the histograms to a PostScript file. Note again the %REF(...) structure required around character strings.

You can select from the same set of output devices that you can use from IDA.

If the histogram ID was specified as a character string, use the character string in the HOUT call.

For example:

     CALL HOUT(%REF('XV02'),%REF('POSTSCR'));

CALL DPWDOW: to Make HOUT Place More than One Histogram on a Page

When you learned how to output histograms from IDA, you saw that you could place more than one histogram on a single page by adding options to the IDA HOUT command such as QUAD and HEX.

To get the same effect from Prepmort, you have to call a different routine before you CALL HOUT. You must first call the Handypak routine DPWDOW.

For example, to set up output for six histograms per page, with two in the horizontal direction and three in the vertical direction,

     CALL DPWDOW(1,2,3,1);

the first argument is either 1 to turn on the special windowing feature or 0 to turn off the special windowing feature.
the second argument is the number of histograms to place in the horizontal direction.
the third argument is the number of histograms to place in the vertical direction.
the last argument is the window position to use for the next histogram to be drawn. In our case, we specified that the next histogram will be drawn in the first window position (the top left). All subsequent calls to HOUT will increment this window position.

CALL HOPTC or DOPTC:To Set Histogram Options

Many other histogram options can be controlled by calls to the Handypak routines HOPTC and DOPTC.

Calls to HOPTC affect how information is accumulated into a histogram. In general, HOPTC is called soon after a histogram is defined.
Calls to DOPTC affect how histograms are displayed. So HOPTC can be called any time before the histogram is outputted.

There is some overlap between what is done by HOPTC and what is done by DOPTC. Study the Handypak manual for details.

Watch out. The version of HOPTC that you call from Prepmort is not exactly the same as the version described in the Handypak manual. All of the available options are the same, but the arguements are in a different order. The version you call from Prepmort has the histogram ID first, not last.

HOPTC Example

Here is an example of how HOPTC could be used.

" This line in the declarations section of the Prepmort routine "
     REAL SCALES(8)/0.,1.,5.,4.,10.,2.,4.,0./;

" These lines later, in the executable section of the Prepmort routine "

     CALL HDEF2(102,'R*4',40,40.,0.,-2.,50.,2.,' PT versus Tan(lambda)@');
     CALL HOPTC('ALL ','STAT',.TRUE.);
     CALL HOPTC('ALL ','SOUT',.TRUE.);
     CALL HOPTC('ALL ','HMSCAL',SCALES);

The option ALL is used here in place of a specific histogram ID.

The first two HOPTC calls cause Handypak to do a more accurate accumulation of statistics information for all histograms. It accumulates statistical information at every HCUM. The default, which is to have these options set FALSE, uses only the final bin contents sums for its statistics.

The last HOPTC call turns on manual scales. The default is to have the scales set automatically.

The manuals scales are set to the values specified in the Real array SCALES.

element 1, in our case 0., sets the XMIN
element 2, in our case 1., sets the X Tic size
element 3, in our case 5., sets the X number of Tics
element 4, in our case 4., sets the X number of sub-tics
element 5, in our case 10., sets the YMIN
element 6, in our case 2., sets the Y Tic size
element 7, in our case 4., sets the Y number of Tics
element 8, in our case 0., sets the Y number of sub-tics

Again, see the Handypak manual for details on setting scales. And keep in mind that when you call HOPTC from Prepmort, you need to place the histogram ID argument first, not last.

DOPTC Example

Here is an example of how DOPTC would be used:

     CALL DOPTC ('MARKER',3) ;
     CALL DOPTC ('ERROR',0) ;
     CALL DOPTC ('LINE',1) ;

The first DOPTC call sets the mark style to be mark number 3, a diamond shape (instead of the default maker which is a *).
The second DOPTC call turns off the error bars (instead of the default which is to show symmetric error bars).
The third DOPTC call makes lines be drawn between the plot points (instead of the default which is to just draw the points).

Many other options are listed in the Handypak manual.

Older Forms of HOPTC and DOPTC

In code that was written for SLD before the Alpha computers became available, you will find calls to older forms of the options setting routines.

HOPTN is an older form of the HOPTC. Use HOPTC in all of your new code.
DOPT is an older form of the DOPTC. Use DOPTC in all of your new code.

These older forms of the routines do not work as well as the new forms for passing character strings between Prepmort and Handypak. They make assumptions that work for the VAX, but which do not work for the Alpha.

The Handypak Manual Tells More

Look in the Handypak Manual for other Handypak routines that you can call, or for additional options that you can use with the Handypak routines mentioned above. You can also learn about them by looking at how they are called by other Prepmort code in DUCS, but be aware that many of the routines in DUCS that call Handypak were written before the Alphas came into use and may not have been updated since then. You may need to include additional %REF structures to make these calls work on the Alpha.

Back to Writing Code

Joseph Perl
1 March 1995