%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2012 European Southern Observatory
%.IDENT      statisimag.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, STATISTICS/IMAGE
%.PURPOSE    On-line help file for the command: STATISTICS/IMAGE
%.VERSION    1.0  06-APR-1990 : Creation, KB
%.VERSION    1.1  01-MAR-1991 : change layout of OUTPUTR + STATIST, KB
%.VERSION    1.2  08-JUL-1992 : add more options, KB
%----------------------------------------------------------------
\se
SECTION./IMAG
\es\co
STATISTICS/IMAGE			                23-FEB-2009  KB
\oc\su
STATISTICS/IMAGE [frame] [area] [bins] [lo,hi_exc] [option] [outtab] 
                 [plotflg] [format]
	calculate statistics of a frame
\us\pu
Purpose:  
          Calculate statistics of a frame.
\up\sy
Syntax: 
          STATISTICS/IMAGE [frame] [area] [bins] [lo,hi_exc] [option]
                           [outtab] [plotflg] [format]
\ys\pa
          frame = input data,
		  (a) name of image frame 
		  (b) table_name,column (as :col_label or #col_no);
		  defaulted to displayed image
\ap\pa
          area = window within image to work on;
               (a) subframe       or    subframe1,subframe2,... 
                   subframe(s) in the usual MIDAS syntax: [xs:xe] or
                   [xs,ys:xe,ye] or [xs,ys,zs:xe,ye,ze],
                   see the Help of READ/IMAGE for more info
               (b) complete frame, indicated by '+' (the plus sign);
               (c) CURSOR for cursor defined windows, size may be adjusted
                   interactively;
                   or CURSOR,cmax for max. `cmax' cursor inputs;
               (d) ROW for processing of all rows of 2-dim input frame, or
                   ROW,i,j,... to process rows no. i, j, ... of frame;
               (e) COLUMN for processing all columns of 2-dim input frame, or
                   COLUMN,i,j,... to process columns no. i, j, ... of frame;
               (f) PLANE for processing all planes of 3-dim input frame, or
                   PLANE,i,j,... to process planes no. i, j, ... of frame;
               (g) table_name for table defined subimages, which are defined
                   in the (real data) columns labeled :XSTART, :XEND, :YSTART 
                   and :YEND. For 3-dim frames also :ZSTART and :ZEND are used;
               (h) [xpix*ypix] fixed sized intervals/subframes
                   as many subframes of `xpix' * `ypix' pixels are used as
                   needed to cover the full 1- or 2-dim image, if NPIX(1) is
                   not a multiple of `xpix' the last interval gets the size to
                   fit (the same applies to y-direction)
                   for 1-dim frames [xpix*1] has to be given
               defaulted to (b);
\ap\pa
          bins = bin size for histogram calculation or no. of bins;
               to distinguish between the two options, the character \# is used
               for no. of bins; defaulted to \#256;
               if the parameter lo,hi_exc is given, two excess bins are added.
               Bins are half-open intervalls [a,b[, i.e. all values v with
               a <= v < b contribute to this bin.
\ap\pa
          lo,hi_exc = optional low and high excess values,
               i.e. all values less than lo_exc contribute to the low excess
               bin (1st bin) and all values greater or equal to hi_exc
               contribute to the high excess bin (last bin) in the histogram.
               The resulting histogram is stored in the descriptor HISTOGRAM
               and can be converted to image or table format by the 
               application procedure @a histogram (see HELP/APPLIC histogram);
\ap\pa
          option = 4 chars flag for: statistics_level (1), display_flag (2),
                                     rect_draw_flag (3), merge_flag (4);
               statistics_level: F/G or V/W or R/X or S or H or M;
                   F(ull) Statistics => compute statistical quantities (1) - (4)
                                        (as explained in the Notes below)
                   G is like Full, but exact median is obtained,
                   V is like Full, but also stat. quantity (5) is calculated
                   W is like V, but exact median is obtained and used for (5)
                   R(educed) Statistics => only (1) -> (3) are computed
                   X like Reduced, but exact median is obtained,
                   S(hort) Statistics => only (1) + (2) are computed,
                   H(istogram) => (1) + (4)are computed, 
                   M(inmax) => only (1) s calculated 
               display_flag: F(ull), S(hort), X(short) or N(o) display of
                             results;
               rect_draw_flag: Y(es) or N(o) for drawing rectangles around
                   subframes (only applied to area option );
               merge_flag: M(erge) or N(o Merge) - not applicable to area
                   choices (b) and (h);
                   if set to Merge, the area of all subframes specified are 
                   used to gather the required statistics;
               defaulted to GFYN
\ap\pa
          outtab = optional output table (or image)
               for table output the table columns hold same contents as the
               descr. STATISTIC (cf. Note);
               enter `outtab,A' if results should be appended to existing table
               `outtab', otherwise a new table `outtab' will be created
               enter `outtab,image' if all results are written into a 2-dim
               image `outtab', each row holding contents like descr. STATISTIC
               enter `outtab,image,stat_val' if only one specific statistical
               value should be written into a 1-dim image `outtab' 
               stat_val may be any of: Minimum, Maximum, Mean, Stddev, Mom3,
               Mom4, Total, Median, Mode1 or Mode
\ap\pa
          plotflg = P(lot) or N(oplot) for plotting the histogram (with some
               consequences for area option (c) -> (g));
               defaulted to N
\ap\pa
          format = Format string used for displaying minimum, maximum, mean and
               std_dev of frame in Fortran notation; 
               defaulted to E15.6
\ap\sa
See also:
          STATISTICS/TABLE, PLOT/HISTOGRAM, FIND/MINMAX, FIND/PIXEL
          SHRINK/IMAGE, REBIN/STATISTICS, HELP/APPLIC histogram
\as\no
Note:
          The parameters may also be referenced via
          FRAME=, AREA=, BINSIZE=, EXCESS=, OPTION=, OUTTAB=, PLOT=, FORMAT=
 
          The following statistical quantities are computed:
          1) minimum + maximum 
          2) mean value, standard deviation
          3) dimensionless 3rd, 4th moment + intensity (sum of pixels)
                formulas used for 3rd, 4th moment are:
                3rd moment = 1/N * 1/std**3 * SUM of (x - mean)**3
                4th moment = 1/N * 1/std**4 * SUM of (x - mean)**4
                (with std = standard deviation) - they are also known as
                moment coefficients of "skewness" and "kurtosis"
          4) histogram + median + first mode + mode of data values.
          5) mean abs. deviation (m_a_d) of mean + of median
                formulas used are:
                m_a_d of mean = 1/N * SUM of abs(x - mean)
                m_a_d of median = 1/N * SUM of abs(x - median)
 
          The following descriptors are filled for area option (a) with single
          subframe and (b):
          WINDOW_FROM, WINDOW_TO, STATISTIC and if option(1) = F or H, also
          HIST_BINS and HISTOGRAM.
          Start and end frame pixels of the area are saved in integer
          descr. WINDOW_FROM and WINDOW_TO.
          Real descr STATISTIC is filled depending upon 1. char of `option' 
          as follows:
          minimum(1), maximum(2), mean value(3), standard deviation(4),
          3rd moment(5), 4th moment(6), intensity(7), median(8),
          first mode(9), no.of bins(10), binsize(11), mode(12),
          m_a_d mean(13), m_a_d median(14)
 
          With option[1] = F, the median value is determined via the histogram
	  of the image, in order to speed up the STATISTICS command. This works 
	  pretty well if the range of the image data is not too large 
	  (max. no. of histogram bins is 1024). By using well chosen excess bins,
	  also in that case we would get a good approximation to the median.
          With the statistics level (1. char. of parameter `option') set to G,
          W or X you enforce the precise calculation of the median value, which
          means that the complete image has to be sorted. 
          With the current computer systems, the difference in execution time 
	  for the F or G statistics level is is hardly noticeable anymore...
	  So, as of the 08SEP release of Midas, by default the median is 
	  calculated by sorting the image. The option for calculating the median
	  via the histogram is just left for backwards compatibility.
          If 1. char of `option' = F/G: elements (1) - (12) of STATISTIC are
          written (in same order), 
          if = R: (1) - (7), = X: (1) - (8), = S: (1) - (4), = M/H: (1) - (2)
          and if 1. char = V/W: (1) - (14) are written.
 
          The number of bins + binsize is stored in the real descr. HIST_BINS
          in element (1,2), lo,hi_excess are stored in (3,4) and the no. of
          excess bins (= 0 or 2) is put in HIST_BINS(5), if descr. are written.
          Integer descr HISTOGRAM is filled with histogram:
          HISTOGRAM(1) = number of values in first bin, which is the lower
                         excess bin, if lo,hi_excess are given
          HISTOGRAM(2) = number of values in second bin, ...,
          HISTOGRAM(n) = number of values in last bin, which may be the high
                         excess bin, n = HIST_BINS(1)
 
          Always the real keyw. OUTPUTR is filled with same contents as descr.
          STATISTIC, i.e.  max. 14 values, depending on `option'.
          Integer keyword OUTPUTI will hold total no. of pixels and pixel
          numbers of min. and max. coordinates, i.e. (1 + NAXIS*2) values.
          If the complete frame was processed, descriptor LHCUTS(3,4) will
          also be set to the minimum and maximum value.
 
          If an output table name is specified, the statistical quantities
          are stored in columns which are labeled
          :MIN, :MAX, :MEAN, :STD, :MOM3, :MOM4, :TOT_INTENS, :MEDIAN,
          :SMAL_MODE, :NO_BINS, :BIN_SIZE and :MODE.
 
          If the plotflag is set to `P', statistics_level must be = F, G or H,
          otherwise there is no histogram! In that case, also for area choices
          (c) -> (g) the descr. HIST_BINS and HISTOGRAM are always updated.
          For area choices (d), (e) and (f) counting starts at 1.

	  There is also the command STATISTICS/TABLE for getting statistical
	  quantities of a table column. Option (b) for the 1st parameter 
	  'frame' was added to get exactly the same results for a table column 
	  as for a 1-dim image. Only selected and non-NULL elements of the
	  given column are used for the statistics calculations.
	  However, none of the 'statistics'  descriptors is written to the 
	  table, only to Midas keywords.
\on\exs
Examples:
\ex
          STATISTICS/IMAGE toro [335,405:3333,425] 0.5
            Work in specified window of 2-dim image `toro.bdf'.
