Program:       MEDIAN

Purpose:       Calculate median of data from set, file, table or
               expression.
               
Category:      CALCULATION

File:          median.c

Author:        M.G.R. Vogelaar

Keywords:


** FILENAME=   Name of ASCII file:                  [No output to file]

               Write result (median, number of pixels, number of
               blanks) to Ascii file on disk. If the file already 
               exists, the keyword OVERWRITE= is prompted.

               Example of contents:
               
               ! Median ---- total number of pixels ---- number of blanks
               0.000000  1000  0



   APPEND=     File exists, ok to append?                        [Y]/N
   
               Only asked if FILENAME= is a name of an existing
               file on disk.


   INSET=      Give input set (, subsets):                [other input]
               Maximum number of subsets is 2048.
               The default, carriage return, prompts with DATA=
               If subsets are defined, then all data will be 
               treated as one array. The result is ONE median.


   BOX=        Give box in .....                        [entire subset]
   
  
   DATA=       Enter data (from file/table/expression):
               Standard input for floating point numbers.
               See examples.
               


Notes:         This program stores the result in the header of
               INSET= using keyword MEDIAN
               The value is stored as a real, not as a double.


               There is a hidden keyword FAST= that selects an 
               alternative method to calculate a median by selecting
               the k largest elements in an array. The default is FAST=N. 
               To examine the (experimental) method, type FAST=Y


               Given an array with N data values extracted from set, 
               file or table:
               MEDIAN will remove all blanks in that array before
               sorting. After sorting, we have a new array with length M.
               and the median is calculated as:
               1) If M is odd, the median is the k-th element with
                  k = (M+1)/2
               2) When M is even, the median is the arithmetic mean
                  of the elements k=M/2 and k=M/2+1.
               

Examples:      INPUT OF NUMBERS WITH DATA=
               ===========================

               The input of the array data follows the rules of
               input of floating point numbers. Probably you want to
               use one of the database or file functions 'table',
               'image', or 'file'.

               FILE
               ====
               Syntax for reading from file:

                       keyword=file(filename,column,rows)

               and the syntax for 'rows' is as for recall files.


               ex.1:  DATA=file(profile.txt,2,3:20)

               reads from ASCII file profile.txt the second column.
               It starts reading at row 1 and it wil read until
               line 20 is read.

               ex.2:  DATA=file(profile.txt,2,1:)

               reads from ASCII file profile.txt the second column.
               It starts reading at row 1 and it will read until
               the end of that column.


               IMAGE
               =====
               Syntax for reading image data:

                           keyword=image(set, box)

               'set' is the set/subset specification as known from
               the INSET= keywords. 'box' sets the limits as in the
               BOX= keywords. Suppose we have a 2-dim RA/DEC GIPSY set
               called 'profset', then:

               ex.3:  YARRAY=image(profset dec 0, -14 15)

               reads profile data in the RA direction at DEC=0.
               It starts reading at RA=-14 and it stops reading
               image data after RA=15


               TABLE
               =====
               Syntax for reading data from a table:

                      keyword=table(set, tab, col, rows)

               'set' is the set/subset specification as known from
               the INSET= keywords. 'tab' is the name of the GDS table,
               'col' is the name of a column in that table and rows
               indicate the rows in that column.
               Set 'profset' has a table called 'tab1'. This table
               has two columns named 'X' and 'Y':

               ex.4:  DATA=table(profset,tab1,X,1:39)

               reads row 1 to 39 from column 'X' from table 'tab1'
               in set 'profset'.



Updates:       Jun 19, 1995: VOG, Document created.
               Feb  1, 2000: JPT, Increased number of subsets.