; TAPLT
;---------------------------------------------------------------
;! Plots data from a Table extension file
;# TASK TABLE PLOT
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2005, 2008-2009, 2012
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
TAPLT     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TAPLT     Plots data from a Table extension file
USERID       -32000.0    32000.0   File owner - ignored
INNAME                             Input file name (name)
INCLASS                            Input file name (class)
INSEQ             0.0     9999.0   Input file name (seq. #)
INDISK            0.0        9.0   Input file disk unit #
INEXT                              Input table type.
INVERS            0.0    46655.0   Input table version #.
BCOUNT            0.0    99999.0   Beginning row in plot
ECOUNT            0.0    99999.0   Last row in plot: 0 => end
XINC              0.0     9999.0   Increment between plotted
                                   rows
DOHIST           -3.0        1.0   Plot as histogram
APARM                              Column selection parameters:
                                   1: X-axis col A, no default
                                   2: X-axis col A subscript
                                   3: X-axis col B, no default
                                   4: X-axis col B subscript
                                   5: X-axis function type
                                          SEE the HELP !
                                   6: Y-axis col A, no default
                                   7: Y-axis col A subscript
                                   8: Y-axis col B, no default
                                   9: Y-axis col B subscript
                                   10: Y-axis function type
BPARM                              Control parameters
                                   1 : Number of bins in plot
                                   2 : Print binned results?
                                   3 : > 0.0 => fixed scale
                                       < 0.0 => fixed range
                                   4 : Xmin (fixed scale)
                                   5 : Xmax (fixed scale)
                                   6 : Ymin (fixed scale)
                                   7 : Ymax (fixed scale)
                                   9: Exponent for X-axis
                                   10: Exponent for Y-axis
CPARM                              1: X-axis col A factor
                                   2: X-axis col A offset
                                   3: X-axis col B factor
                                   4: X-axis col B offset
                                   5: Y-axis col A factor
                                   6: Y-axis col A offset
                                   7: Y-axis col B factor
                                   8: Y-axis col B offset
                                   9: X-axis overall factor
                                   10: X-axis overall offset
RPARM                              Limit plot to rows matching
                                   (1) column, (2) subscript,
                                   (3) value, (4) allowed
                                   mismatch, (5-8) 2nd test
                                   (9-12) 3rd test, etc.
KEYSTRNG                           String to match
DOINVERS         -1.0       1.0    > 0 print if not match, else
                                   print only if match
LTYPE         -10.0        10.0    Type of labeling: 1 border,
                                   2 no ticks, 3 - 6 standard,
                                   7 - 10 only tick labels
                                   <0 -> no date/time
DOTV           -1.0         1.0    > 0 Do plot on the TV, else
                                   make a plot file
GRCHAN          0.0         8.0    Graphics channel 0 => 1.
----------------------------------------------------------------
TAPLT
Type: Task
Use:  Plots data from an AIPS table-format extension file.
Adverbs:
  USERID.....Input file user number.  Ignored.
  INNAME.....Input file name (name)    Standard defaults.
  INCLASS....Input file name (class)   Standard defaults.
  INSEQ......Input file name (seq. #)  0 => highest.
  INDISK.....Disk drive # of input file.  0 => any.
  INEXT......Type of input table extension.  '  ' = 'CC'
  INVERS.....Version number of table extension.  0 => highest.
  BCOUNT.....Beginning row number to be included in plot. 0 = 1.
  ECOUNT.....Ending row number included in plot.  0 = highest.
  XINC.......Increment in row number between rows included in
             plot.    0 => 1.
  DOHIST.....> 0 => plot as histogram in the X-axis parameter.
             <= 0 plot two columns against each other.
  APARM......Column selection parameters:
     1 = X-axis logical column number A:  0 => row number.
         < 0 => use absolute value of col. abs(APARM(1))
     2 = The subscript of the X-axis column A data to use if the
         column is an array.  0 => 1.
     3 = X-axis logical column number B:  0 => row number.
         < 0 => use absolute value of col. abs(APARM(1))
     4 = The subscript of the X-axis column B data to use if the
         column is an array.  0 => 1.
     5 = X-axis function number: Various functions may be
         performed on column A only or on a pair of columns A
         and B before plotting.  Functions which use column A
         only are 0 = no function, 1 = sum, 2 = asin, 3 = Log10,
         4 = ln, 5 = exp, 6 = sin, 7 = cos, 8 = tan, 9 = atan.
         In these cases, APARM(3) and (4) are ignored.  Sum
         includes those rows which are not plotted due to XINC
         and BCOUNT.  Functions which use both columns are
         10 = +, 11 = -, 12 = *, 13 = /, 14 = **, 15 = mod,
         16 = Modulus, 17 = atan2, 18 = max, and 19 = min.
         The atan, atan2 return results in degrees.
     6 = Y-axis logical column number A:  as for X-axis.
     7 = The subscript of the Y-axis column A data to use if the
         column is an array.  0 => 1.
     8 = Y-axis logical column number B:  as for X-axis.
     9 = The subscript of the Y-axis column B data to use if the
         column is an array.  0 => 1.
     10 = Y-axis function number: as for X-axis.  The Y-axis
         parms 6-9 are ignored if DOHIST > 0.  APARM(10) will
         be used for the histogram counts if it is 2 = sqrt,
         3 = log10, or 4 = ln.  Otherwise it is ignored too.
  BPARM......Plot control parameters:
     1 = If DOHIST > 0, the number of bins in the histogram (0 => 50).
         If DOHIST <= 0 and BPARM(1) > 0, the plot will be of bin
         averages in X of the specified quantity.  There will be
         BPARM(1) number of bins in the plot.  For bins with more than
         2 samples the vertical height of the symbol represents the
         standard deviation of the mean of the distribution in the
         bin.  In this case, 0 means to plot all points rather than
         the binned average.  BPARM(1) < 0 means to plot the sum in
         abs(BPARM(1)) bins rather than the average.
     2 = If DOHIST <= 0 and BPARM(1) > 0 and BPARM(2) > 0, the
         bin averages will be printed in the message file at
         message level 4.
     3 = If greater than zero, use BPARM(4) - BPARM(7) as the ranges
         of the axes.  If less than zero, use the BPARMs to limit the
         range of the axes, but self-scale the axes within that range.
         If 0.0, fully self-scaling.
     4 = Minimum of X-axis.
     5 = Maximum of X-axis (if = BPARM(4) do self-scale in X).
     6 = Minimum of Y-axis.
     7 = Maximum of Y-axis (if = BPARM(6) do self-scale in Y).
     9 = The exponent to which to take the X-axis result value
         before plotting.   0 => 1.
     10 = The exponent to which to take the Y-axis result value
         before plotting.   0 => 1.
  CPARM......After the value or absolute value of a column is
          found, it may be scaled and offset before other
          functions are applied to it.
     1 = X-axis logical column number A scale factor: 0 -> 1.
     2 = X-axis logical column number A offset.
     3 = X-axis logical column number B scale factor: 0 -> 1.
     4 = X-axis logical column number B offset.
     5 = Y-axis logical column number A scale factor: 0 -> 1.
     6 = Y-axis logical column number A offset.
     7 = Y-axis logical column number B scale factor: 0 -> 1.
     8 = Y-axis logical column number B offset.
     9 = X-axis overall factor, 0 -> 1.
     10 X-axis overall offset - after all other scaling, powers, etc.
        are applied the X value is multipled by CPARM(9) and CPARM(10)
        is added.
You can also limit the plot to include those rows which match or which
do not match specified values.
  RPARM......(1-4) 1st test column, subscript, value, allowed error
             (5-8) 2nd test column, subscript, value, allowed error
             (9-12) 3rd test column, subscript, value, allowed error
             etc. up to 7 tests all of which are ANDed.
  KEYSTRNG...One test may be on character-valued column which must
             match this adverb - the match is checked only to the
             number of characters given in KEYSTRNG.  Thus, for
             example, KEYSTR='RFLAG:'; DOINV 1; RPARM = 9,1 will
             include only those flags not generated by RFLAG ignoring
             the times shown in the RFLAG reasons when printing a flag
             table.
  DOINVERS...<= 0 => include only those rows match tests 1, 2, etc.
                     (how many of them have values)
             > 0  => include only those that do not match
  LTYPE.......Labelling type: 1 = border, 2 = no ticks,
              3 - 10 = standard, with  7-10 all labels other
              than tick numbers and axis type are omitted.
              Less than 0 is the same except that the plot file
              version number and create time are omitted.
  DOTV........> 0 => plot directly on the TV device, otherwise
              make a plot file for later display on one or
              more devices (including the TV if desired).
  GRCHAN......Graphics channel (1 - 7) to use for line drawing.
              0 => 1.
----------------------------------------------------------------
Examples:

A Clean Component extension has flux in column 1 and delta X in column
2 and Delta Y in column 3.  To plot the fluxes versus radius from the
center, self-scaling the plot with no scaling of column values
     INEXT = 'CC'; XINC 1
     APARM = 2, 1, 3, 1, 16,  1, 1
     BPARM = 0
     CPARM = 0
The APARM selects column 2 subscript 1 and column 3 subscript 1 to be
operated on by the modulus function [sqrt (a*a + b*b)] as the X plot
parameter and column 1 subscript 1 to be the Y plot parameter.  One
could bin the results by setting DOHIST = 1 and choosing the number of
bins with BPARM(1).


To plot a histogram of phases from an SN table
     INEXT = 'SN'; XINC 1
     DOHIST = 1
     APARM = 11, 0, 10, 0, 17
     BPARM = 45, 0, 1, -45, 45
     CPARM = 0
does the plot for the first IF and first polarization.  Column 11 has
the imaginary part, column 10 the real part and function 17 is ATAN2.
The results are binned in 45 bins from -45 to 45 degrees.


To plot the SY table, consider SNPLT first.  In an SY table, column 1
is time, column 3 is source, column 4 is antenna, column 7 is RR Pdif,
column 8 is RR Psum, column 10 is LL Pdif, and column 11 is LL Psum.
To plot Psys RR versus Psys LL (Psys = 0.5*Psum/Pdif * Tcal) you will
have to look up the Tcals in the CD table.  Then
      INEXT = 'SY'; XINC 1
      APARM 8,n,7,n,13,  11,n,10,n,13
      BPARM 0
      CPARM 0; CPARM(9) ~ TcalR/2, TcalL/2
      RPARM 4,1,Ant,0.1
where n is the desired IF (spectral window) and Ant is the desired
antenna.  A simpler plot would be, e.g. Psum on the X axis and Pdif on
the Y for RR:
      APARM 8,n,0,0,0,  7,n,0,0,0
      BPARM=0
      CPARM=0
      RPARM 4,1,Ant,0.1
or
      RPARM=0
for all antennas.