\xe\ex
          STATISTICS/IMAGE becerra [@12:>] 0.5
            Work in specified window of 1-dim image `becerra.bdf'.
\xe\ex
          STATISTICS/IMAGE ? CURSOR
            Work on displayed image, choose windows via cursor.
\xe\ex
          STATISTICS/IMAGE becerra BINSIZE=1.0 EXCESS=0.22,9.8
            Do statistics on image frame `becerra.bdf', specify a binsize of
            1.0 - all pixels with intensity up to (and equal to) 0.22 are 
            collected in the low excess bin, all pixels with intensity higher
            than 9.8 are collected in the high excess bin.
\xe\ex
          STATISTICS/IMAGE vaca PLOT=P
            Statistics on image frame `vaca.bdf', no display of results, but
            plot the histogram.
\xe\ex
          STATISTICS/IMAGE vaca option=WF plot=P
            As above but compute also the mean_abs_dev of mean and median.
\xe\ex
          STATISTICS/IMAGE hear.tbl,:wave
            Do statistics on column labeled :wave (only selected, non-NULL
	    rows) of table `hear.tbl'. Results are saved in keywords only.
\xe\ex
          STATISTICS/IMAGE toro ROW OPTION=RN OUTTAB=vaca
            Reduced statistics on all rows of 2-dim image `toro.bdf'. Display
            nothing and write results to table file `vaca.tbl'.
