% @(#)plot_hist.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:49
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      plot_hist.hlq
%.AUTHOR     RHW, IPG/ESO
%.KEYWORDS   MIDAS, help files, PLOT/HISTOGRAM
%.PURPOSE    On-line help file for the command: PLOT/HISTOGRAM
%.VERSION    1.0  10-JUN-1987 : Creation, RHW
%----------------------------------------------------------------
\se
SECTION./HIST
\es\co
PLOT/HISTOGRAM                                                 10-JUN-1987  RHW
\oc\su
PLOT/HISTOGRAM tab col [x_sc,y_sc[,x_off,y_off]] [bin[,min[,max]]] 
               [exc] [log] [opt]
	plot histogram of a column in the table
PLOT/HISTOGRAM frame [x_sc,y_sc[,x_off,y_off]] [exs] [log] [opt]
	plot the histogram of an image
\us\pu
Purpose:    
            Plot a histogram of a column in a table or
            plot the histogram of given image
\up\sy
Syntax:     
            PLOT/HISTOGRAM tab col [x_sc,y_sc[,x_off,y_off]] [bin[,min[,max]]] 
                           [exc] [log] [opt]
            or
            PLOT/HISTOGRAM frame [x_sc,y_sc[,x_off,y_off]] [exs] [log] [opt]
\ys\pa
            tab  = name of table file
\ap\pa
            col = column reference
\ap\pa
            frame = name of image frame
\ap\pa
            x_sc,y_sc,x_off,y_off = scale or size in the x- and y-direction,
                  offset in the x- and y-direction. For the scaling x_sc
                  and y-sc, positive numbers are interpreted as scale
                  parameters (world units/mm), negative numbers as size
                  parameters (axis will be made sc_* mm. long). A
                  combination of a positive and negative number is
                  allowed. By default the plot fills the device area. \\
                  x_off and y_off determine the distance of the lower
                  left corner of the plot to the lower left corner of the
                  graphic device, measured in mm. By default, the plot
                  is put at the top left of the graphic device, allowing
                  space for the various labels.
\ap\pa
            bin,min,max = bin size, minimum, and maximum values to be included
                  in the histogram. Default bin size depends on the actual 
                  dynamic range of the data values; default minimum is the 
                  minimum of the column values; similar for maximum.

\ap\pa
            exc = plot low and high excess; default YY
\ap\pa
            log = flag for logarithmic scale; can be LIN (default) LOG 
                  or LN. 
\ap\pa      
            opt = histogram type, hashing spacing and hashing angle; 
                  default: standard staircase plot, no hashing done.\\
                  The histogram type is determined by an integer number:
                     0:  simple staircase;\\
                     1: staircase steps joining the x axis;\\
                  => 2: data points will joint the x axis with boxes 
                        which are determined by the number (2 = zero width)\\
\\
                  In case the hashing spacing is given a small number (e.g.
                  0.01) the histogram will be filled completely. A reasonable 
                  number is 1.
\ap\no
Note:    
            In case the second parameter is defaulted, the command assumes a
            frame as input.
\\
	    In case the input  is a frame the command will first check if the 
            descriptor HISTOGRAM exits. If so, these data will be plotted. If 
            the descriptor is absent the command  STATISTICS/IMAGE  will be 
            executed first.
\\
            The histogram determination of a table column makes use of the 
            command READ/HISTOGRAM. The histogram data for tables is stored 
            in two descriptors of the table: TCLAS001 and TFREQ001.
\on\see
See also:
            PRINT/HISTOGRAM, COMPUTE/HISTOGRAM, READ/HISTOGRAM
\\
            STATISTICS/IMAGE, STATISTICS/TABLE
\ees\exs
Examples:
\ex
            PLOT/HISTOGRAM myimage ? NN LOG
             This will plot the descriptor HISTOGRAM of the image `myimage.bdf' 
             with a logarithmic scale in y; the plot will fill the plot area 
             of the device.
             Does not plot the excess bins of the histogram if existing.
\xe\ex
            PLOT/HISTOGRAM mytable :VELOCITY 0.5,12.34 1,8 ? ? 1,1,45
             This will plot the column labelled :VELOCITY from table
             `mytable.tbl' with a x-scale of 0.5 units/mm and in y 12.34 
             units/mm; the bin size will be 1 and the minimum value will be 8.
             Excess bins will be plotted, and the histogram will be of bar 
             type and will be hashed (angle 45 deg).
\xe \sxe