You have already used the HIST and HOUT commands.
We'll talk now about a few more options for those commands and then we'll
go on to talk about the most commonly used other histogram commands.
For all of these commands, the complete options list are available by
typing HELP from the IDA prompt.
HIST command you used before was:
Ida> HIST PHCHRG%(HLXPAR(2)) FROM 0 TO 10 ID 1 TITLE "HLXPAR(2)"If you do not provide an ID, the system assigns one, starting with 1. It is generally a good idea to assign the ID explicitly, since that way you know what ID to use to modify or display that particular histogram later.
The ID can an integer from 1 to 9999 or it can be a string of up to four characters. For example, the following histogram uses character ID:
Ida> HIST PHCHRG%(HLXPAR(2)) FROM 0 TO 10 ID "CHRG"By default, the histogram is made with 40 bins, You can use the
Step or Bins options to change this.
For example, to create a histogram with step size of 1
Ida> HIST PHCHRG%(HLXPAR(2)) FROM 0 TO 10 STEP 1 ID 1To create a histogram with 20 bins:
Ida> HIST PHCHRG%(HLXPAR(2)) FROM 0 TO 10 BINS 20 ID 1If the
REBIN option is included, the histogram is stored in
a way that allows you to rebin the histogram at later time.
This is particularly useful in cases where you do not know in advance
what values to expect for the histogram.
When you specify REBIN, IDA needs to store every data point
rather than just store the accumulated bin contents.
This means that REBIN can use up a large amount of memory.
For that reason, the default is to not allow REBIN.
Remake the PHCHRG histogram now with the rebin option and accumulate 200 events. We'll modify the histogram slightly to show transverse momentum rather than inverse transverse momentum.
Ida> VAR PT Ida> DEF EVANAL Ida> BANKLOOP PHCHRG Ida> PT = 1./ PHCHRG%(HLXPAR(2)) Ida> HIST PT FROM 0 TO 10 ID 1 TITLE "Transverse P" REBIN Ida> ENDLOOP Ida> ENDDEF Ida> REWIND Ida> GO 500Output the histogram using the original bin size.
Ida> HOUT 1 SDDXWDONote that some of the entries were lost out the right hand side of the histogram. They overflowed the maximum bin value of 10. Since the histogram was made with the
REBIN option,
you can now use the REBIN command to remake the plot.
Ida> REBIN 1 FROM 0 TO 100 Ida> HOUT 1 SDDXWDOThe highest transverse momentum should be roughly the full energy of one of the beams, 48 GeV (due to track finding errors, the highest actually came out slightly above this 48).
Rebin the histogram again to investigate the structure on the low end of the plot.
Ida> REBIN 1 FROM 0 TO 1 BINS 50 Ida> HOUT 1 SDDXWDO
SCAT command defines a scatter plot or a lego plot.
Here is an example that plots the transverse momentum versus the dip angle, tan(lambda).
Ida> DEF EVANAL Ida> BANKLOOP PHCHRG Ida> PT = 1./ PHCHRG%(HLXPAR(2)) Ida> SCAT PT FROM 0 TO 50 VS PHCHRG%(HLXPAR(3)) FROM -2 TO 2 ID 2 Ida> ENDLOOP Ida> ENDDEF Ida> REWIND Ida> GO 500 Ida> HOUT SDDXWDONote that in the above we left out the ID in the HOUT command. HOUT defaults to output the last histogram created.
If you add the "Mode of Storage" option, MS I*2 to the
SCAT command, you will get a lego plot rather than a scatter plot.
This "Mode of Storage" option tells IDA to store the data in a different way
that is appropriate for a lego plot.
Try the previous example now, but with the addition of this MS I*2
in the SCAT command.
Ida> DEF EVANAL Ida> BANKLOOP PHCHRG Ida> PT = 1./ PHCHRG%(HLXPAR(2)) Ida> SCAT PT FROM 0 TO 50 VS PHCHRG%(HLXPAR(3)) FROM -2 TO 2 MS I*2 ID 3 Ida> ENDLOOP Ida> ENDDEF Ida> REWIND Ida> GO 500 Ida> HOUT SDDXWDO
PLOT command makes another kind of two dimensional histogram.
It shows the mean of the values of one quantity in bins defined by another.
The error bars reflect the error in the average.
This is a sensitive way to study correlations that may not be apparent in
a scatterplot.
Lets look at the previous example, but now using PLOT.
Ida> DEF EVANAL Ida> BANKLOOP PHCHRG Ida> PT = 1./ PHCHRG%(HLXPAR(2)) Ida> PLOT PT VS PHCHRG%(HLXPAR(3)) FROM -2 TO 2 ID 4 Ida> ENDLOOP Ida> ENDDEF Ida> REWIND Ida> GO 500 Ida> HOUT SDDXWDO
HCAT.
Ida> HCATThe Plot, Under and Over columns show how many entries fell within the plot, underflowed the plot or overflowed the plot.
HCLR.
For example, to clear our last histogram:
Ida> HCLR 4Since the EVANAL that filled that histogram is still in place, we can refill the histogram by just running through some more events.
Ida> REWIND Ida> GO 500 Ida> HOUT 4 SDDXWDO
HOUT command has a number of other options.
If you omit the SDDXWDO at the end of the HOUT command,
the histogram will be written out in line printer mode.
This can be useful for checking exact bin contents. Try it now.
Ida> HOUT 1To output multiple histograms, you can list several IDs in one command:
Ida> HOUT 1 2 3To output all of the histograms:
Ida> HOUT ALLYou can place all four histograms into one window with:
Ida> HOUT ALL SDDXWDO QUADThe options can be in many different orders. For example, the following also works:
Ida> HOUT ALL QUAD SDDXWDOYou can specify a variety of different output devices other than SDDXWDO for hard copies. For example, to output a PostScript file suitable for printing on any PostScript printer:
Ida> HOUT 1 POSTSCRBe careful making hard copies of scatter plots. If the plot has a large number of entries, you should expect the output file to be very large and to take a long time to print.
To force IDA to show you its complete list of supported output devices, give it an HOUT command that it doesn't understand. It will think you have specified an output device it doesn't know, and it will respond by telling you what output devices it does know.
Ida> HOUT JUNKSee HELP HOUT from the IDA prompt for the full set of HOUT options.
HWRITE and HREAD
commands.
For example, write out your current set of four histograms.
Ida> HWRITE MYFOURNow quit IDA. IDA will have left a file in your current directory named MYFOUR.HCOM.
Restart IDA and confirm that you have no histograms defined:
Ida> HCATNow read in your stored histograms:
Ida> HREAD MYFOURYou should now be able to display the histograms, accumulate more entries into them, clear them, and so forth. You will no longer be able to REBIN any of the histograms that were written out and read back in (the extra data needed by REBIN is omitted from the HCOM file that is written to disk).
FIT command.
This performs a least squares fit using the program VARPRO from the
NAPL program library.
The other fitter is a more complex fitting package that uses the Minuit
fitting package developed at CERN. We will discuss how to use the Minuit
package in the next section of the Workbook, when we discuss
command processors.
Run the following procedure to create a simple Gaussian distribution
that we can use for a test of the FIT command.
At its heart, this procedure uses a function called RAN
which generates a random number between zero and one.
The HIST statement itself calls the procedure GAUSS
which in turn calls RAN.
The GTEST 1000 calls the procedure GTEST with
a value of 1000 for the argument ITER.
Ida> DEF GAUSS Ida> GAUSS = -6 Ida> DO I = 1 TO 12 Ida> GAUSS = GAUSS+RAN Ida> ENDDO Ida> ENDDEF Ida> DEF GTEST(ITER) Ida> DO I = 1 TO ITER Ida> HIST GAUSS FROM -4 TO 10 STEP .25 ID 5 TITLE "Simple Gaussian" Ida> ENDDO Ida> ENDDEF Ida> GTEST 1000HOUT the histogram. You will see that it is roughly a Gaussian. To make it more smooth, you just need to accumulate more entries into the histogram. To do this, run the
GTEST procedure some more.
Ida> GTEST 5000You should now have a fairly smooth Gaussian with 6000 entries.
To fit a Gaussian with the FIT function, you first need to
supply an initial guess at the mean and sigma.
Plug these values into the IDA variable ALPHA.
This is one of IDA's system variables that you will see in the directory
if you issue the command DIR/SYS.
Let's try values of mean .1 and sigma .6.
Ida> ALPHA .1 .6Then call FIT.
Ida> FIT 5If you now output the histogram, you will see results of the fit overlayed on the plot.
For more details on the fitter, use HELP FIT.
The Handypak manual describes many histogram control options
that you can control with the DOPT and HOPTN commands.
IDA supports the DOPT and HOPTN commands, but refers you to the
Handypak manual for most of the details.
Reading and Writing Jazelle Data Files
You have already used some commands to read Jazelle data from disk or tape
and to write Jazelle data to tape.
The commands you used were OPENTAPE READ,
OPENTAPE WRITE and WRITE USING INLIST.
You will now learn some additional features of reading and writing Jazelle
data.
OPEN READ command
instead of the OPENTAPE READ command.
For OPENTAPE, you had to supply a nickname for the data that
could be found in some datacat.
For OPEN, you must supply the real file name.
No datacats are checked.
This means that you can read a file even if there is no datacat entry
for that file.
But remember, the OPEN command can not read tape files,
it can only read disk files.
For example, if you look in the file PRODDATACAT:NEWUSERS.DATACAT, you will see that the nickname REC94_MDST points to the file
DISK$SLD_FAC0:[SLDWWW.WORKBOOK]REC94V11_MDSTYou can open this file using the
OPENTAPE command:
Ida> OPENTAPE READ REC94_MDST STAGE WAITOr you can open this file using the
OPEN command:
Ida> OPEN READ DISK$SLD_FAC0:[SLDWWW.WORKBOOK]REC94V11_MDSTIf the NEWUSERS.DATACAT did not exist, only the second method would work.
OPEN WRITE rather than OPENTAPE WRITE.
For example, to write the current event to a file called MYEVENT.JAZZDATA
on your current directory:
Ida> OPEN WRITE MYEVENT Ida> WRITE USING INLISTAs you can see, the only difference between writing to tape and to disk is that in one case you use
OPENTAPE WRITE and in the other
case you use OPEN WRITE.
The USING part of the WRITE command is where you
specify what contexts are to be written out.
WRITE USING INLIST tells IDA that you want to write out
all of the contexts that were originally read in (the group of contexts
read in forms the INLIST).
To write out some other subset of contexts, you first use the
SEGLIST command to create your own list of contexts.
Such a list is called a "segment list" or "seglist."
You then put the name of this seglist into your WRITE command.
For example, suppose the data you are currently reading is raw data and you want to write out only the data from the S120 context. You could create a seglist called MYLIST that just contains the S120 context as follows:
Ida> SEGLIST CREATE MYSLIST S120You could then write only the S120 data as follows:
Ida> WRITE USING MYSLISTIf you wanted to write out both the RAWDATA and S120 context, you could create a seglist that contains both of these contexts:
Ida> SEGLIST CREATE MYSLIST2 RAWDATA S120Sometimes, the list of families that you want to write out does not fall neatly into the existing context groupings. To get around this, you can create your own groupings using the
JLIST command.
Such a grouping is called a "Jazelle list."
It behaves like a sort of temporary new context.
You can then use this Jazelle list in place of a context name in the
SEGLIST command.
For example, suppose you have just read in some raw data and you want to write out only the banks that contain the barrel drift chamber hit information, the DBRAW banks.
If you just did the following, you would write out the entire RAWDATA context:
Ida> SEGLIST CREATE MYSLIST RAWDATA Ida> WRITE USING MYSLISTInstead, first create a Jazelle list that contains only the DBRAW family:
Ida> JLIST CREATE MYJLIST DBRAWYou then feed this Jazelle list to the
SEGLIST command:
Ida> SEGLIST CREATE MYSLIST @MYJLIST Ida> WRITE USING MYSLISTThe
@ sign before MYJLIST tells SEGLIST
that this is not a real context but is instead a temporary "made up" context,
a Jazelle list.
Don't worry too much about understanding these details about
WRITE.
The important thing for now is just that you know that you do not always have
to write out the whole event. You can specify any particular set of contexts
or any particular set of families.
Another command that uses segment lists is the WIPE command.
This command deletes all of the banks in all of the families in all of
the contexts in a given segment list.
For example, the following would delete all of the raw data:
Ida> SEGLIST CREATE MYSLIST RAWDATA Ida> WIPE USING MYSLIST
OPENTAPE command or one OPEN command).
But IDA allows you to have multiple input files open at a time.
This tends to come up in special circumstances such as when one wants
to try to associate 120 Hz beam monitoring data from one tape with DST
data from another tape taken during the same time period.
When you have multiple input files open, IDA needs some way to tell
which file you want to read at which moment.
The OPEN commands therefore accept an additional argument,
AS.
For example, you could open two different tapes as follows:
Ida> OPENTAPE READ HAD30320 AS INFILE STAGE WAIT Ida> OPENTAPE READ 12030320 AS IN120 STAGE WAITThe first input file has been named
INFILE;
the second input file has been named IN120.
The name INFILE is actually special. Whatever file has been opened with that
name is the one that will have one event read each time you GO 1.
If you omit the AS option, the default file name is
INFILE. That is why in all of the simple examples you did not
need to include the AS option.
To read from any file other than INFILE,
you use the READ command.
For example, to read one record from our IN120 file:
Ida> READ IN120So, to open the two files and set up an EVANAL that would read one record from each of the two files, you could just:
Ida> OPENTAPE READ HAD30320 STAGE WAIT Ida> OPENTAPE READ 12030320 AS IN120 STAGE WAIT Ida> DEF EVANAL Ida> READ IN120 Ida> ENDDEFThe first file gets the default name of
INFILE.
And INFILE gets read automatically with every GO 1,
so you only need the explicit READ for the IN120 file.
Before the first time you call a particular PREPMORT or C routine from IDA,
you must issue the command EXTERNAL followed by the name of
that routine.
This command tells IDA the name of the routine that you will be calling
and tells IDA how many arguments this routine takes.
For example, the PREPMORT routine UCHKTAG can be used to
check various things about how the beam crossing number changes from
one event to the next.
This beam crossing number, also referred to as the "tag,"
should be a unique number for every time the SLC beams cross, normally
120 times per second.
The beam crossing number starts at zero at the beginning of each calendar year and increments 120 times a second. By the end of the year it is a very large integer, but has not rolled over. Hence within a run (which always lasts less than a year) all events should have unique beam crossing numbers.
If two events ever appear with the same beam crossing number, it means that the event has been split or duplicated in the process or reading out the electronics. This is rare but does occasionally occur. The UCHKTAG routine has been used to study this issue.
UCHKTAG gets its information by checking a bank called
MA_BEL which is only present in raw data, not in DST data.
Before you can run the UCHKTAG example,
you will need to open some raw data, go to the first event
and declare some variables.
Ida> CLOSE INFILE Ida> OPEN READ DISK$SLD_FAC0:[SLDWWW.WORKBOOK]NURAW94 Ida> GO 1 Ida> VAR DELTAG,DUPLICAT,SPLIT
UCHKTAG expects four arguments.
To prepare to call it, issue the EXTERNAL command as follows:
Ida> EXTERNAL UCHKTAG 4
UCHKTAG will now be available to call from IDA.
This particular routine expects to be called the first time with a
one as the first argument (to tell it to initialize).
After that, each time you call the routine it will return information on
how the event compares with the event that was there the previous time
you called UCHKTAG.
The following code will call UCHKTAG once to initialize it
and will then call it again for each event and type the output.
Ida> CALL UCHKTAG 1. DELTAG DUPLICAT SPLIT Ida> DEF EVANAL Ida> CALL UCHKTAG 0. DELTAG DUPLICAT SPLIT Ida> TYPE DELTAG DUPLICAT SPLIT Ida> ENDDEF Ida> GO 4You should get the results:
%IDA-I-GOSTART Start GO for 0 records
12.68 0.0000E+00 0.0000E+00
127.2 0.0000E+00 0.0000E+00
17.59 0.0000E+00 0.0000E+00
4.392 0.0000E+00 0.0000E+00
The first column is the difference in the beam crossing number converted to
seconds (120 per second).
The second column is zero unless the two events are duplicates.
The third column is zero unless the two events represent a single event
that has been accidentally split.
One more note on calling PREPMORT or C routines from IDA. We told you earlier that all IDA variables are REAL*4. But the variables in some of the PREPMORT or C routines that you call may be integers.
To pass an IDA variable to a routine as an integer,
instead of just the IDA variable pass INT(variable).
For example, the routine VXIDLSC expects an integer as its
first argument. It can be handled as follows:
Ida> CALL VXIDLSC(INT(CCDID),LAYER,SECTOR,CCDNUM)
HELP at the IDA prompt.
Finally, you can do what most users do: find some other IDA code that
looks about right and modify it to your needs.
But beware, they may be using a much more complicated method then is
actually necessary (since they probably stole their code from somebody else
who stole their code form somebody else).
The next section of this workbook describes a powerful set of external routines that you can call from IDA to do much of your analysis work. They are called "Processors" and "Command Processors." Read on.