Program:       FLUX

Purpose:       Program to calculate flux in user defined box.

Category:      ANALYSIS, CALCULATION, TABLES

File:          flux.c

Author:        M.G.R. Vogelaar

Keywords:

   INSET=      Give input set, subsets:
               Input set (and subsets). Maximum number of subsets is 2048.

** POLYGON=    Define polygons instead of boxes?                     Y/[N]
               If you want the flux in a polygon select POLYGON=Y.
               The keyword VERTICES%= (%=1,2,3,...) is prompted instead
               of BOX%= The Polygon option can be used for two dimensional
               subsets only.

   VERTICES%=  Give vertices of polygon:
               Asked if POLYGON=Y
               The vertices are given in two dimensional coordinate pairs
               x1,y1, x2,y2, .....
               The minimum number of vertices is 3, the maximum is 128.
               The program closes the polygon. The maximum number of
               pixels in the box that encloses the polygon cannot exceed
               16384.

   BOX%=       Frame for input subsets.                    [entire subset]
               Asked if POLYGON=N
               It is possible to give more than one box (% indicates
               box number). The keyword is repeated until user pressed
               carriage return.

   CLEANBEAM=  Do you want to give values of a clean beam?           Y/[N]
               If data is radio data and there is no AP available,
               use CLEANBEAM=Y and BEAM= to calculate the sum in the AP.


   HEADER=     Antenna Pattern from header?                          [Y]/N
               If your data is radio data and there is a reference
               to an antenna pattern (AP) in the header, you can choose to
               select this antenna pattern by specifying HEADER=Y. If you
               want to get the APSET prompt to select another AP, specify
               HEADER=N

               if HEADER=Y:

** APSET=      Give set, subs. of ant.pat.:               [AP from header]

               if HEADER=N or no reference to AP:

   APSET=      Give set, subs. of ant.pat.:                       [NO AP]]
               Set and subset(s) of AP. This keyword is
               prompted if your data is radio data and there is no
               reference to an AP in the header, or there was a reference,
               but you selected HEADER=N. The program recognizes several
               radio telescopes.

   BEAM=       Maj. and min. axis of beam (arcsec)                  [none]
               Asked if CLEANBEAM=YES
               The sum in the AP is now the integral from -inf. to inf.
               of a gaussian with the specified FWHM.

   CDELT%=     Give grid spacing in 'axis type' in 'axis units':
               If a clean beam is wanted, the grid spacings are needed.
               If a spacing is not found in the header, you are prompted
               to give the spacing in units as found in the header.

   FREQUENCY=  Give frequency:                                 [1.415 GHZ]
               If FLUX cannot find a proper frequency for primary beam,
               correction, a frequency is asked with FREQUENCY=
               The keyword accepts a number and a unit. If no unit is given,
               the number is in Ghz. Otherwise, a conversion is done to Ghz.
               The possible units to convert from are for example MHz,
               Hz, but also cm (all upper- or lowercase). The keyword
               is asked unhidden only once.

   GRDEVICE=   Plot device:                              [List of devices]
               Destination of plot, Screen or Hardcopy.

   FILENAME=   Name of ASCII file:                     [No output to file]
               If a name is specified, an ASCII file is created
               where fit parameters are listed in a row. 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.


               PLOTTING:

   OPTION=     0)Exit  1)Sum  2)SumPBC  3)Flux  4)FluxPBC  5)GRdev    [3]
               Plot results. Default is a plot of the flux if the
               flux is calculated else the default is a plot of the
               sum. Option 5 offers the possibility to change the 
               plot device. You are prompted with the GRDEVICE= keyword
               again. Also the hidden 'PG" keywords (PGMOSAIC=, PGPAPER= etc.
               accept new values if you define them at this point. 

** PGMOSAIC=   View surface sub divisions in x,y:             [calculated]
               View surface can contain a number of plots in
               in X and Y direction (mosaic). Default the program tries
               to put the same number of columns as rows in 1 plot.

** 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.

** PGTICKS=    Coord. int. between maj. tick marks in X,Y:    [calc, calc]
               World coordinate interval between major tick marks
               on X and Y axis. The default is 0 0 which results in 
               values calculated by PGPLOT.
               
** PGNSUB=     Number of subintervals between maj. ticks:     [calc, calc]
               The number of subintervals to divide the major
               coordinate interval into. The default is calculated 
               by PGPLOT.
               
** 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]

** TABNAME=    Give name of table to store results:                 [FLUX]
               Columns are created on set level.

