Program: STAT Purpose: Program to calculate elementary statistics in user Category: CALCULATION, PLOTTING, TABLES File: stat.c Author: M.G.R. Vogelaar Keywords: INSET= Give set, subsets: Maximum number of subsets is 2048. BOX*= Frame for input subsets. [entire subset] It is possible to give more than one box for each subset (with a maximum of 64), which can be handy if user wants to compare different boxes in one subset. The keywords appear as BOX1=, BOX2= etc. The BOX*= prompt is repeated until carriage return is pressed. TOSCREEN= Print results on screen? [Y] ** DISPTOT= Display table of totals? [default depends on TOSCREEN=] Overrule the TOSCREEN= keyword for table with statistics of totals. FILENAME= Name of ASCII file: [No output to file] If a name is specified, an ASCII file is created where data is written without the subset information. If you press carriage return, there will be no output to an ASCII file. APPEND= File exists, ok to append? [Y]/N The file specified in FILENAME= already exists. You can append to this file with APPEND=Y. If APPEND=N you will be prompted for another name. FORMAT= Give format for output: [Calculated] Print numbers on screen in user given output format. See description for possible formats. Keyword is only asked if TOSCREEN=Y GRDEVICE= Plot device: [List of devices] Destination of plot, Screen or Hardcopy. PLOT= [0]=quit,1=sum,2=mean,3=rms,4=min,5=max,6=pts,7=blks,8=DEV 1: Plot sum (default) 2: Plot mean 3: Plot rms 4: Plot minimum values 5: Plot maximum values 6: Plot number of points without blanks 7: Plot number of blanks 8: Select another graphics device (GRDEVICE=) ** TABNAME= Give name of table to store results: [STAT] Columns are created on set level. The table name for one box is STAT. If there are more boxes, the names are STAT1, STAT2 etc. The box number is appended by the program. TABNAME= specifies the name only. ** TABAPPEND= Append to existing columns? Y/[N] If a table already exists, it is possible to append to this table with TABAPPEND=Y The default always creates a new table. GRAPHICS: ** PGMOSAIC= View surface sub divisions in x,y: [1,1] View surface can contain a number of plots in in X and Y direction (mosaic). Default is 1 plot in both X- and Y direction. ** PGPAPER= Give width(cm), aspect ratio: [calc, calc] Aspect ratio is height/width. ** PGBOX= Corners of box Xl,Yl,Xh,Yh: [default by application] It is possible to overrule the calculated PGPLOT box size with PGBOX=. The coordinates (x,y) of the lower point are given first. ** PGCOLOR= Give color 1..15: [1] See description for the available colors. ** PGWIDTH= Give line width 1..21: [1] ** PGHEIGHT= Give character height: [1.0] ** PGFONT= Give font 1..4: [2] Description: STAT determines mean, rms, minimum value, maximum value, number of blanks and number of non-blank values in one or more boxes in user given subsets. The boxes are asked with BOX1=, BOX2= etc. The default for BOX1= is the entire subset. For the next box keywords, pressing carriage return will end the 'box loop'. STAT has two loops. The outer loop is always the loop over all given boxes and the inner loop is a loop over all given subsets. Results are written to screen if TOSCREEN=Y (default) in a formatted way. The format applies for all double precision numbers: sum, mean, rms, minimum and maximum. The format images that are allowed are described further on. The default format is: FORMAT=fffff.fff If TOSCREEN=N but DISPTOT=Y, only the statistics on the totals will be displayed. The results are also stored in a GDS table in the descriptor of the set you are working on. For each box a table name is created (or you can give one yourself with the hidden keyword TABNAME= ). This name is appended by the box number if there is more than one box. The appending of a number is always done by the program. The default table name is STAT. If for example, there are two boxes, you will have two tables with names STAT1 and STAT2. Each table has columns SUM, MEAN, RMS, MINVAL, MAXVAL, VALIDS, NBLANKS. There is also a column with the box number and there are columns with physical coordinates. These columns have the names of the 'repeat' axes. For instance, if AURORA is a RA-DEC-FREQ cube and you specified INSET=AURORA FREQ than the frequency axis is the repeat axis and a column with frequencies will be created. If a transformation can be made to a secondary axis type (f.i. velocity) than the name of the column will be the name of the secondary axis type and the physical coordinates will also be converted. Further statistics on these columns, plotting, editing etc. can be done with the program TABLE. The columns are all written on set level. In TABLE you need to specify: INSET=AURORA to get a table directory with columns made by STAT. If you want to append to existing columns, use TABAPPEND=Y Plotting is done in a loop. Each loop you can chose which result you want to plot (PLOT=). The x-coordinate is always a physical coordinate (if a conversion of grid to physical coordinate could be made). The y-coordinate is one of sum, mean, rms, minval, maxval, valids (the number of non blank values in the statistics) and nblanks (the number of blanks). For each selection the results of each box is plotted. In this loop, you can change the destination of the output (GRDEVICE=). Plots are sent to the printer after STAT is finished. Note that if there is more than one repeat axis, the physical coordinates in the plot will be taken from the first repeat axis. Example: STAT INSET=AURORA F 1:10 RA 3:5 will plot sum etc. in a plot where the frequencies are the x-coordinates. You will see three curves, one for RA 3, one for RA 4 and one for RA 5. PLOTTING ======== How do you change the layout of your plot? You have the possibility to overrule the default sizes of your plot with PGBOX= The number of plots on one page can be selected with PGMOSAIC=n,m where n is the number of plots in the x-direction and m the number of plots in the y- direction. Color is selected with PGCOLOR= The width of the lines with PGWIDTH= The height of the characters with PGHEIGHT= and the font with PGFONT= Hardcopy output can be controlled with PGPAPER= which defines size and aspect ratio of the plot on paper. FORMATS ======= The specification in FORMAT= is called a 'format image'. A 'format image' is used to print numbers in a user given format consisting of characters representing the wanted output format. The syntax is: flag(s) Zero or more flags, in any order, which modify the meaning of the conversion specification. The flag characters and their meanings are: - The result of the conversion is left- justified within the field. + The result of a signed conversion always begins with a sign, "+" or "-". string Characters, some with special meaning. If the string (f.i. FFFFF.FF or gggg.gg or wwwww) contains no dot, the number of characters specify a minimum field width. For an output field, if the converted value has fewer characters than the field width, it is padded on the left (or right, if the left-adjustment flag, - has been given) to the field width. If the string contains a dot, the total number of characters including the dot is the minimum field width and the number of characters after the dot is the precision. The characters are used to determine the conversion type. If the string contains an: 'e' or 'E' The floating-point-number argument is printed in the style [-]drddde+dd, where there is one digit before the radix character, and the number of digits after it is equal to the precision. The E conversion character produces a number with E introducing the exponent instead of e. The exponent always contains at least two digits. However, if the value to be printed requires an exponent greater than two digits, additional exponent digits are printed as necessary. 'g' or 'G' The floating-point-number argument is printed in style f or e (or int style E n the case of a G conversion character), with the precision specifying the number of significant digits. The style used depends on the value converted; style e is used only if the exponent resulting from the conversion is less than -4 or greater than or equal to the precision. others Strings without 'e', 'E', 'g' and 'G' indicate a floating point conversion. The floating point number argument is printed in decimal notation in the style [-]dddrddd, where the number of digits after the radix character, r, is equal to the precision specification. If the result of a conversion is longer than the field width, an asterisk is returned. If the input number is a blank, a 'b' is returned. Examples: Format string: +eeeeee.eeee Number: 43345.5436 Result: +4.3346e+04 Remark: exponential format signed conversion field width: 12 precision: 4 Format string: gggg.ggggg Number: 34.43 Result: 34.430 Remark: Field width is 10 Number of significant digits is 5 Format string: +ffff.ff Number: 23.456 Result: +23.46 Remark: signed conversion Format string: -ffff Number: 345.87 Result: 346 Remark: left justified Format string: -+ffff.fff Number: 34.43 Result: +34.430 Remark: left justified signed conversion Format string: eee.eeee Number: 234.43 Result: * Remark: Field width too small for conversion Format string: ffff.ff Number: blank Result: b Remark: input was a blank COLOR INDICES: ============= 0 Background 1 Default (Black if background is white) 2 Red 3 Green 4 Blue 5 Cyan 6 Magenta 7 Yellow 8 Orange 7 Yellow 8 Orange 9 Green + Yellow 10 Green + Cyan 11 Blue + Cyan 12 Blue + Magenta 13 Red + Magenta 14 Dark Gray 15 Light Gray 16-255 Undefined AVAILABLE FONTS: =============== 1 single stroke "normal" font 2 roman font 3 italic font 4 script font Notes: Example: Updates: Nov 17, 1992: VOG, Document created. Oct 23, 1995: VOG, Option included to Write data to ASCII file also (FILENAME=).. Feb 1, 2000: JPT, Increased number of subsets. Feb 9, 2001: VOG, Included subset coordinates in output file.