= HOWTO: Histograms in 1 and 2 Dimensions =

In order to ease plotting histograms, the modules "hist.f90" and "hist2D.f90" provide routines prepared for this issue. The routines are a little bit more involved in order to allow simultanously for calculating different 'stuff', as e.g. 'averages per bin'. They also automatically report the number of entries per bin, report over- and underflow of the considered x-region etc.


== 1 dimensional histograms ==

The three steps for using 1 dimensional arrays are:

 * You initialize a histogram by 
   {{{
   call CreateHist(H, HName,x1,x2,bin)
   }}}
   Here "'''H'''" is the variable to store the Histogram in, "'''HName'''" a name to use at write-out time and "'''x1'''","'''x2'''" and "'''bin'''" are the minimal and maximal x-values and the bin width.

 * You add an entry to the histogram by
   {{{
   call AddHist(H, x,y)
   }}}
   This adds in histogram "'''H'''" the value "'''y'''" to the bin where "'''x'''" corresponds to.[[BR]][[BR]]
   Alternatevily you can use
   {{{
   call AddHist(H, x,y, y2)
   }}}
   where you are internally filling two histograms at the same time. (Why the hell you ever would like to do such: see below!)

 * At the end, you write out the histogram by
   {{{
   call WriteHist(H,iFile,add,mul,DoAve,maxVal,H2,file,dump)
   }}}
   Here "'''H'''" and "'''iFile'''" are the only obligatory parameters (the histogram and the number of the file to write it), the other parameters are optional. (It has shown up to be a good idea to give optional arguments always in the form "''optarg=optarg_value''", since you then do not have to take care of the correct ordering.)[[BR]][[BR]]
   The sum of all entries per bin are automatically divided by the bin width, in order to get the correct scaling. In addition, you may specify "'''add'''" and/or "'''mul'''" to get some additional scaling: instead of "Y", the printed output is "'add'+Y*'mul'". [I like to call it with "add=1e-20" when creating log-plots in order to avoid problems while ploting "0" in a log-plot (KG)][[BR]][[BR]]
   The parameter "'''!DoAve'''" is 'logical' and indicates, whether we want to print also "per bin averages": If this feature is selected, then also on a per-bin-basis we write the value of "sum(y2-entries)/sum(y-entries)", which can be interpreted as "<y2>(x)", while the normal output is "dN/dx" and "dN2/dx". (Argument "'''maxval'''" is the value, which is printed, if there are no entries in a specific bin.)[[BR]][[BR]]
   You can give a second histogram via parameter "'''H2'''", then all output is divided bin-by-bin by the entries of this second histogrmm.[[BR]][[BR]]
   If you give a string as argument for "'''file'''", the the output routines opens the file with the given name "file" for output as stream "iFile", does the output and closes stream "iFile" afterwards again.[[BR]][[BR]]
   The last optional (logical) parameter "'''dump'''" indicates, whether you want in addition to the ASCII output also some binary dump of all the information stored. This may be helpful, if you want to read in the information again by some additional Fortran program to further manipulate the output, e.g. increasing the statistics by averaging over 10 runs with different random seeds.[[BR]][[BR]]
In addition to the output given in columns, the output routine writes a header providing some general information, as e.g. over- and underflow. 

== 2 dimensional histograms ==

The basic idea was to have the same syntax as for the 1D-case by just replacing x -> (/x1,x2/). You may take all the given description of the 1D histograms here to the 2D histograms by taking into account this replacement.

The output routine was named as "!WriteHist2D_Gnuplot" in order to indicate, that the output format is directly suitable for gnuplot's "splot" command.