% @(#)statisimag.hlq 17.1.1.1 (ESO-IPG) 01/25/02 17:44:00 %++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ %.COPYRIGHT (c) 1990 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 14-OCT-1998 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 = name of image frame; 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 FFYN \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 \\ 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) \\ By default, the median value is determined via the histogram of the image, in order to speed up the STATISTICS command. This works pretty well if there are no "runaway" data, like e.g. saturated columns in a CCD frame which are far outside the rest of the data intensity range. But, note, 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. \\ The difference in execution time for e.g. the F or G statistics level is not excessive, e.g. a factor 2 for a 2048*2048 image, so the options F, V, ... are mainly kept 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. \on\exs Examples: \ex STATIST/IMAGE toro [335,405:3333,425] 0.5 Work in specified window of 2-dim image `toro.bdf'. \xe\ex STATIST/IMAGE becerra [@12:>] 0.5 Work in specified window of 1-dim image `becerra.bdf'. \xe\ex STATIST/IMAGE ? CURSOR Work on displayed image, choose windows via cursor. \xe\ex STATIST/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 STATIST/IMAGE vaca PLOT=P Statistics on image frame `vaca.bdf', no display of results, but plot the histogram. \xe\ex STATIST/IMAGE vaca option=GF plot=P As above but compute the exact value of the median. \xe\ex STATIST/IMAGE vaca option=WF plot=P As above but compute also the mean_abs_dev of mean and median. \xe\ex STATIST/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 STATIST/IMAGE toro ROW OPTION=RN OUTTAB=vaca,image As above but write results to 2-dim image `vaca.bdf'. \xe\ex STATIST/IMAGE toro ROW OPTION=gs OUTTAB=ternera,image,median Fill 1-dim image `ternera.bdf' with row-medians of `toro.bdf'. \xe\ex STATIST/IMAGE toro ROW,10,22,299 ? ? gs Do full statistics on rows #10, #22 and #299 of `toro.bdf'. \xe\ex STATIST/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 STATIST/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 STATIST/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