\xe\ex
          STATISTICS/IMAGE toro ROW OPTION=RN OUTTAB=vaca,image
            As above but write results to 2-dim image `vaca.bdf'.
\xe\ex
          STATISTICS/IMAGE toro ROW OPTION=gs OUTTAB=ternera,image,median
            Fill 1-dim image `ternera.bdf' with row-medians of `toro.bdf'.
\xe\ex
          STATISTICS/IMAGE toro ROW,10,22,299 ? ? gs
            Do full statistics on rows #10, #22 and #299 of `toro.bdf'.
\xe\ex
          STATISTICS/IMAGE toro ROW,10,22,299 ? ? gsnm
            Merge rows #10, #22 and #299 of `toro.bdf' and do full statistics
            on all those pixels as if it were a single frame.
\xe\ex
          STATISTICS/IMAGE toro [8x8] OPTION=gs OUTTAB=ternera,image,mean
            Do statistics over as many 8 * 8 pixels intervals as needed to 
            cover the frame `toro.bdf'. Intervals start at pixel (1,1),
            move along x-axis and then increase along the y-axis.
            Fill `ternera.bdf' with the means of all these intervals.
\xe\ex
          STATISTICS/IMAGE chiva cursor option=ss format=f5.2
            Use cursor rectangle to define areas for calculating short
            statistics (and short display) and use format `F5.2' for output.
            Frame `chiva.bdf' is loaded in the display.
\xe \sxe
