.;
.;This document has been prepared for use with Bonner Lab Runoff
.;	J. Clement, Bonner Lab
.;
.;QA Cern__library
.;The Cern library is available.  It is broken up into 3 pieces:
.;.i5;sys$userlib:KERNLIB
.;.i5;sys$userlib:GENLIB
.;.i5;sys$userlib:PACKLIB
.;.p
.;There will be a complete set of ducumentation available after
.;it has all been received, and bound.  It will be announced when available.
.qb HBOOK
This is a set of subroutines for defining and filling histograms.
.br;Library: PACKLIB,KERNLIB
.br;The average time to fill is about 420 microsec per call to HFILL
or 180 microsec for HF1,HF2 see benchmarks.
.qc Fundamentals
.list 0
.le;You must set up blank common in your FORTRAN program.
see topic: Commons.
.le;You must call HLIMIT to declare the common size.
.le;You probably should CALL HBINSZ('YES')
.x Subroutine>HBINSZ
.le;To define a 1-dimensional histogram call HBOOK1
.le;To define a 2-dimensional histogram or scatter plot
call HBOOK2
.le;The histogram is incremented by HFILL.
.le;The results can finally be printed by HPRINT
.le;A histogram may be reset or zeroed by HRESET.
.le;The command to link your fortran program should look like:
.i5;_$ LINK program,sys_$userlib:packlib/lib-
.i5; ,sys_$userlib:kernlib
.els 1
A variety of commands are available to control the output format of the
histograms, but for quick plots they are not necessary.
.qc Benchmarks
A series of benchmarks were taken on a VAX-11/750 with histograms
incremented randomly.  The runs were made for 20 1-d, 20 2-d or 10 of each.
The times/fill are given below in microseconds for
various routines.
.nf
.lm+5
.ts R,20,R,+10,R,+10,R,+10
	HFILL	HF1,2	HFF1,2
