Histogramming Functions

Function	Purpose
`hid = histo(name,nx,xmin,xmax`	create histogram with name `name`,
`[,xtitle,ytitle])`	`nx` channels between `xmin` and `xmax`. return histogram id `hid` [optional axis titles]
`hid = histo(name,other_hid)`	create histogram with name by copying histo with id `other_hid`
`hid = hrebin(name,other_hid,nx)`	create histogram with name as a rebinned version (`nx` bins) of `other_hid`
`hfill(hid,x[,incr])`	increment histogram `hid` at value `x` by 1 [ or `incr`]
`hfillarea(hid,x1,x2,value)`	distribute `value` evenly in the x-range from x1 to x2
`cont = hpoke(hid,bin,val)`	set contents of channel number `bin` to `val` for histogram `hid`. returns previous contents
`cont = hpokeErr(hid,bin,val)`	set error of channel number `bin` to `val` for histogram `hid`. returns previous error
`cont = hpeek(hid,bin)`	return current contents of channel `bin` for histogram `hid`
`cont = hpeekErr(hid,bin)`	return current error of channel `bin` for histogram `hid`
`val=hintegral2d(hid[,x1,x2][,err])`	calculates integral [over specified range of x values], [and stores the associated error in `err[0]`, i.e. err must be dim'ed as an array]
`hdump(hid)`	print contents of histogram `hid` to stdout
`hclear(hid)`	set all channels of histogram `hid` to zero
`hid = histo2d(name,nx,xmin,xmax,`	create 2-dimensional histogram with name,
`ny,ymin,ymax`	and nx(ny) bins in the horizontal (vertical
`[,xtitle,ytitle])`	direction covering the range xmin-xmax (ymin-ymax) [optional axis titles]
`hid = histo2d(name,other_hid)`	create 2d-histogram with name by copying histo with id `other_hid`
`hid = hrebin2d(name,other_hid,nx,ny`	create histogram with name as a rebinned
`[,xmin,xmax,ymin,ymax])`	version (`nx` and `ny` bins) of `other_hid`, if desired only in a bin range specified by `xmin`, `xmax`, `ymin`, and `ymax`. Returns histogram identifier `hid`
`hfill2d(hid, x, y[, incr])`	increment histogram `hid` at value (`x`,`y`) by 1 [ or `incr`]
`cont = hpoke2d(hid,binx,biny,val)`	set contents of channel number (`binx` , `biny`) to val and return previous contents
`err = hpokeErr2d(hid,binx,biny,val)`	set error of specified channel and return old value
`hpeek2d(hid, binx, biny)`	return current contents of channel (`binx`, `biny`) for 2-dimensional histogram `hid`
`hpeekErr2d(hid, binx, biny)`	return current error of given channel
`val=hintegral2d(hid[,x1,x2,y1,y2]`	calculates integral [if desired only over
`[,err])`	specified range of x and y values], [and stores the associated error in `err[0]`, i.e. err must be dim'ed as an array ]
`hdump2d(hid)`	print contents of 2-dimensional histogram `hid` to stdout
`hclear2d(hid)`	set all channels of 2-dimensional histogram `hid` to zero

Function	Purpose
`value=hstat(hid,"dim")`	returns dimension of histogram
`value=hstat(hid,"id")`	returns HBOOK id of histogram
`value=hstat(hid,"binx")`	returns number of bins in x
`value=hstat(hid,"minx")`	returns upper limit in x
`value=hstat(hid,"maxx")`	returns lower limit in x
`value=hstat(hid,"binwidthx")`	returns width of bin in x
`value=hstat(hid,"biny")`	returns number of bins in y (0 for 1-dim)
`value=hstat(hid,"miny")`	returns upper limit in y (0 for 1-dim)
`value=hstat(hid,"maxy")`	returns lower limit in y (0 for 1-dim)
`value=hstat(hid,"binwidthy")`	returns width of bin in y
`value=hstat(hid,"maximum")`	returns maximum
`value=hstat(hid,"minimum")`	returns minimum
`value=hstat(hid,"overx")`	returns number of overflows in x
`value=hstat(hid,"underx")`	returns number of underflows in x
`value=hstat(hid,"overy")`	returns number of overflows in y
`value=hstat(hid,"undery")`	returns number of underflows in t
`value=hstat(hid,"error")`	returns 1 if errors are booked, else 0
`value=hstat(hid,"meanContents"`	returns (weighted) mean of the histogram
`[,x1,x2[,y1,y2]][,"var"])`	contents, x1(y1) and x2(y2) allow to specify a bin range in x(y), if a variable name is given in "var" the error of the mean is stored in this variable
`value=hstat(hid,"mean"[,x1,x2])`	returns the mean value of the 1-dim histogram [for bins x1-x2].
`value=hstat(hid,"rms",[,x1,x2])`	returns the root mean square value of the 1-dim histogram [for bins x1-x2].
`hname(hid[,1])`	returns pointer to histogram name (can only be used as an argument, e.g. to sprintf(...)., if 1 is specified as the second argument the task name is stripped off
`hmanip("add",hid1,hid2)`	performs `hid1 = hid1 + hid2`
`hmanip("sub",hid1,hid2)`	performs `hid1 = hid1 - hid2`
`hmanip("mul",hid1,hid2)`	performs `hid1 = hid1 * hid2`
`hmanip("div",hid1,hid2)`	performs `hid1 = hid1 / hid2`
`hmanip("addConst",hid,value[,error])`	performs `hid = hid + value`, if error is given, error propagation is done
`hmanip("subConst",hid,value[,error])`	performs `hid = hid - value`
`hmanip("mulConst",hid,value[,error])`	performs `hid = hid * value`
`hmanip("divConst",hid,value[,error])`	performs `hid = hid / value`
`hmanip("mulRows",hid1_2d,hid2_1d)`	performs `hid1_2d(i,j) *= hid2_1d(j)`
`hmanip("divRows",hid1_2d,hid2_1d)`	performs `hid1_2d(i,j) /= hid2_1d(j)`
`hmanip("mulCols",hid1_2d,hid2_1d)`	performs `hid1_2d(i,j) *= hid2_1d(i)`
`hmanip("divCols",hid1_2d,hid2_1d)`	performs `hid1_2d(i,j) *= hid2_1d(i)`
`hmanip("asymmetry",hid1,hid2,hid3)`	performs `hid1=(hid2-hid3)/(hid2+hid3)`
`hmanip("sqrt",hid)`	performs `hid = sqrt(hid)`
`hmanip("inverse",hid)`	performs `hid = 1/hid`
`hmanip("poisson",hid)`	calculate error of bin as sqrt of bin contents
`hmanip("xtitle", histoid, "Title")`	set title for x-axis in YODAs display
`hmanip("ytitle", histoid, "Title")`	set title for y-axis in YODAs display
`hdelete(hid)`	deletes histogram from memory

Function	Purpose
`hid_1d=hmean("new_name",hid_2d,`	creates 1d-Histogram with name hid_1d
`"meanX"[,y1,y2])`	"new_name" containing the mean and rms (as contents and error) of vertical slices of 2d-Histogram hid_2d. If y1 and y2 are given the mean and rms is calculated for this bin range
`hid_1d=hmean("new_name",hid_2d,`	the same but for horizontal
`"meanY"[,y1,y2] )`	slices
`hid_1d=hmean("new_name",hid_2d,`	here the root mean square of vertical slices
`"rmsX"[,x1,x2] )`	is stored as the histogram contents of hid_1d.
`hid_1d=hmean("new_name",hid_2d,`	the same but for horizontal
`"rmsY"[,y1,y2] )`	slices
`update()`	transfer current contents of all histograms to shared memory (for the displaying program) explicitly. Periodic update can be
	stopped with `set_updatetimer 0` in
	YODA's terminal window
`write_histos(filename [, format])`	writes all histograms of all tasks to file named `filename` in format HBOOK (0) or YZ (1)
`clearhistos()`	clears all histograms of all tasks.
Read Histograms by name:
`file = hfile("filename"[, 1])`	open HBOOK file [strip taskname from histogram names]
`hclose(file)`	close HBOOK file
`n = hlist(file)`	list contents, returns number of histos
`hid = hrin(file,dim,"name"`	read histo of dimension dim from file (use dim > 2 for pseudo N-dim. histograms
`[,"new_name"])`	[and change name]
`n=hrinall(file,vector,dim[,"ext"])`	read at most dim histos, ids will be in vector, returns number histos read. If `ext` is given, histogram names will be "taskname.ext.name-in-file"
Read Histograms by ID:
`hid = hread("file",id[,"name"])`	read histogram of any dimension [ and change name]
`hid1d = hread1d("file",id[,"name"])`	read only 1d histograms
`hid2d = hread2d("file",id[,"name"])`	read only 2d histograms
`hid2d = hreadNd("file",id[,"name"])`	read only pseudo N-dimensional histograms
projections and slices:
`hid1d=hprox(name,hid2d,ybin1,ybin2)`	creates 1-dimensional histogram `hid1d` as a slice of the 2-dimensional histogram `hid2d` using bins `ybin1` to `ybin2` in y. If `ybin2` is ommitted only one bin is used. If both `ybin1` and `ybin2` are not given, all bins in y are used for the projection.
`hid1d=hproy(name,hid2d,ybin1,ybin2)`	creates 1-dimensional histogram `hid1d` as a slice of the 2-dimensional histogram `hid2d` using bins `xbin1` to `xbin2` in x. If `xbin2` is ommitted only one bin is used. If both `xbin1` and `xbin2` are not given, all bins in x are used for the projection.

The histogramming functions are summarized in Table 5.5. Histograms are created with calls to either histo(...) or histo2d(...) for one- or two-dimensional histograms, respectively. These calls return a handle to the created histogram which must be used to refer to the object when filling, clearing etc. This handle is used just inside the current task context and has nothing to do with e.g. PAW's histogram identifiers.

The usual way of using histograms is by means of filling via calls to hfill or hfill2d, respectively. However, you can also ''abuse'' the histograms for producing x/y plots, where one quantity is simply plotted against another. Simply use hpoke(h, bin, y); for entering a point at (bin,y). It is important to remember to use the x-coordinate in units of bins (indexing with floats will not give the desired results). Once all desired channels are filled, the information can automatically be transferred to the display program with the update(); call. This causes the current contents of the histograms to be transferred to paw (To make this work correctly, you should switch off the automatic (periodic) update done by YODA by default. To do so, enter set_updatetimer 0 in YODA's terminal window. Periodic update can be restored with set_updatetimer VALUE, where VALUE is the time between refresh cycles in milliseconds). The histogram can then be cleared with hclear(h);. The corresponding calls for two-dimensional histograms are available as well and work just in the same manner.

Histograms can also be read from and written to file in either HBOOK or YODAs native YZ format (see table 5.5).

The histogramming functions set a variable ERRNO, to test if the last command was successful (ERRNO == 0) or not (ERRNO > 0). See table 5.5 for an explanation of the error codes.