** 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.


Description:   Inside the box in which one wants to know the flux, all
               non blank pixel values are summed and then, if possible,
               the sum is converted to a flux in appropriate units. This
               conversion is case dependent:

               a) RADIO DATA

               Data is considered radio data, if the instrument name
               in the header is equal to one of 'WSRT', 'VLA' ,'FST',
               or 'DRAO'. Primary Beam Correction is available for
               'WSRT', 'VLA' ,'FST'.

               What is needed for the conversion from sum to flux
               is the 'SUMAP' in an equivalent box, i.e. the sum
               over all pixels in a box of the corresponding antenna
               pattern (AP) that has a size equal to the size of the box
               in which the flux is wanted. A warning is generated if
               the AP cannot be summed symmetrically. The axes in such
               a box will be extended in length until they are all
               symmetrical. Be warned that your box is changed then!
               Also a Primary Beam Corrected (PBC) sum and flux is
               determined. This is a correction for the response of one
               antenna and it depends on distance of a position to the
               beam center and on frequency. The distance is corrected
               for projection effects. If it is greater than a certain
               distance (validity range of PBC), there is no contribution
               to the sum or flux.

               PBC possible if:

               1) An instrument name can be found in the set header.
               2) The instrument is one of WSRT, VLA or FST.
               3) The dimension of the selected subset must be 1 or 2
               4) The subset axes are spatial.
               5) The subset is 2-dimensional, and the spatial axes
                  are be different.
               6) The reference values CRVAL% & CDELT% can be found in
                  the header.
               7) There is a spectral axis available and the units can
                  be converted to GHZ (if no spectral axis is available,
                  a frequency is asked with FREQUENCY=).


               If the RA-DEC pointing center of the telescope can not be
               found in the header,  it is assumed they are equal to
               CRVAL1 and CRVAL2 (position of grid 0,0). If an image value
               is not a blank and its position is within the validity
               region of the primary beam correction, the value is
               corrected and added to 'sumPBC'.

               If a polygon is defined, the AP is centered at the
               position weighted center of the data inside the polygon
               and only the part of the AP inside the polygon is summed.

               b) NON-RADIO DATA

               The grid spacings from the header are read and
               converted to steradian/pixel. The sum in the
               requested box is multiplied by this number.



               'flux' has a different definitions. For radio data you
               need an antenna pattern because sum = sum / sumAP. For
               other data: sum = sum * steradians/pixel.
               The units of the flux are the units found in the header.

               'fluxPBC' is calculated if there is a 'sumPBC' and an
               antenna pattern. It is comparable to 'flux', but in this
               case the sum is the primary beam corrected sum. If the
               data was in Westerbork Units (WU), a conversion to mJy's
               is applied, where 1 W.U. ==> 5 mJy/Beam.


               Plotting:

               It is possible for each given box, to make a plot of
               sum against subset index. The subset index always runs
               from 0 to the number of subsets you specified minus 1.
               A plot can be created only if the number of subsets
               is greater than 1;


               Tables:

               Results are always stored in a table. The name of the
               table is FLUX by default. You can change this with
               TABNAME=. The name is appended by a number that corres-
               ponds to the number of the used box (FLUX1, FLUX2, ...).
               The names of the columns are:

               SUM            Sum of data
               SUMPBC         Primary beam corrected sum
               FLUX           Flux
               FLUXPBC        Primary beam corrected flux
               SUMAP          Sum in Antenna pattern
               NDATA          Number of non blank points in statistics
               NBLANKS        Number of blanks in statistics
               XLO            Lowest X value of box
               YLO            Lowest Y value of box
               XHI            Highest X value of box
               YHI            Highest Y value of box
               SUBGRIDn       Used subset in grid coordinates
                              n is a number of an axis outside
                              the subset. If there are no axes outside
                              the subset, this column is not created.
               Axisname       If there are n axes outside the subset,
                              there will be n extra columns with the
                              name equal to the name of the (secondary)
                              axis, containing physical units.

               Use the application TABLE to print, plot and process the
               column entries.




               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:       Mar 20,  1990: VOG, Document created.
               Apr 10,  1992: VOG, New call to PRIBEAM.
               May 26,  1992: VOG, Rewritten in C.
               Oct  5,  1992: VOG, Units bug with 'strtok'
                                   Tables implemented.
               Apr 16,  1996: VOG, Implemented code for unequal column 
                                   lengths when appending tables.