1-d hist	340	140	43
both 1,2-d	420	183	77
2-d hist	470	240	125
.lm.f
.qc list__of__routines
.TS +20,+10,+10
.define command /qs/.lm.lm+12
.define command /Qi/.i-12;
.LM+20
.DEFINE COMMAND /qiA/.I-20;
.c-10;^&Initialization\&
.qiA HTITLE(Title)	Defines a general title
.qiA HBOOK1(...)	Defines 1 dimensional histogram
.qiA HBOOK2(...)	Defines 2 dimensional histogram
.qiA HTABLE(...)	Defines 2 dimensional table
.qiA HBPRO(ID',Limit)	Defines projections 2 dimensional hist.
.qiA HBPROX(ID',Limit)	Defines projections 2 dimensional hist. onto X
.qiA HBPROY(ID',Limit)	Defines projections 2 dimensional hist. onto Y
.qiA HBANDX(ID',ymin,ymax,Limit)	Defines a projection onto X restricted by Y
.qiA HBANDY(ID',xmin,xmax,Limit)	Defines a projection onto Y restricted by X
.qiA HBSLIX(ID,nslice,Limit)	Defines a slice projected onto X
.qiA HBSLIY(ID,nslice,Limit)	Defines a slice projected onto Y
.c-10;^&Filling a histogram\&
.qiA HFILL(ID,x,y,weight)	Fills or increments a histogram or table
.qiA HF1(ID,x,weight)	Fast filling of 1 dimensional hist.
.qiA HF2(ID,x,y,weight)	Fast filling of 2 dimensional hist.
.qiA HFF1(ID,iad,x,weight)	Very Fast filling of 1 dimensional hist.
.qiA HFF2(ID,iad,x,y,weight)	Very Fast filling of 2 dimensional hist.
.qiA HPAK(ID,contents)	Fill a histogram from an array
.qiA HPAKE(ID,errors)	Sets histogram errors from an array.
.c-10;^&Select options\&
.qiA HBINSZ(switch)	Enable or disable rounded bin sizes
.qiA HBSTAT(ID')	Enables more accurate statistics
.qiA HBARX(ID')	Enables statistical error computation and output
.qiA HBARY(ID')	Enables statistical error computation and output
.qiA HLOK(ID')	Enables histogram filling
.qiA HUNLOK(ID')	Disables histogram filling
.c-10;^&Output\&
.qiA HINDEX	Print index of histograms
.qiA HISTDO	Prints all histograms
.qiA HPRINT(ID')	Prints selected histograms
.qiA HNEWS(version) Print news about HBOOK
.c-10;^&Selective output\&
.qia HPHIST(ID',choice,norder)	Outputs 1-din hist on line printer
.qia HPROT(ID',choice,norder)	Outputs for presentation down page
.qia HPSCAT(ID')	Outputs 2-dim hist as scatter plot
.qia HPHS(ID')	Same as HPRINT but ignore tables and HROTAT
.qia HPHST(ID')	Same as HPRINT but ignore HROTAT
.qia HPTAB(ID',iformat)	Output 2-dim hist as a table
.c-10;^&Output options\&
.qiA HPRHIS(ID',switch)	Print histogram shape Def=N
.qiA HPRCHA(ID',switch)	Print Channel numbers Def=N
.qiA HPRCON(ID',switch)	Print channel contents Def=N
.qiA HPRERR(ID',switch)	Print errors in each chan Def=Y
.qiA HPRFUN(ID',switch)	Print superimposed function Def=Y
.qiA HINTEG(ID',switch)	Print integrated contents Def=Y
.qia HPRLOW(ID',switch) Print lower limits Def=N
.qiA HPRSTA(ID',switch)	Print statistical info. Def=N
.qia HOUTPU(Lun)	Set logical unit of output file
.qia HERMES(Lun)	Set logical unit of messages
.c-10;^&Printer Graphics options\&
.qiA HBLACK(ID')	Fills in blank space under hists.
.qiA HSTAR(ID')	Prints only asterisk for each chan instead of contents
.qiA HPCHAR(IOPT,char)	Select printing character for hist.
.qiA HERROR(ID')	Select error bars for hist
.qiA HBIGBI(ID,NCOL)	1 dim. hist. ID is printed 2ith 1 chan. over NCOL
.c-10;^&Page control\&
.qiA HSQUEZ(switch)	New page each plot Def=Y
.qiA HPAGSZ(Iline,Icolumn)	Set page size
.qiA H2PAGE(ID')	2 Page hist for improved resolution
.qiA HROTAT(ID')	Print down the page
.c-10;^&Scale definition\&
.qiA HLOGAR(ID)	Contents are logarithmically scaled
.qiA HMINIM(ID',Amin)	Contents maximum scale
.qiA HMAXIM(ID',Amax)	Contents maximum scale
.qiA H1EVL(ID')	Step of vertical scale is integer
.qiA HCOMPA(IDvect,N)	Specified hists. have same vertical scale
.qiA HNORMA(ID',factor)	Normaizes hist when printed
.qiA HSCALE(ID',factor)	Multiply contents scale by factor
.c-10;^&Copy and Delete\&
.qiA HCOPY(ID1,ID2,Title)	Copies 1 histogram to another
.qiA HRESET(ID',Title)	Resets or zeroes a histogram
.qiA HDELET(ID')	Deletes a histogram
.c-10;^&Functions\&
.qiA HBFUN1(...)	Defines a 1 dim. hist and fills it with an external function
.qiA HBFUN2(...)	Defines a 2 dim. hist and fills it with an external function
.qiA HFUNC(ID,FUN)	Declares a function to be superimposed onto the
histogram 
.c-10;^&Memory management\&
.qia HISTGO(Ikeep)	Moves origin of HBOOK mem. to IKEEP+1
.qia HLIMIT(Nwords)	Declares the size of blank common
.qia HDISKF(Lun,Nhists)	Defines the unit,size for hists. on disk.
.qia HARRAY(ID,Nwords,Iaddr)	Reserves an array
.c-10;^&Getting Histogram Information\&
.qia Logical=HEXIST(ID)	.YES. if ID exists
.x Subroutine>HEXIST
.qia HID1(IDVECT,N)	The number and IDs of all 1-dim hists
.qia HID2(IDVECT,N)	The number and IDs of all 2-dim hists
.qia HIDALL(IDVECT,N)	Gives the number and IDs of all hists
.qia HNOENT(ID,NOENT)	The number of entried
.qia HUNPAK(ID,CONTENTS,choice,Islice)	Contents of hist.
.qia Var=HI(ID,I)	Contents of channel I
.x Subroutine>HI
.qia Var=HIJ(ID,I,J)	Contents of channel J
.x Subroutine>HIJ
.qia Var=HX(ID,X)	Contents of bin X
.x Subroutine>HX
.qia Var=HX(ID,X,Y)	Contents of bin X,Y
.x Subroutine>HX
.qia Var=HIE(ID,I)	Error for chan I
.x Subroutine>HIE
.qia Var=HXE(ID,X)	Error for bin X
.x Subroutine>HXE
.qia Var=HIF(ID,I)	Value of stored function
.x Subroutine>HIF
.qia HXI(ID,X,I)	Channel corresponding to X
.qia HXYI(ID,X,Y,I,J)	Channels corresponding to X,Y
.qia HIX(ID,I,X)	X corresponding to I
.qia HIJXY(ID,I,J,X,Y)	X,Y corresponding to I,J
.qia Var=HMAX(ID)	Maximum X for hist
.x Subroutine>HMAX
.qia Var=HMIN(ID)	Minimum X for hist
.x Subroutine>HMIN
.qia Var=HSUM(ID)	Integrated contents
.x Subroutine>HSUM
.qia HLOCAT(ID,ifirst)	Address of first word of hist
.qia HGIVE(....)	Returns parameters and address
.qia var=HSTATI(ID,icase,choice,num)	Returns stat. info.
.x Subroutine>HSTATI
.qia HDUMP(ID)	Prints a dump of commons
.c-10;^&Arithmetic + fitting\&
.qia HOPERA(ID1,op,ID2,ID3,C1,C2)	Add subtract, mult., divide hists
.qia HFIT(...)	Fit a function to hist.
.qia HDERI1(ID,params,derivs)	Return to HFIT parameters
.qia HDERI2(ID,x,y,params,derivs)	Return to HFIT derivitives
.qia HFITEX(ID,AA,BB,chi2,IC,sig)	Fits an exponential
.qia HFITGA(ID,C,av,SD,chi2,IC,sig)	Fits a gaussian
.qia HFITPO(ID,NP,A,chi2,ic,sig)	Fits a polynomial
.qia HSMOOF(ID,icase,chi2)	Smooths 1-d hists.
.qia HSPLI1(ID,ic,n,k,chi2)	B-spline Smooths 1-d hists.
.qia HSPLI2(ID,nx,ny,kx,ky)	B-spline Smooths 2-d hists.
.qia HSPFUN(ID,x,n,k)	Returns value of B-spline
.c-10;^&Random number generation\&
R=HRNDM1(ID,dummy)	Random number dist by contents of 1-d hist.
.x Subroutine>HRNDM1
CALL HRNDM2(ID,RX,RY)	Random numbers distributed according to 2-d hist.
.x Subroutine>HRNDM2
.c-10;^&Saving and restoring\&
.qia HSTORE(ID,Lun)	Store a hist in file on logical unit LUN.
.qia HFETCH(ID,Lun)	Fetch first hist from file.
.qia HFNEXT(ID,Lun)	Fetch next hist.
.qia HMSAVE(LUN)	Save the entire HBOOK common.
.qia HMSET(LUN)	Inverse of HMSAVE
.qia HWRITE(...)	Store hist in machine independent form.
.qia HREAD(...)	Reverse of HWRITE
.qc parameters
.ts +10,+10,+10,+10,+10
Parameters inside brakets [] are optional and may be omitted.
.P
.qs
.qi ID	=#Histogram identification.
.qi ID'	=#Ident. - Zero applies to all existing histograms.
.qi FUN(x)	=#External function.  This must be declared REAL#EXTERNAL#FUN
.qi Title	=#text to be used as a title. (see text)
.qi X	=#Value to histogram along ordinate
(may be specified as an integer)
.qi Y	=#Value to histogram along abscissa
(may be specified as an integer)
.qi Weight	=#Weight to add per chan.  (1.0 if omitted)
(may be specified as an integer)
If not 1 word/chan weight is truncated to nearest integer.
.qi Limit	=#Upper limit of single channel content (if missing 1 
word/chan.)  For maximum efficiency do not specify.
.qi Switch	=#'YES' or 'NO' - This enables or disables the function in
question.
.qc text
Text is entered as either a literal, or as an array containing
text.  The text may be terminated by a dollar sign "_$".
.i5;For example defining a histogram with title, the following are equivalent:
.i10;CHARACTER*9 IC
.i10;data	IC/'Histogram'/
.i10;CALL HBOOK1(1,IC)
.x Subroutine>HBOOK1
.i10;CALL HBOOK1(1,'Histogram')
.x Subroutine>HBOOK1
.i10;CALL HBOOK1(1,'Histogram$')
.x Subroutine>HBOOK1
.qc Commons
.i10;COMMON Memory(size)
.p
Memory must be set aside in blank common for HBOOK to allocate.
Once the memory is full, added histograms will be stored on disk.
This will make histogramming much less efficient.
.p
You should call HLIMIT to declare the common size.
.qc efficiency
.p
For maximum efficiency.
.lis 0
.le;Avoid packing more than 1 channel per word.
.le;Use HF1 and HF2 for filling.
.le;Do not have histograms stored on mass storage.
.els 0
The following timings were obtained on a VAX-11/750
All histograms were memory resident, and the times are per call
to the routine in question.
.s.nf
routine =_>	^&HFILL	HF1	HF2\&
1-dim hist	.65ms	.29ms
2-dim hist	.96ms		.44ms
.s.i5;For comparison the RICE hist package took .11ms all hists.
.i5;HANDYPAK used around .29ms
.f
.qc HBANDX
CALL HBANDX(ID',ymin,ymax,[Limit])
.x Subroutine>HBANDX
Defines a histogram as a projections onto the X axis, restricted
to the specified Y limits.
.qc HBANDX
CALL HBANDY(ID',xmin,xmax,[Limit])
.x Subroutine>HBANDY
Defines a histogram as a projections onto the Y axis, restricted
to the specified X limits.
.qc HBFUN1
CALL HBFUN1(ID,title,Nx,xmin,xmax,FUN)
.x Subroutine>HBFUN1
.p
.qs
.qi ID	=#Unique histogram identifier
.qi Title	=#Histogram title (if missing none)
.qi Channels	=#Number of channels (100 if missing)
.qi Xmin	=#Minimum X value (if missing auto calculation)
.qi Xmax	=#Maximum X value (if Xmin >= Xmax auto calculation)
.qi Limit	=#Upper limit of single channel content
.QI FUN(x)	=#External function of 1 variable.
.qc HBFUN2
CALL HBFUN2(ID,title,Nx,xmin,xmax,Ny,ymin,ymax,FUN)
.x Subroutine>HBFUN2
.p
.qs
.qi ID	=#Unique histogram identifier
.qi Title	=#Histogram title (if missing none)
.qi Nx	=#Number of channels along x (100 if missing)
.qi Xmin	=#Minimum X value (if missing auto calculation)
.qi Xmax	=#Maximum X value (if Xmin >= Xmax auto calculation)
.qi Ny	=#Number of channels along y (100 if missing)
.qi Ymin	=#Minimum Y value (if missing auto calculation)
.qi Ymax	=#Maximum Y value (if Ymin >= Ymax auto calculation)
.qi Limit	=#Upper limit of single channel content
.QI FUN(x,Y)	=#External function of 2 variables.
.p
FUN(x,y) is an external function of 2 variables.
.qc HBIGBI
CALL HBIGBI(ID,NCOL)
.x Subroutine>HBIGBI
.p
The 1-dim. histogram is printed with one channel over NCOL columns.
.qs
.qi NCOL	=#Column number.  If missing or zero the full page is used.
.qc HBINSZ
CALL HBINSZ(Switch)
.x Subroutine>HBINSZ
.p
This controls bin size rounding for all histograms. If enabled the bins are
rounded to a "decent" value.  A decent value is: 
.i5;1., 1.5, 2., 2.5, 4., 5.
.i10;Times a power of 10.
.qs.qi Switch	=#'YES' or 'NO'

.qc HBLACK
CALL HBLACK(ID)
.x Subroutine>HBLACK
.p
All 1-dim histograms and projections are printed by filling all character
positions up the the maximum with X.  The upper character is 1 to 9 or X
corresponding to 1/10 to 10/10
.qc HBOOK1
CALL HBOOK1(ID,[Title],[Nx],[Xmin],[Xmax],[Limit])
.x Subroutine>HBOOK1
.p
This defines a 1 dimensional histogram.
.qs
.qi ID	=#Unique histogram identifier.  If ID has already been defined
the old one is deleted.
.qi Title	=#Histogram title (if missing none)
.qi Nx	=#Number of channels (100 if missing)
.qi Xmin	=#Minimum X value (if 0 or missing auto calculation)
.qi Xmax	=#Maximum X value (if Xmin >= Xmax auto calculation)
.qi Limit	=#Upper limit of single channel content (if missing 1 
word/chan.)  For maximum efficiency do not specify.
If auto channel calculation is selected, storage is automatically 1 word/chan.
.QC HBOOK2
CALL HBOOK2(ID,Title,Nx,Xmin,Xmax,Ny,Ymin,Ymax,[Limit])
.x Subroutine>HBOOK2
.p
This defines a 2 dimensional histogram.
No automatic limit calculations are possible.
.qs
.qi ID	=#Unique histogram identifier
If ID has already been defined the old one is deleted.
.qi Title	=#Histogram title (if missing none)
.qi Nx	=#Number of channels along x
.qi Xmin	=#Minimum X value
.qi Xmax	=#Maximum X value
.qi Ny	=#Number of channels along y
.qi Ymin	=#Minimum Y value
.qi Ymax	=#Maximum Y value
.qI Limit	= missing, allocates 5 bits/channel
.qc HBPRO__
CALL HBPRO(ID,[Limit])
.x Subroutine>HBPRO
.p
Defines projections of a scatter plot or table as two 1 dim. hists.
If the histogram has not already been defined by HBOOK2 or HTABLE this
does nothing.
.qc HBPROX
CALL HBPROX(ID',[Limit])
.x Subroutine>HBPROX
.p
Defines projections of a scatter plot or table onto the X axis.
If the histogram has not already been defined by HBOOK2 or HTABLE this
does nothing.
.qc HBPROX
CALL HBPROX(ID',[Limit])
.x Subroutine>HBPROX
.p
Defines projections of a scatter plot or table onto the Y axis.
If the histogram has not already been defined by HBOOK2 or HTABLE this
does nothing.
.qc HBSLIX
CALL HBSLIX(ID,nslice,[Limit])
.x Subroutine>HBSLIX
.p
This defines a histogram as nslice 1 dimensional histograms 
projected on the X axis restriced along the Y axis.
.qs
.qi ID	=#Identifier of an existing 2 dim. hist or table.
.qi Nslice	=#The number of slices
.qc HBSLIY
CALL HBSLIY(ID,nslice,[Limit])
.x Subroutine>HBSLIY
.p
This defines a histogram as nslice 1 dimensional histograms 
projected on the Y axis restricted along the X axis.
.qs
.qi ID	=#Identifier of an existing 2 dim. hist or table.
.qi Nslice	=#The number of slices
.qc HBSTAT
CALL HBSTAT(ID')
.x Subroutine>HBSTAT
.p
Accurate statistics will be calculated when a histogram is filled.
This produces accurate final statistics at the expense of speed.
The following are calulated.
.qc HFILL
CALL HFILL(ID,X,[Y],[Weight])
.x Subroutine>HFILL
.p
Fills a histogram, or table.  For maximum efficiency use HF1 or HF2
.qs
.qi X	=#Value of abscissa
.qi Y	=#Value of ordinate
.qi Weight	=#Weight to add per chan.  (1.0 if omitted)
If not 1 word/chan weight is truncated to nearest integer.
Negative weight gives meaningless results.
.qc HFIT__
CALL HFIT(ID,FUN,NP,pi,IC,ST,PMI,PMA)
.x Subroutine>HFIT
.p
Fits an arbitrary function to a histogram.
.qs
Input parameters:
.qi FUN(x1,x2...xnp)	=#The function to fit (must be external)
.qi NP	=#The number of parameter of FUN
.qi P(NP)	=#Initial values of params
.qi ST(NP)	=#Initial step sizes
.qi IC	=+L*1000000+F*100000+B*10000+D*1000+W*100+P*10+S
.qi	##W=1 weights=1, 0 statistical errors
.qi	##L=0 linear dependence, 1 otherwise
.qi	##F=0 ID is normal hist, >0 fit non equidistant F-dim data points
.qi	##B=0 save memory, B=1 save time
.qi	##D=0 numerical calc of deriv, 1 analytic calc of deriv (HDERI1/2)
.qi	##P=0 no itermediate print, 
1 print final iter, >1 prints iterations N*(P-1)
.qi	##S=1 (no), 2 (default) superimpose function on hist.
.x Subroutine>1 
.qi PMI(NP)	=#Lower parameter bounds
.qi PMI(NP)	=#Upper parameter bounds
.br;Output parameters:
.qi P	=#Final values of paremeters
.qi CHI2	=#Chisquared of fit
.qi SIG(NP)	=#Standard deviations of parameters
.qi COV(NPAR*(NPAR+1)/2)	=#Covariance matrix
.qc HFITEX
CALL HFITEX(ID,AA,BB,CHI2,IC,SIG)
.x Subroutine>HFITEX
.p
Fits an exponential to histogram.
.c;E(x)=EXP(AA + BB*x)
.x Subroutine>EXP
.qs
Input parameters:
.qi IC	=#Control word, see HFIT
.br
Output parameters:
.qi AA,BB	= Coefficients.
.qi CHI2	=#Chi-squared
.qi SIG(2)	=#Standard deviations of AA,BB
.qc HFITGA
CALL HFITGA(ID,C,AV,SD,CHI2,IC,SIG)
.x Subroutine>HFITGA
.br
Fits a gaussian to hist ID.
.c;G(x)=C*EXP(-0.5*((x-AV)/SD)**2)
.qs
Input parameters:
.qi IC	=#Control word, see HFIT
.br
Output parameters:
.qi C,AV,SD	= Coefficient, Average, Standard deviation
.qi CHI2	=#Chi-squared
.qi SIG(3)	=#Standard deviations of C,AV,SD
.qc HFITPO
CALL HFITPO(ID,NP,A,CHI2,IC,SIG)
.x Subroutine>HFITPO
.s;Fits a polynomial to the histogram.
.c;P(x)=A(1)+A(2)*x+....A(NP)*x**(NP-1)
.qs
Input parameters:
.qi NP	=#Number of coefficients (order+1)
.qi IC	=#Control word, see HFIT
.br
Output parameters:
.qi A(NP)	= Coefficients.
.qi CHI2	=#Chi-squared
.qi SIG(NP)	=#Standard deviations of A

.qc HF1
CALL HF1(ID,X,[Weight])
.x Subroutine>HF1
.p
This is fast filling for 1 dimensional hists.  
.list 0
.le;Same as HFILL, but can not be mixed with HFILL.
.le;HLOK is ignored
.le;HBARX is ignored
.le;HBSTAT is ignored
.le;Inefficient if on mass storage.
.els 0
.qc HF2
CALL HF2(ID,X,[Weight])
.x Subroutine>HF2
.p
This is fast filling for 2 dimensional hists.  
.list 0
.le;Same as HFILL, but can not be mixed with HFILL.
.le;HLOK is ignored
.le;Projections, bands, slices not filled.
.le;Inefficient if on mass storage.
.els 0
.qc HFUNC
CALL HFUNC(ID',FUN)
.x Subroutine>HFUNC
.p
.qs
ID	=#Histogram ID, 0 means all hists
FUN	=#an external function (declared external) which is superimposed on
the histogram, and optionally printed.  FUN can not contain any calls to HBOOK
subroutines.
.qc HGIVE
CALL HGIVE(ID,title,NX,xmin,xmax,NY,ymin,ymax,limit,IAD)
.x Subroutine>HGIVE
.p
This routine returns information about a histogram.
.qs
.qi Title	=#Histogram title (must be long enough vector)
.qi Nx	=#Number of channels along x
.qi Xmin	=#Minimum X value
.qi Xmax	=#Maximum X value
.qi Ny	=#Number of channels along y (1-dim if zero)
.qi Ymin	=#Minimum Y value
.qi Ymax	=#Maximum Y value
.qI Ntitle	= number of machine words for title
.qi IAD	=#Address of ID int the address table
.qc HISTDO
Outputs all histograms to line printer.
.qc HLIMIT
CALL HLIMIT(Nwords)
.x Subroutine>HLIMIT
.p
This sets the limit on the number of words in blank common. Where blank
common has been defined:
.i5;COMMON Memory(Nwords)
.p
If this is not done, it is possible for HBOOK to overflow the common, and
cause fatal errors.
.qc HLOK
CALL HLOK(ID')	Forbids histogram filling
.x Subroutine>HLOK
.br;CALL HUNLOK(ID')	Permits histogram filling
.x Subroutine>HUNLOK
.qc HNEWS
CALL HNEWS(VERS)
.x Subroutine>HNEWS
.P
Prints on HBOOK output file all modification for the specified version.
VERS = 0 lists all mods since version 3.00.
If VERS=3.5 then all mods on 3.5 are listed.
.qc HOPERA
CALL HOPERA(ID1,operation,ID2,ID3,c1,c2)
.x Subroutine>HOPERA
.s
ID3(n) = C1*ID1(n) (oper) C2*ID2(n)
.s
operation = 1H+ 1H- 1H* 1H/
.s
.list 0
.le;ID1,2,3 must all have the same number of channels.
.le;If ID3 does not exist it is created to be same as ID1
.le;Division by zero gives an error
.le;Histograms with different scales may give meaningless results.
.le;If ID1,ID2 have option HBARX set, ID1 and ID2 are assumed uncorrelated.
.els 0
.qc HPCHAR
CALL HPCHAR(IOPT,ICHA)
.x Subroutine>HPCHAR
Selects printing char. for histograms that are not drawn contour only, or for
functions.
.qs
.qi IOPT	=#'BLAC' - applies to HBLACK
.qi	=#'FUNC' - applies to functions
.qi	=#'STAR' - applies to HSTAR
.qi ICHA	=#Chosen character (see text)
.qc HPRINT
CALL HPRINT(ID')
.x Subroutine>HPRINT
.p
Prints the specified histogram(s).
.qc HSMOOF
CALL HSMOOF(ID,[ICASE],[CHI2])
.x Subroutine>HSMOOF
.p
Smooths histogram according to algorithm in:
.lm+5;J. H. Friedman, Data Analysis Techniques for High Energy Particle
Physics, proc. of 1974 CERN school of computing, (CERN 74-23)
.qs
.qi ICASE	=#1 replace original by smoothed version (default)
.qi	=#2 superimpose as a function
.qi CHI2	=#Chi-square
.qc HSPFUN
CALL HSPFUN(ID,X,N,K)
.x Subroutine>HSPFUN
.p
Returns restult of 1-dim B-spline.
.qc HSPLI1
S = HSPLI1(ID,[IC],[N],[K],[CHI2])
.x Subroutine>HSPLI1
.qs
.qi X	=#abscissa
.qi N,K	=#Knots, degree same as in HSPL1
.p
B-spline smoothing of 1-dim hist.
.qs
.qi ICASE	=#1 replace original by smoothed version (default)
.qi	=#2 superimpose as a function
.qi N	=#Number of knots (default=3)
.qi K	=#Degree of spline (default=13)
.qi CHI2	=#Resulting chis-quare
.qc HSPLI2
CALL HSPLI2(ID,[NX],[NY],[KX],[KY])
.x Subroutine>HSPLI2
.p
Smooth 2-dim hist by B-spline
.qs
.qi Nx	=#Number of knots in x interval (default=3)
.qi Ny	=#Number of knots in y interval (default=3)
.qi Kx	=#Degree of spline in x interval (default=13)
.qi Ky	=#Degree of spline in y interval (default=13)
.qc HSTAR
CALL HSTAR(ID')
.x Subroutine>HSTAR
.p
For existing 1-dim. hists and projections only an asterisk is printed
at the ordinate corresponding to the contents of the channel.
.qc HSTATI
Var = HSTATI(ID,icase,choice,num)
.x Subroutine>HSTATI
.p
This is a real function that returns statistical information.
.qs
.qi ICASE	=#1 - return mean value
.qi	=#2 Standard deviation
.qi	=#3 Skewness
.qi	=#4 Kurtosis
.qi	=#5 Number of equivalent events
.qi Choice	=#Hollerith variable to pick subhist. (irrelevant for 1-dim)
.qi	=#HIST The scatter plot (default)
.qi	=#PROX - X projection
.qi	=#PROY - Y projection
.qi	=#SLIX - X slice
.qi	=#SLIY - Y slice
.qi	=#BANX - X band
.qi	=#BANY - Y band
.qi Num	=#Order of slice or band (default=1)
.lm
.br;E(X) = sum(weight(i)*X(i))/sum(weight(i))
.x Subroutine>sum
.br;Mom(n) = E((X-E(x))**n)
.br;Mean = E(x)
.br;std = SQRT(Mom(2))
.x Subroutine>SQRT
.br;skewness = Mom(3) / (Mom(2))**3/2
.x Subroutine>Mom
.br;kurtosis = (Mom(4) / Mom(2)**2) - 3
.br;Number of equiv events = Sum(weight(i)**2) / Sum(weight(i)**2)
.x Subroutine>Sum
.c;Example
STD = HSTAT(25,2,'SLIX',5)
.x Subroutine>HSTAT
.qc HTABL
CALL HTABLE(ID,Title,Nx,Xmin,Xmax,Ny,Ymin,Ymax,[Limit])
.x Subroutine>HTABLE
.p
This allocates a 2 dimensional table.
No automatic limit calculations are possible.
.qs
.qi ID	=#Unique histogram identifier
.qi Title	=#Histogram title (if missing none)
.qi Nx	=#Number of channels along x
.qi Xmin	=#Minimum X value
.qi Xmax	=#Maximum X value
.qi Ny	=#Number of channels along y
.qi Ymin	=#Minimum Y value
.qi Ymax	=#Maximum Y value
.qI Limit	= missing, allocates 10 bits/channel
The number of cols used to write results = ALOG10(Limit)+2.
.x Subroutine>ALOG10
.qc HUNPAK
CALL HUNPAK(ID,CONTENTS,[Choice],[Islice])
.x Subroutine>HUNPAK
.p
This transferrs the contents of a histogram or selected projections
into an array CONTENTS
.qs
.qi CONTENTS	=#Array to receive the data.  It must be large enough to
contain the data.
.qi Choice	=#Hollerith variable to pick subhist. (irrelevant for 1-dim)
.qi	=#HIST The scatter plot (default)
.qi	=#PROX - X projection
.qi	=#PROY - Y projection
.qi	=#SLIX - X slice
.qi	=#SLIY - Y slice
.qi	=#BANX - X band
.qi	=#BANY - Y band
.qi Islice	=#Order of slice or band (default=1)
.lm
.c;Example
CALL HUNPAK(25,ARRAY,'SLIX',5)
.x Subroutine>HUNPAK
.qc errors
.ts +5,+8,+8
.lm +8
.i-8;111	non existant ID
.i-8;112	ID already exists
.i-8;113	ID=0 is illegal
.i-8;114	illegal parameter
.i-8;115	reference to non-existant slice or band
.i-8;211	negative number of chans.
.i-8;214	X or Y upper limit smaller than lower limit
.i-8;215	bin packing incompatible with automatic limits-1 word/bin selected
.i-8;311	non-positive parameter in HISTGO
.i-8;321	illegal option for 1-dim.
.i-8;322	illegal option for 2-dim.
.i-8;325	try to find a non existing option
.i-8;541	comparison of hists with different specs.
.i-8;542	Zero is illegal normalization factor
.i-8;543	Bad scale factor
.i-8;711	operation on hists with different specs.
.i-8;721	degree of polynomial non positive
.i-8;722	no of channels smaller than degree of polynomial
.i-8;723	infinite error estimated, min. terminated
.i-8;724	no further minimization possible, terminated
.i-8;725	iteration limit exceeded, terminated
.i-8;726	hist is empty
.i-8;727	undefined initial param.
.i-8;731	hist empty, or integral negative or zero, assume uniform dist.
.i-8;732	packing incompatible with random number generation
.i-8;810	not enough records in virutal memory
.i-8;811	not enough space in memory
.i-8;812	call HLIMIT before HDISKF
.i-8;900	HPLOT errors
.qc internals
If IAD = address of the histogram.
.i5;IB(IAD)##=ID
.i5;IB(IAD+1)=Address of hist
.i5;IB(IAD+2)=Number of words in hist
.i5;IB(IAD+3)=status word
.qc author
.nf
This package was written by:
.lm +5
R. Brun
I. Ivanchenko
P. Palazzi
.s.lm
This documentation was prepared from:
.lm +5
Cern long write up
Y 250 - December 1979
.lm +5
The Program Librarian
Data Handling Division
CERN
CH 1211 Geneva 23
Switzerland
.s.lm
This document was prepared by:
.lm +5
John Clement
Rice University
PO Box 1892
Houston, Texas, 77251
July 1985